Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.md
index 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 rej
call 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 where
an 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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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__.py
index 58246c7fb..888f56eb7 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -8,6 +8,7 @@ import os
from .client import Firecrawl, AsyncFirecrawl, FirecrawlApp, AsyncFirecrawlApp
from .v2.utils.v1_compat import ScrapeOptions
+from .v2.methods.feedback import collect_feedback_tokens
from .v2.watcher import Watcher
from .v2.watcher_async import AsyncWatcher
from .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 project
logger: 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.py
new file mode 100644
index 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 == 400
diff --git a/apps/python-sdk/firecrawl/client.py b/apps/python-sdk/firecrawl/client.py
index 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.scrape
self.scrape_alexandria = client_instance.scrape_alexandria
self.find_tools = client_instance.find_tools
+ self.alexandria_feedback = client_instance.alexandria_feedback
self.interact = client_instance.interact
self.stop_interaction = client_instance.stop_interaction
self.stop_interactive_browser = client_instance.stop_interactive_browser
@@ -169,6 +170,7 @@ class AsyncV2Proxy:
self.scrape = client_instance.scrape
self.scrape_alexandria = client_instance.scrape_alexandria
self.find_tools = client_instance.find_tools
+ self.alexandria_feedback = client_instance.alexandria_feedback
self.interact = client_instance.interact
self.stop_interaction = client_instance.stop_interaction
self.stop_interactive_browser = client_instance.stop_interactive_browser
@@ -292,6 +294,7 @@ class Firecrawl:
self.scrape = self._v2_client.scrape
self.scrape_alexandria = self._v2_client.scrape_alexandria
self.find_tools = self._v2_client.find_tools
+ self.alexandria_feedback = self._v2_client.alexandria_feedback
self.interact = self._v2_client.interact
self.stop_interaction = self._v2_client.stop_interaction
self.stop_interactive_browser = self._v2_client.stop_interactive_browser
@@ -453,6 +456,7 @@ class AsyncFirecrawl:
self.scrape = self._v2_client.scrape
self.scrape_alexandria = self._v2_client.scrape_alexandria
self.find_tools = self._v2_client.find_tools
+ self.alexandria_feedback = self._v2_client.alexandria_feedback
self.interact = self._v2_client.interact
self.stop_interaction = self._v2_client.stop_interaction
self.stop_interactive_browser = self._v2_client.stop_interactive_browser
diff --git a/apps/python-sdk/firecrawl/v2/__init__.py b/apps/python-sdk/firecrawl/v2/__init__.py
index 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 FirecrawlClient
from .client_async import AsyncFirecrawlClient
+from .methods.feedback import collect_feedback_tokens
from .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.py
index 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_module
from .methods import browser as browser_module
from .methods import monitor as monitor_module
from .methods import research as research_module
+from .methods import feedback as feedback_module
from .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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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: int
next: 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] = None
upstream_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."""