Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(sdks): surface Alexandria feedback tokens and accept them in Alexandria feedback (#5600)
Nicolas590d7f9c7084
diff --git a/apps/js-sdk/firecrawl/README.md b/apps/js-sdk/firecrawl/README.mdindex 581fc4747..9da53ccba 100644--- a/apps/js-sdk/firecrawl/README.md+++ b/apps/js-sdk/firecrawl/README.md@@ -480,3 +480,24 @@ uses its published price. A provider whose data terms have not been accepted rejcall with a 403 whose `SdkError` carries `code: "THIRD_PARTY_DATA_TERMS_REQUIRED"` and a`requiresAction: { type: "accept_terms", terms, version, url }` pointing at the page wherean organization admin can accept them.++Each Alexandria call result can carry an opaque `feedbackToken`, valid for 24 hours. It is+absent under zero data retention. Pass the tokens of the calls in a session to+`alexandriaFeedback`: `tokens` (at most 20, newest last) are covered by the session+`rating`, and `callRatings` (at most 20) rate individual calls. The response includes+`rejectedTokens` when some tokens failed verification.++```ts+import { collectFeedbackTokens } from "@mendable/firecrawl-js";++const response = await firecrawl.alexandriaFeedback({+ rating: "partial",+ requestedWebsite: { url: "https://example.com", requestedFunctionality: "Find episodes" },+ rationale: "Found the episodes but the dates were missing",+ tokens: collectFeedbackTokens(result.alexandria),+ callRatings: result.alexandria[0].feedbackToken+ ? [{ token: result.alexandria[0].feedbackToken, rating: "bad" }]+ : undefined,+});+console.log(response.rejectedTokens ?? 0);+```diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex e29b28d09..3a6984866 100644--- a/apps/js-sdk/firecrawl/package.json+++ b/apps/js-sdk/firecrawl/package.json@@ -1,6 +1,6 @@{"name": "@mendable/firecrawl-js",- "version": "4.52.0",+ "version": "4.53.0","description": "JavaScript SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and search scientific papers (PubMed, bioRxiv, medRxiv, arXiv)","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/alexandria-feedback.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/alexandria-feedback.unit.test.tsnew file mode 100644index 000000000..9bb97d752--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/alexandria-feedback.unit.test.ts@@ -0,0 +1,234 @@+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";+import { createServer, type Server } from "node:http";+import { FirecrawlClient, collectFeedbackTokens } from "../../../index";++let server: Server;+let client: FirecrawlClient;+const sent: Array<{ url?: string; body: any }> = [];+let reply: { status: number; body: unknown } = { status: 200, body: {} };++const feedbackResponse = {+ success: true,+ feedbackId: "feedback-1",+ creditsRefunded: 0,+};+const base = {+ rating: "good" as const,+ requestedWebsite: {+ url: "https://example.com",+ requestedFunctionality: "Find episodes",+ },+ rationale: "Returned what was needed",+};++beforeAll(async () => {+ server = createServer(async (req, res) => {+ let raw = "";+ for await (const chunk of req) raw += chunk;+ const body = JSON.parse(raw);+ sent.push({ url: req.url, body });+ res.setHeader("content-type", "application/json");+ if (req.url === "/v2/feedback") {+ res.statusCode = reply.status;+ return res.end(JSON.stringify(reply.body));+ }+ const provider = body.alexandria[0].provider;+ const alexandria =+ provider === "firecrawl"+ ? [+ {+ provider,+ capability: "find-tools",+ creditsCost: 0,+ feedbackToken: "meta-token",+ data: { level: "providers", items: [], total: 0, next: null },+ },+ ]+ : [+ {+ provider: "particle",+ capability: "a/b",+ creditsCost: 15,+ feedbackToken: "token-ok",+ data: {},+ },+ {+ provider: "x",+ capability: "b",+ feedbackToken: "token-error",+ error: { code: "unavailable", message: "Unavailable" },+ },+ { provider: "y", capability: "c", creditsCost: 1, data: {} },+ ];+ res.end(+ JSON.stringify({+ success: true,+ scrape_id: "scrape-1",+ data: { alexandria, creditsCost: 15 },+ }),+ );+ });+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));+ const port = (server.address() as { port: number }).port;+ client = new FirecrawlClient({+ apiKey: "fc-test",+ apiUrl: `http://127.0.0.1:${port}`,+ backoffFactor: 0,+ });+});+afterAll(async () => {+ await new Promise<void>((resolve) => server.close(() => resolve()));+});+beforeEach(() => {+ sent.length = 0;+ reply = { status: 200, body: feedbackResponse };+});++describe("Alexandria feedback tokens", () => {+ test("scrape keeps feedbackToken on successful and errored results", async () => {+ const result = await client.scrape({+ alexandria: [+ { provider: "particle", capability: "a/b" },+ { provider: "x", capability: "b" },+ { provider: "y", capability: "c" },+ ],+ });+ expect(result.alexandria.map((item) => item.feedbackToken)).toEqual([+ "token-ok",+ "token-error",+ undefined,+ ]);+ });++ test("findTools passes through the token of the meta call", async () => {+ const found = await client.findTools({ providers: ["particle"] });+ expect(found.feedbackToken).toBe("meta-token");+ });++ test("collectFeedbackTokens skips missing, dedupes, and keeps the newest 20", () => {+ const results = Array.from({ length: 25 }, (_, i) => ({+ feedbackToken: `t${i}`,+ }));+ const collected = collectFeedbackTokens([+ { feedbackToken: "dup" },+ {},+ undefined,+ ...results,+ { feedbackToken: "dup" },+ ]);+ expect(collected).toHaveLength(20);+ expect(collected.at(-1)).toBe("dup");+ expect(collected.at(-2)).toBe("t24");+ expect(collected[0]).toBe("t6");+ expect(collectFeedbackTokens([{}, { feedbackToken: "" }])).toEqual([]);+ });+});++describe("alexandriaFeedback", () => {+ test("posts endpoint alexandria with tokens and callRatings", async () => {+ reply.body = { ...feedbackResponse, rejectedTokens: 1 };+ const response = await client.alexandriaFeedback({+ ...base,+ objective: "Find episodes",+ tokens: ["a", "b"],+ callRatings: [{ token: "c", rating: "bad" }],+ providerFeedback: [+ { name: "particle", issue: "insufficient_coverage", why: "Gaps" },+ ],+ });+ expect(sent).toHaveLength(1);+ expect(sent[0].url).toBe("/v2/feedback");+ expect(sent[0].body).toMatchObject({+ endpoint: "alexandria",+ rating: "good",+ requestedWebsite: base.requestedWebsite,+ rationale: base.rationale,+ objective: "Find episodes",+ tokens: ["a", "b"],+ callRatings: [{ token: "c", rating: "bad" }],+ providerFeedback: [+ { name: "particle", issue: "insufficient_coverage", why: "Gaps" },+ ],+ });+ expect(typeof sent[0].body.origin).toBe("string");+ expect(response.rejectedTokens).toBe(1);+ expect(response.feedbackId).toBe("feedback-1");+ });++ test("works without tokens, as before", async () => {+ const response = await client.alexandriaFeedback(base);+ expect(sent[0].body).not.toHaveProperty("tokens");+ expect(sent[0].body).not.toHaveProperty("callRatings");+ expect(response.rejectedTokens).toBeUndefined();+ });++ test("accepts exactly 20 tokens and 20 callRatings", async () => {+ await client.alexandriaFeedback({+ ...base,+ tokens: Array.from({ length: 20 }, (_, i) => `t${i}`),+ callRatings: Array.from({ length: 20 }, (_, i) => ({+ token: `c${i}`,+ rating: "partial" as const,+ })),+ });+ expect(sent[0].body.tokens).toHaveLength(20);+ expect(sent[0].body.callRatings).toHaveLength(20);+ });++ test("accepts a token of exactly 1024 characters", async () => {+ await client.alexandriaFeedback({ ...base, tokens: ["x".repeat(1024)] });+ expect(sent[0].body.tokens[0]).toHaveLength(1024);+ });++ test("requires requestedFunctionality for new_capability_request", async () => {+ const entry = {+ name: "episodes",+ provider: "particle",+ issue: "new_capability_request" as const,+ why: "Needed",+ };+ await expect(+ client.alexandriaFeedback({+ ...base,+ capabilityFeedback: [entry as any],+ }),+ ).rejects.toThrow("requestedFunctionality is required");+ expect(sent).toHaveLength(0);+ await client.alexandriaFeedback({+ ...base,+ capabilityFeedback: [{ ...entry, requestedFunctionality: "Dates" }],+ });+ expect(sent[0].body.capabilityFeedback[0].requestedFunctionality).toBe(+ "Dates",+ );+ });++ test.each([+ ["21 tokens", { tokens: Array.from({ length: 21 }, (_, i) => `t${i}`) }, "tokens accepts at most 20"],+ [+ "21 callRatings",+ { callRatings: Array.from({ length: 21 }, (_, i) => ({ token: `c${i}`, rating: "good" as const })) },+ "callRatings accepts at most 20",+ ],+ ["empty token", { tokens: [""] }, "tokens[0] must be a string"],+ ["oversized token", { tokens: ["x".repeat(1025)] }, "tokens[0] must be a string"],+ [+ "invalid call rating",+ { callRatings: [{ token: "a", rating: "great" as any }] },+ "rating must be one of",+ ],+ ["invalid rating", { rating: "great" as any }, "rating must be one of"],+ ])("rejects %s before dispatch", async (_name, override, message) => {+ await expect(+ client.alexandriaFeedback({ ...base, ...override }),+ ).rejects.toThrow(message);+ expect(sent).toHaveLength(0);+ });++ test("surfaces API errors", async () => {+ reply = { status: 400, body: { success: false, error: "Invalid request" } };+ await expect(client.alexandriaFeedback(base)).rejects.toMatchObject({+ status: 400,+ });+ });+});diff --git a/apps/js-sdk/firecrawl/src/index.ts b/apps/js-sdk/firecrawl/src/index.tsindex 0250f0826..49ff8decb 100644--- a/apps/js-sdk/firecrawl/src/index.ts+++ b/apps/js-sdk/firecrawl/src/index.ts@@ -11,6 +11,8 @@ export { FirecrawlClient } from "./v2/client";export * from "./v2/types";/** Watcher class and options for crawl/batch job monitoring. */export { Watcher, type WatcherOptions } from "./v2/watcher";+/** Collects Alexandria feedback tokens from call results for a session rating. */+export { collectFeedbackTokens } from "./v2/utils/feedbackTokens";/** Research sub-client (accessed via `firecrawl.research`). */export { ResearchClient } from "./v2/methods/research";/** Legacy v1 client (feature‑frozen). */diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.tsindex af9f19003..00296182d 100644--- a/apps/js-sdk/firecrawl/src/v2/client.ts+++ b/apps/js-sdk/firecrawl/src/v2/client.ts@@ -10,7 +10,11 @@ import { scrapeAlexandria, findTools } from "./methods/tools";import { developerSearch as developerSearchMethod } from "./methods/developer";import { govSearch as govSearchMethod } from "./methods/gov";import { map as mapMethod } from "./methods/map";-import { feedback as feedbackMethod, searchFeedback as searchFeedbackMethod } from "./methods/feedback";+import {+ alexandriaFeedback as alexandriaFeedbackMethod,+ feedback as feedbackMethod,+ searchFeedback as searchFeedbackMethod,+} from "./methods/feedback";import {startCrawl,getCrawlStatus,@@ -63,6 +67,8 @@ import type {DeveloperSearchResponse,GovSearchOptions,GovSearchResponse,+ AlexandriaFeedbackRequest,+ AlexandriaFeedbackResponse,EndpointFeedbackRequest,FeedbackResponse,SearchFeedbackRequest,@@ -340,6 +346,18 @@ export class FirecrawlClient {return feedbackMethod(this.http, request);}+ /**+ * Rate Alexandria calls. Pass the `feedbackToken` of each call result in+ * `tokens` (session rating) or `callRatings` (per-call rating).+ * @param request Alexandria feedback payload.+ * @returns Feedback record, refund details, and the count of rejected tokens.+ */+ async alexandriaFeedback(+ request: AlexandriaFeedbackRequest,+ ): Promise<AlexandriaFeedbackResponse> {+ return alexandriaFeedbackMethod(this.http, request);+ }+/*** Submit feedback for a search job.* @param jobId Search job id returned by search.diff --git a/apps/js-sdk/firecrawl/src/v2/methods/feedback.ts b/apps/js-sdk/firecrawl/src/v2/methods/feedback.tsindex 7af68a10a..f3d3d7681 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/feedback.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/feedback.ts@@ -1,9 +1,12 @@import {+ type AlexandriaFeedbackRequest,+ type AlexandriaFeedbackResponse,type EndpointFeedbackRequest,type FeedbackResponse,type SearchFeedbackRequest,} from "../types";import { HttpClient } from "../utils/httpClient";+import { ALEXANDRIA_FEEDBACK_MAX_TOKENS } from "../utils/feedbackTokens";import {normalizeAxiosError,throwForBadResponse,@@ -57,3 +60,71 @@ export async function searchFeedback(throw err;}}++const ALEXANDRIA_FEEDBACK_MAX_TOKEN_LENGTH = 1024;++function validateToken(token: unknown, label: string): void {+ if (+ typeof token !== "string" ||+ token.length === 0 ||+ token.length > ALEXANDRIA_FEEDBACK_MAX_TOKEN_LENGTH+ ) {+ throw new Error(+ `${label} must be a string of 1 to ${ALEXANDRIA_FEEDBACK_MAX_TOKEN_LENGTH} characters`,+ );+ }+}++export async function alexandriaFeedback(+ http: HttpClient,+ request: AlexandriaFeedbackRequest,+): Promise<AlexandriaFeedbackResponse> {+ validateRating(request.rating);+ const { tokens, callRatings } = request;+ if (tokens != null) {+ if (!Array.isArray(tokens)) throw new Error("tokens must be an array");+ if (tokens.length > ALEXANDRIA_FEEDBACK_MAX_TOKENS) {+ throw new Error(+ `tokens accepts at most ${ALEXANDRIA_FEEDBACK_MAX_TOKENS} entries`,+ );+ }+ tokens.forEach((token, index) => validateToken(token, `tokens[${index}]`));+ }+ request.capabilityFeedback?.forEach((entry, index) => {+ if (+ entry?.issue === "new_capability_request" &&+ !entry.requestedFunctionality?.trim()+ ) {+ throw new Error(+ `capabilityFeedback[${index}].requestedFunctionality is required for new_capability_request`,+ );+ }+ });+ if (callRatings != null) {+ if (!Array.isArray(callRatings))+ throw new Error("callRatings must be an array");+ if (callRatings.length > ALEXANDRIA_FEEDBACK_MAX_TOKENS) {+ throw new Error(+ `callRatings accepts at most ${ALEXANDRIA_FEEDBACK_MAX_TOKENS} entries`,+ );+ }+ callRatings.forEach((entry, index) => {+ validateToken(entry?.token, `callRatings[${index}].token`);+ validateRating(entry.rating);+ });+ }++ try {+ const res = await http.post<AlexandriaFeedbackResponse>("/v2/feedback", {+ ...request,+ endpoint: "alexandria",+ });+ if (res.status !== 200 || !res.data?.success) {+ throwForBadResponse(res, "alexandriaFeedback");+ }+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "alexandriaFeedback");+ throw err;+ }+}diff --git a/apps/js-sdk/firecrawl/src/v2/methods/tools.ts b/apps/js-sdk/firecrawl/src/v2/methods/tools.tsindex 2b8db534c..91bf0c782 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/tools.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/tools.ts@@ -141,5 +141,8 @@ export async function findTools(new SdkError(item.error.message, item.error.status, item.error.code),{ requestId: result.requestId },);- return item.data as FindToolsData;+ const data = item.data as FindToolsData;+ return item.feedbackToken+ ? { ...data, feedbackToken: item.feedbackToken }+ : data;}diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 9dfaf597d..34c1dba82 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -978,6 +978,8 @@ export interface FindToolsData {}>;total: number;next: AlexandriaCall | null;+ /** Opaque feedback token of this find-tools call. Absent when the API issues none. */+ feedbackToken?: string;}export interface AlexandriaScrapeRequest extends AlexandriaOptions {@@ -1007,12 +1009,15 @@ export type AlexandriaScrapeResult =records?: number;upstreamStatus?: number;recordedAt?: string;+ /** Opaque token to pass to `alexandriaFeedback`. Absent under zero data retention. */+ feedbackToken?: string;error?: undefined;[key: string]: unknown;}| {provider?: string;capability?: string;+ feedbackToken?: string;error: AlexandriaScrapeError;[key: string]: unknown;};@@ -1243,6 +1248,60 @@ export interface FeedbackResponse {warning?: string;}+export interface AlexandriaProviderFeedback {+ name: string;+ issue:+ | "missing_provider"+ | "insufficient_coverage"+ | "provider_unavailable"+ | "other";+ why: string;+}++export type AlexandriaCapabilityFeedback = {+ name: string;+ provider: string;+ why: string;+} & (+ | { issue: "new_capability_request"; requestedFunctionality: string }+ | {+ issue:+ | "missing_capability"+ | "insufficient_functionality"+ | "incorrect_result"+ | "execution_error"+ | "other";+ requestedFunctionality?: string;+ }+);++export interface AlexandriaCallRating {+ /** The `feedbackToken` of an Alexandria call result. */+ token: string;+ rating: FeedbackRating;+}++export interface AlexandriaFeedbackRequest {+ /** Session-level rating, applied to every call in `tokens`. */+ rating: FeedbackRating;+ requestedWebsite: { url: string; requestedFunctionality: string };+ rationale: string;+ objective?: string;+ providerFeedback?: AlexandriaProviderFeedback[];+ capabilityFeedback?: AlexandriaCapabilityFeedback[];+ /** Tokens of the calls `rating` covers: at most 20, newest last. */+ tokens?: string[];+ /** Per-call ratings: at most 20. A token here need not also be in `tokens`. */+ callRatings?: AlexandriaCallRating[];+ integration?: string | null;+ origin?: string;+}++export interface AlexandriaFeedbackResponse extends FeedbackResponse {+ /** Tokens that failed verification (expired, other team, or forged). */+ rejectedTokens?: number;+}+/*** Schedule for a monitor.*diff --git a/apps/js-sdk/firecrawl/src/v2/utils/feedbackTokens.ts b/apps/js-sdk/firecrawl/src/v2/utils/feedbackTokens.tsnew file mode 100644index 000000000..8c1340ea9--- /dev/null+++ b/apps/js-sdk/firecrawl/src/v2/utils/feedbackTokens.ts@@ -0,0 +1,19 @@+export const ALEXANDRIA_FEEDBACK_MAX_TOKENS = 20;++/**+ * Collects feedback tokens from Alexandria call results for a session rating:+ * skips results without one, dedupes, and keeps the newest 20 (newest last).+ */+export function collectFeedbackTokens(+ results: ReadonlyArray<{ feedbackToken?: string } | null | undefined>,+): string[] {+ const tokens: string[] = [];+ for (const result of results) {+ const token = result?.feedbackToken;+ if (!token) continue;+ const seen = tokens.indexOf(token);+ if (seen !== -1) tokens.splice(seen, 1);+ tokens.push(token);+ }+ return tokens.slice(-ALEXANDRIA_FEEDBACK_MAX_TOKENS);+}diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.mdindex d41c92a4b..d6767c252 100644--- a/apps/python-sdk/README.md+++ b/apps/python-sdk/README.md@@ -488,3 +488,28 @@ execute a selected tool, or pass a list of up to ten calls. Check each item's`error` before using `data`. Results and execution exceptions expose `request_id`;reuse it with the identical payload when retrying. Automatic retries retain it.The same methods are available with `await` on `AsyncFirecrawl`.++Each Alexandria call result can carry an opaque `feedback_token`, valid for 24 hours. It+is absent under zero data retention. Pass the tokens of the calls in a session to+`alexandria_feedback`: `tokens` (at most 20, newest last) are covered by the session+`rating`, and `call_ratings` (at most 20) rate individual calls. The response includes+`rejected_tokens` when some tokens failed verification.++```python+from firecrawl import collect_feedback_tokens++scraped = firecrawl.scrape(alexandria={+ "provider": "particle",+ "capability": "podcasts/episodes/search",+ "options": {"semantic_search": "AI agents"},+})+first_token = scraped.alexandria[0].feedback_token+response = firecrawl.alexandria_feedback({+ "rating": "partial",+ "requested_website": {"url": "https://example.com", "requested_functionality": "Find episodes"},+ "rationale": "Found the episodes but the dates were missing",+ "tokens": collect_feedback_tokens(scraped.alexandria),+ "call_ratings": [{"token": first_token, "rating": "bad"}] if first_token else None,+})+print(response.rejected_tokens or 0)+```diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex 58246c7fb..888f56eb7 100644--- a/apps/python-sdk/firecrawl/__init__.py+++ b/apps/python-sdk/firecrawl/__init__.py@@ -8,6 +8,7 @@ import osfrom .client import Firecrawl, AsyncFirecrawl, FirecrawlApp, AsyncFirecrawlAppfrom .v2.utils.v1_compat import ScrapeOptions+from .v2.methods.feedback import collect_feedback_tokensfrom .v2.watcher import Watcherfrom .v2.watcher_async import AsyncWatcherfrom .v2.types import (@@ -16,6 +17,12 @@ from .v2.types import (FindToolsData,AlexandriaCall,AlexandriaError,+ AlexandriaCallRating,+ AlexandriaCapabilityFeedback,+ AlexandriaFeedbackRequest,+ AlexandriaFeedbackResponse,+ AlexandriaProviderFeedback,+ AlexandriaRequestedWebsite,AlexandriaScrapeData,AlexandriaScrapeResult,ExchangeSearchResult,@@ -42,7 +49,7 @@ from .v1 import (V1ChangeTrackingOptions,)-__version__ = "4.55.0"+__version__ = "4.56.0"# Define the logger for the Firecrawl projectlogger: logging.Logger = logging.getLogger("firecrawl")@@ -110,7 +117,14 @@ __all__ = ['FindToolsData','AlexandriaCall','AlexandriaError',+ 'AlexandriaCallRating',+ 'AlexandriaCapabilityFeedback',+ 'AlexandriaFeedbackRequest',+ 'AlexandriaFeedbackResponse',+ 'AlexandriaProviderFeedback',+ 'AlexandriaRequestedWebsite','AlexandriaScrapeData',+ 'collect_feedback_tokens','AlexandriaScrapeResult','ExchangeSearchResult','CrawlJobTimeoutError',diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_alexandria_feedback.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_alexandria_feedback.pynew file mode 100644index 000000000..1df5447cb--- /dev/null+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_alexandria_feedback.py@@ -0,0 +1,232 @@+from unittest.mock import Mock++import httpx+import pytest++from firecrawl import AsyncFirecrawl, Firecrawl, collect_feedback_tokens+from firecrawl.v2.types import AlexandriaScrapeResult++REQUEST = {+ "rating": "good",+ "requested_website": {"url": "https://example.com", "requested_functionality": "Find episodes"},+ "rationale": "Returned what was needed",+}+FEEDBACK_RESPONSE = {"success": True, "feedbackId": "feedback-1", "creditsRefunded": 0}+SCRAPE_DATA = {+ "alexandria": [+ {"provider": "particle", "capability": "a/b", "creditsCost": 15, "feedbackToken": "token-ok", "data": {}},+ {+ "provider": "x",+ "capability": "b",+ "feedbackToken": "token-error",+ "error": {"code": "unavailable", "message": "Unavailable"},+ },+ {"provider": "y", "capability": "c", "creditsCost": 1, "data": {}},+ ],+ "creditsCost": 15,+}+FIND_TOOLS_DATA = {+ "alexandria": [+ {+ "provider": "firecrawl",+ "capability": "find-tools",+ "creditsCost": 0,+ "feedbackToken": "meta-token",+ "data": {"level": "providers", "items": [], "total": 0, "next": None},+ }+ ],+ "creditsCost": 0,+}+++def response(status, data):+ result = Mock(status_code=status)+ result.json.return_value = data+ return result+++def test_scrape_result_keeps_feedback_token():+ result = AlexandriaScrapeResult(**SCRAPE_DATA["alexandria"][0])+ assert result.feedback_token == "token-ok"+ assert AlexandriaScrapeResult(**SCRAPE_DATA["alexandria"][2]).feedback_token is None++[email protected]("async_client", [False, True])+async def test_scrape_and_find_tools_surface_tokens(async_client, monkeypatch):+ def payload(body):+ provider = body["alexandria"][0]["provider"]+ data = FIND_TOOLS_DATA if provider == "firecrawl" else SCRAPE_DATA+ return {"success": True, "scrape_id": "scrape-1", "data": data}++ calls = [{"provider": "particle", "capability": "a/b"}]+ if async_client:+ client = AsyncFirecrawl(api_key="fc-test")+ try:+ async def post(url, **kwargs):+ return httpx.Response(200, json=payload(kwargs["json"]))++ monkeypatch.setattr(client._v2_client.async_http_client._client, "post", post)+ scraped = await client.scrape(alexandria=calls)+ found = await client.find_tools()+ finally:+ await client._v2_client.async_http_client.close()+ else:+ monkeypatch.setattr("requests.post", lambda url, **kwargs: response(200, payload(kwargs["json"])))+ client = Firecrawl(api_key="fc-test")+ scraped = client.scrape(alexandria=calls)+ found = client.find_tools()+ assert [item.feedback_token for item in scraped.alexandria] == ["token-ok", "token-error", None]+ assert found.feedback_token == "meta-token"+++def test_collect_feedback_tokens_dedupes_and_keeps_newest_twenty():+ results = [AlexandriaScrapeResult(feedbackToken="dup"), AlexandriaScrapeResult()]+ results += [AlexandriaScrapeResult(feedbackToken=f"t{i}") for i in range(25)]+ results.append(AlexandriaScrapeResult(feedbackToken="dup"))+ collected = collect_feedback_tokens(results)+ assert len(collected) == 20+ assert collected[0] == "t6"+ assert collected[-2:] == ["t24", "dup"]+ assert collect_feedback_tokens([AlexandriaScrapeResult()]) == []+++def test_collect_feedback_tokens_accepts_plain_dicts():+ results = [{"feedbackToken": "a"}, {"feedback_token": "b"}, {}, {"feedbackToken": "a"}]+ assert collect_feedback_tokens(results) == ["b", "a"]+++def test_alexandria_feedback_accepts_token_of_exactly_1024_chars(monkeypatch):+ sent = []+ monkeypatch.setattr(+ "requests.post", lambda url, **kwargs: sent.append(kwargs["json"]) or response(200, FEEDBACK_RESPONSE)+ )+ Firecrawl(api_key="fc-test").alexandria_feedback({**REQUEST, "tokens": ["x" * 1024]})+ assert len(sent[0]["tokens"][0]) == 1024+++def test_alexandria_feedback_requires_functionality_for_new_capability_request(monkeypatch):+ post = Mock(return_value=response(200, FEEDBACK_RESPONSE))+ monkeypatch.setattr("requests.post", post)+ entry = {"name": "episodes", "provider": "particle", "issue": "new_capability_request", "why": "Needed"}+ client = Firecrawl(api_key="fc-test")+ with pytest.raises(ValueError, match="requested_functionality is required"):+ client.alexandria_feedback({**REQUEST, "capability_feedback": [entry]})+ post.assert_not_called()+ client.alexandria_feedback(+ {**REQUEST, "capability_feedback": [{**entry, "requested_functionality": "Dates"}]}+ )+ assert post.call_args.kwargs["json"]["capabilityFeedback"][0]["requestedFunctionality"] == "Dates"+++def test_alexandria_feedback_trims_text_and_rejects_blank(monkeypatch):+ post = Mock(return_value=response(200, FEEDBACK_RESPONSE))+ monkeypatch.setattr("requests.post", post)+ client = Firecrawl(api_key="fc-test")+ with pytest.raises(ValueError):+ client.alexandria_feedback({**REQUEST, "rationale": " "})+ post.assert_not_called()+ client.alexandria_feedback({**REQUEST, "rationale": " ok "})+ assert post.call_args.kwargs["json"]["rationale"] == "ok"++[email protected]("async_client", [False, True])+async def test_alexandria_feedback_posts_tokens_and_call_ratings(async_client, monkeypatch):+ sent = []+ body = {**FEEDBACK_RESPONSE, "rejectedTokens": 1}+ request = {+ **REQUEST,+ "objective": "Find episodes",+ "tokens": ["a", "b"],+ "call_ratings": [{"token": "c", "rating": "bad"}],+ "provider_feedback": [{"name": "particle", "issue": "insufficient_coverage", "why": "Gaps"}],+ }+ if async_client:+ client = AsyncFirecrawl(api_key="fc-test")+ try:+ async def post(url, **kwargs):+ sent.append((url, kwargs["json"]))+ return httpx.Response(200, json=body)++ monkeypatch.setattr(client._v2_client.async_http_client._client, "post", post)+ result = await client.alexandria_feedback(request)+ finally:+ await client._v2_client.async_http_client.close()+ else:+ def post(url, **kwargs):+ sent.append((url, kwargs["json"]))+ return response(200, body)++ monkeypatch.setattr("requests.post", post)+ result = Firecrawl(api_key="fc-test").alexandria_feedback(request)+ url, payload = sent[0]+ assert url.endswith("/v2/feedback")+ assert payload["endpoint"] == "alexandria"+ assert payload["rating"] == "good"+ assert payload["requestedWebsite"] == {"url": "https://example.com", "requestedFunctionality": "Find episodes"}+ assert payload["rationale"] == "Returned what was needed"+ assert payload["objective"] == "Find episodes"+ assert payload["tokens"] == ["a", "b"]+ assert payload["callRatings"] == [{"token": "c", "rating": "bad"}]+ assert payload["providerFeedback"] == [{"name": "particle", "issue": "insufficient_coverage", "why": "Gaps"}]+ assert isinstance(payload["origin"], str) and payload["origin"]+ assert result.rejected_tokens == 1+ assert result.feedback_id == "feedback-1"+++def test_alexandria_feedback_without_tokens_omits_them(monkeypatch):+ sent = []+ monkeypatch.setattr(+ "requests.post", lambda url, **kwargs: sent.append(kwargs["json"]) or response(200, FEEDBACK_RESPONSE)+ )+ result = Firecrawl(api_key="fc-test").alexandria_feedback(REQUEST)+ assert "tokens" not in sent[0]+ assert "callRatings" not in sent[0]+ assert result.rejected_tokens is None+++def test_alexandria_feedback_accepts_camel_case_and_exactly_twenty(monkeypatch):+ sent = []+ monkeypatch.setattr(+ "requests.post", lambda url, **kwargs: sent.append(kwargs["json"]) or response(200, FEEDBACK_RESPONSE)+ )+ Firecrawl(api_key="fc-test").alexandria_feedback(+ {+ "rating": "partial",+ "requestedWebsite": {"url": "https://example.com", "requestedFunctionality": "x"},+ "rationale": "y",+ "tokens": [f"t{i}" for i in range(20)],+ "callRatings": [{"token": f"c{i}", "rating": "good"} for i in range(20)],+ }+ )+ assert len(sent[0]["tokens"]) == 20+ assert len(sent[0]["callRatings"]) == 20+++ "override",+ [+ {"tokens": [f"t{i}" for i in range(21)]},+ {"call_ratings": [{"token": f"c{i}", "rating": "good"} for i in range(21)]},+ {"tokens": [""]},+ {"tokens": ["x" * 1025]},+ {"call_ratings": [{"token": "a", "rating": "great"}]},+ {"rating": "great"},+ ],+)+def test_alexandria_feedback_validates_before_dispatch(override, monkeypatch):+ post = Mock()+ monkeypatch.setattr("requests.post", post)+ with pytest.raises(ValueError):+ Firecrawl(api_key="fc-test").alexandria_feedback({**REQUEST, **override})+ post.assert_not_called()+++def test_alexandria_feedback_raises_on_api_error(monkeypatch):+ monkeypatch.setattr(+ "requests.post", lambda url, **kwargs: response(400, {"success": False, "error": "Invalid request"})+ )+ with pytest.raises(Exception) as caught:+ Firecrawl(api_key="fc-test").alexandria_feedback(REQUEST)+ assert caught.value.status_code == 400diff --git a/apps/python-sdk/firecrawl/client.py b/apps/python-sdk/firecrawl/client.pyindex e8cb558e7..32dda480a 100644--- a/apps/python-sdk/firecrawl/client.py+++ b/apps/python-sdk/firecrawl/client.py@@ -75,6 +75,7 @@ class V2Proxy:self.scrape = client_instance.scrapeself.scrape_alexandria = client_instance.scrape_alexandriaself.find_tools = client_instance.find_tools+ self.alexandria_feedback = client_instance.alexandria_feedbackself.interact = client_instance.interactself.stop_interaction = client_instance.stop_interactionself.stop_interactive_browser = client_instance.stop_interactive_browser@@ -169,6 +170,7 @@ class AsyncV2Proxy:self.scrape = client_instance.scrapeself.scrape_alexandria = client_instance.scrape_alexandriaself.find_tools = client_instance.find_tools+ self.alexandria_feedback = client_instance.alexandria_feedbackself.interact = client_instance.interactself.stop_interaction = client_instance.stop_interactionself.stop_interactive_browser = client_instance.stop_interactive_browser@@ -292,6 +294,7 @@ class Firecrawl:self.scrape = self._v2_client.scrapeself.scrape_alexandria = self._v2_client.scrape_alexandriaself.find_tools = self._v2_client.find_tools+ self.alexandria_feedback = self._v2_client.alexandria_feedbackself.interact = self._v2_client.interactself.stop_interaction = self._v2_client.stop_interactionself.stop_interactive_browser = self._v2_client.stop_interactive_browser@@ -453,6 +456,7 @@ class AsyncFirecrawl:self.scrape = self._v2_client.scrapeself.scrape_alexandria = self._v2_client.scrape_alexandriaself.find_tools = self._v2_client.find_tools+ self.alexandria_feedback = self._v2_client.alexandria_feedbackself.interact = self._v2_client.interactself.stop_interaction = self._v2_client.stop_interactionself.stop_interactive_browser = self._v2_client.stop_interactive_browserdiff --git a/apps/python-sdk/firecrawl/v2/__init__.py b/apps/python-sdk/firecrawl/v2/__init__.pyindex 6ea02b846..5f799810f 100644--- a/apps/python-sdk/firecrawl/v2/__init__.py+++ b/apps/python-sdk/firecrawl/v2/__init__.py@@ -1,10 +1,17 @@from .client import FirecrawlClientfrom .client_async import AsyncFirecrawlClient+from .methods.feedback import collect_feedback_tokensfrom .types import (DiscoveredTool,FindToolsData,AlexandriaCall,AlexandriaError,+ AlexandriaCallRating,+ AlexandriaCapabilityFeedback,+ AlexandriaFeedbackRequest,+ AlexandriaFeedbackResponse,+ AlexandriaProviderFeedback,+ AlexandriaRequestedWebsite,AlexandriaScrapeData,AlexandriaScrapeResult,ExchangeSearchResult,@@ -17,7 +24,14 @@ __all__ = ["FindToolsData","AlexandriaCall","AlexandriaError",+ "AlexandriaCallRating",+ "AlexandriaCapabilityFeedback",+ "AlexandriaFeedbackRequest",+ "AlexandriaFeedbackResponse",+ "AlexandriaProviderFeedback",+ "AlexandriaRequestedWebsite","AlexandriaScrapeData","AlexandriaScrapeResult",+ "collect_feedback_tokens","ExchangeSearchResult",]diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 5d28b8cce..5ba265aea 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -23,6 +23,8 @@ from .types import (CategoryOption,FindToolsData,AlexandriaCall,+ AlexandriaFeedbackRequest,+ AlexandriaFeedbackResponse,AlexandriaScrapeData,CrawlRequest,CrawlResponse,@@ -81,6 +83,7 @@ from .methods import agent as agent_modulefrom .methods import browser as browser_modulefrom .methods import monitor as monitor_modulefrom .methods import research as research_module+from .methods import feedback as feedback_modulefrom .methods.research_docs import (CLIENT_INSPECT_PAPER_DOC,CLIENT_READ_PAPER_DOC,@@ -294,6 +297,20 @@ class FirecrawlClient:self.http_client, calls, timeout=timeout, integration=integration, request_id=request_id)+ def alexandria_feedback(+ self, request: Union[AlexandriaFeedbackRequest, Dict[str, Any]]+ ) -> AlexandriaFeedbackResponse:+ """+ Rate Alexandria calls.++ Pass the ``feedback_token`` of each call result in ``tokens`` (session rating,+ at most 20, newest last) or ``call_ratings`` (per-call ratings, at most 20).++ Returns:+ AlexandriaFeedbackResponse, including rejected_tokens when some tokens failed verification+ """+ return feedback_module.alexandria_feedback(self.http_client, request)+def find_tools(self, **options) -> FindToolsData:"""Explore providers and contracts without executing discovered tools.@@ -312,7 +329,7 @@ class FirecrawlClient:code=item.error.code,charge_id=item.error.charge_id,)- return FindToolsData(**item.data)+ return FindToolsData(**item.data, feedback_token=item.feedback_token)# Research paper index (/v2/search/research)@doc(CLIENT_SEARCH_PAPERS_DOC)diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex 53babc234..c4eb8bc21 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -25,6 +25,8 @@ from .types import (SourceOption,FindToolsData,AlexandriaCall,+ AlexandriaFeedbackRequest,+ AlexandriaFeedbackResponse,AlexandriaScrapeData,CrawlResponse,CrawlJob,@@ -76,6 +78,7 @@ from .methods.aio import agent as async_agent # type: ignore[attr-defined]from .methods.aio import browser as async_browser # type: ignore[attr-defined]from .methods.aio import monitor as async_monitor # type: ignore[attr-defined]from .methods.aio import research as async_research # type: ignore[attr-defined]+from .methods.aio import feedback as async_feedback # type: ignore[attr-defined]from .methods.research_docs import (ASYNC_CLIENT_INSPECT_PAPER_DOC,ASYNC_CLIENT_READ_PAPER_DOC,@@ -163,6 +166,12 @@ class AsyncFirecrawlClient:self.async_http_client, calls, timeout=timeout, integration=integration, request_id=request_id)+ async def alexandria_feedback(+ self, request: Union[AlexandriaFeedbackRequest, Dict[str, Any]]+ ) -> AlexandriaFeedbackResponse:+ """Rate Alexandria calls. See FirecrawlClient.alexandria_feedback."""+ return await async_feedback.alexandria_feedback(self.async_http_client, request)+async def find_tools(self, **options) -> FindToolsData:"""Explore providers and contracts without executing discovered tools.@@ -181,7 +190,7 @@ class AsyncFirecrawlClient:code=item.error.code,charge_id=item.error.charge_id,)- return FindToolsData(**item.data)+ return FindToolsData(**item.data, feedback_token=item.feedback_token)# Research paper index (/v2/search/research)@doc(ASYNC_CLIENT_SEARCH_PAPERS_DOC)diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/feedback.py b/apps/python-sdk/firecrawl/v2/methods/aio/feedback.pynew file mode 100644index 000000000..3029815c7--- /dev/null+++ b/apps/python-sdk/firecrawl/v2/methods/aio/feedback.py@@ -0,0 +1,23 @@+"""Async Alexandria feedback functionality for Firecrawl v2."""++from typing import Any, Dict, Union++from ...types import AlexandriaFeedbackRequest, AlexandriaFeedbackResponse+from ...utils.error_handler import handle_response_error+from ...utils.http_client_async import AsyncHttpClient+from ..feedback import ENDPOINT, prepare_alexandria_feedback_request+++async def alexandria_feedback(+ client: AsyncHttpClient,+ request: Union[AlexandriaFeedbackRequest, Dict[str, Any]],+) -> AlexandriaFeedbackResponse:+ """Submit feedback for Alexandria calls asynchronously."""+ payload = prepare_alexandria_feedback_request(request)+ response = await client.post(ENDPOINT, payload)+ if response.status_code != 200:+ handle_response_error(response, "submit alexandria feedback")+ body = response.json()+ if not body.get("success"):+ handle_response_error(response, "submit alexandria feedback")+ return AlexandriaFeedbackResponse.model_validate(body)diff --git a/apps/python-sdk/firecrawl/v2/methods/feedback.py b/apps/python-sdk/firecrawl/v2/methods/feedback.pynew file mode 100644index 000000000..ba52c4ccc--- /dev/null+++ b/apps/python-sdk/firecrawl/v2/methods/feedback.py@@ -0,0 +1,53 @@+"""Alexandria feedback functionality for Firecrawl v2."""++from typing import Any, Dict, Iterable, List, Optional, Union++from ..types import AlexandriaFeedbackRequest, AlexandriaFeedbackResponse+from ..utils import HttpClient, handle_response_error+++ENDPOINT = "/v2/feedback"+MAX_FEEDBACK_TOKENS = 20+++def collect_feedback_tokens(results: Iterable[Any]) -> List[str]:+ """Collect feedback tokens from Alexandria call results for a session rating.++ Skips results without a token, dedupes, and keeps the newest 20 (newest last).+ """+ tokens: List[str] = []+ for result in results:+ if isinstance(result, dict):+ token = result.get("feedbackToken") or result.get("feedback_token")+ else:+ token = getattr(result, "feedback_token", None)+ if not token:+ continue+ if token in tokens:+ tokens.remove(token)+ tokens.append(token)+ return tokens[-MAX_FEEDBACK_TOKENS:]+++def prepare_alexandria_feedback_request(+ request: Union[AlexandriaFeedbackRequest, Dict[str, Any]],+) -> Dict[str, Any]:+ validated = AlexandriaFeedbackRequest.model_validate(request)+ payload = validated.model_dump(exclude_none=True, by_alias=True)+ payload["endpoint"] = "alexandria"+ return payload+++def alexandria_feedback(+ client: HttpClient,+ request: Union[AlexandriaFeedbackRequest, Dict[str, Any]],+) -> AlexandriaFeedbackResponse:+ """Submit feedback for Alexandria calls."""+ payload = prepare_alexandria_feedback_request(request)+ response = client.post(ENDPOINT, payload)+ if response.status_code != 200:+ handle_response_error(response, "submit alexandria feedback")+ body = response.json()+ if not body.get("success"):+ handle_response_error(response, "submit alexandria feedback")+ return AlexandriaFeedbackResponse.model_validate(body)diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 1a08084fd..18f363f32 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -20,6 +20,7 @@ from pydantic import (ValidationError,model_serializer,model_validator,+ StringConstraints,)# Suppress pydantic warnings about schema field shadowing@@ -1123,10 +1124,14 @@ class DiscoveredTool(ExchangeSearchResult):class FindToolsData(BaseModel):+ model_config = {"populate_by_name": True}+level: Literal["categories", "providers", "groups", "tools"]items: List[Dict[str, Any]]total: intnext: Optional[Dict[str, Any]] = None+ # Meta calls are not scored, so this token is optional to keep.+ feedback_token: Optional[str] = Field(default=None, alias="feedbackToken")class AlexandriaCall(BaseModel):@@ -1155,6 +1160,8 @@ class AlexandriaScrapeResult(BaseModel):records: Optional[int] = Noneupstream_status: Optional[int] = Field(default=None, alias="upstreamStatus")recorded_at: Optional[str] = Field(default=None, alias="recordedAt")+ # Opaque token for alexandria_feedback. Absent under zero data retention.+ feedback_token: Optional[str] = Field(default=None, alias="feedbackToken")error: Optional[AlexandriaError] = None@property@@ -1171,6 +1178,96 @@ class AlexandriaScrapeData(BaseModel):credits_cost: Union[int, float] = Field(default=0, alias="creditsCost")+AlexandriaFeedbackRating = Literal["good", "partial", "bad"]+_FeedbackToken = Annotated[str, Field(min_length=1, max_length=1024)]+_FeedbackText = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=2000)]+++class AlexandriaCallRating(BaseModel):+ """Rating for one Alexandria call, identified by its feedback token."""++ model_config = {"extra": "forbid"}++ token: _FeedbackToken+ rating: AlexandriaFeedbackRating+++class AlexandriaRequestedWebsite(BaseModel):+ model_config = {"extra": "forbid", "populate_by_name": True}++ url: str+ requested_functionality: _FeedbackText = Field(alias="requestedFunctionality")+++class AlexandriaProviderFeedback(BaseModel):+ model_config = {"extra": "forbid"}++ name: str+ issue: Literal["missing_provider", "insufficient_coverage", "provider_unavailable", "other"]+ why: _FeedbackText+++class AlexandriaCapabilityFeedback(BaseModel):+ model_config = {"extra": "forbid", "populate_by_name": True}++ name: str+ provider: str+ issue: Literal[+ "new_capability_request",+ "missing_capability",+ "insufficient_functionality",+ "incorrect_result",+ "execution_error",+ "other",+ ]+ why: _FeedbackText+ requested_functionality: Optional[_FeedbackText] = Field(default=None, alias="requestedFunctionality")++ @model_validator(mode="after")+ def _require_functionality_for_new_capability(self):+ if self.issue == "new_capability_request" and self.requested_functionality is None:+ raise ValueError("requested_functionality is required for new_capability_request")+ return self+++class AlexandriaFeedbackRequest(BaseModel):+ """Feedback for Alexandria calls.++ ``tokens`` lists the calls the session-level ``rating`` covers (at most 20,+ newest last). ``call_ratings`` rates individual calls (at most 20); a token there+ need not also be in ``tokens``.+ """++ model_config = {"extra": "forbid", "populate_by_name": True}++ rating: AlexandriaFeedbackRating+ requested_website: AlexandriaRequestedWebsite = Field(alias="requestedWebsite")+ rationale: _FeedbackText+ objective: Optional[_FeedbackText] = None+ provider_feedback: Optional[List[AlexandriaProviderFeedback]] = Field(+ default=None, alias="providerFeedback", max_length=20+ )+ capability_feedback: Optional[List[AlexandriaCapabilityFeedback]] = Field(+ default=None, alias="capabilityFeedback", max_length=20+ )+ tokens: Optional[List[_FeedbackToken]] = Field(default=None, max_length=20)+ call_ratings: Optional[List[AlexandriaCallRating]] = Field(+ default=None, alias="callRatings", max_length=20+ )+ integration: Optional[str] = None+ origin: Optional[str] = None+++class AlexandriaFeedbackResponse(BaseModel):+ model_config = {"extra": "allow", "populate_by_name": True}++ success: bool = True+ feedback_id: Optional[str] = Field(default=None, alias="feedbackId")+ credits_refunded: Optional[Union[int, float]] = Field(default=None, alias="creditsRefunded")+ # Tokens that failed verification (expired, other team, or forged).+ rejected_tokens: Optional[int] = Field(default=None, alias="rejectedTokens")++class MapDocument(Document):"""A document from a map operation with URL and description."""