@littlebigbrain/mcp 0.10.0 → 0.11.0

package/README.md

@@ -114,23 +114,29 @@ An agent without a SPARQL query can pass the question in plain words:
 }
 ```
 
-The server selects the kind of query, writes the SPARQL query from a
-description of the graph, checks it, and runs it. The result holds the route,
-the rationale, the query, and its rows. `next` continues the same query with
-`mode: "sparql"`. Each question uses model tokens and counts toward a daily
-limit of the stack, so the tool does not retry a failed call. The server finds
-the names in the question in the graph and lists them in `linked`. When the
-question is about records you already know, pass their IRIs in `anchor` (at
-most 10): the query uses them directly. A question about a date reads the last
-commit written by the end of that day; pass `timeline` (`[{date,
-as_of_commit_seq, label?}]`) when the commits stand for other dates. A
-question that asks what changed returns `history.added` and
-`history.removed`, the rows that differ.
-
-A question can take some seconds. When the tool call carries a
-`_meta.progressToken`, the server sends a progress notification for each
-step, for example `Route: lookup (router, 0.92)` or `12 rows in 85 ms`. The
-result is the same. Cancel the call to stop the server's work.
+The server answers in plain words (`POST /v1/query/ask`). A router model picks
+the kind of question. A reasoning model runs queries in a bounded loop, reads
+their rows, and answers. The result holds `answer` (`text`, `citations`, the
+IRIs the answer names, and `chart`, how to draw the rows, when the server
+gave one), `steps`, the route, and the query and rows the answer stands on. `next` continues that query with `mode: "sparql"`. A
+question takes about 8 s. Each question uses model tokens and counts toward a
+daily limit of the stack, so the tool does not retry a failed call.
+
+The server finds the names in the question in the graph and lists them in
+`linked`. When the question is about records you already know, pass their
+IRIs in `anchor` (at most 10): the queries use them directly. A question
+about a date reads the last commit written by the end of that day; pass
+`timeline` (`[{date, as_of_commit_seq, label?}]`) when the commits stand for
+other dates. A question that asks what changed returns `history.added`,
+`history.removed` and `history.changed`, with `history.totals`.
+
+When the tool call carries a `_meta.progressToken`, the server sends a
+progress notification for each step, for example `Route: lookup (router,
+0.92)` or `Step 2, sparql SELECT ?db: 1 row`. The result is the same. Cancel
+the call to stop the server's work.
+
+To write the queries yourself, use `names`, `describe`, `commit_at` and
+`compare`, then `mode: "sparql"`.
 
 For your own data, start with `lbb_inspect` using `action: "guide"` or
 `action: "ontology"`. Imported Resource Description Framework (RDF) data keeps
@@ -141,14 +147,19 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | Tool | Purpose |
 | --- | --- |
 | `lbb_inspect` | Read the schema, graph status, and entities. |
-| `lbb_query` | Ask a question in plain words, run SPARQL queries, search by meaning (also inside a SPARQL query with `search:similarTo`), or request summary statistics. |
+| `lbb_query` | Ask a question in plain words, run SPARQL queries, search by meaning (also inside a SPARQL query with `search:similarTo`), or request summary statistics. Four modes help an agent write its own queries: `names` (the IRIs of the names in a text), `describe` (the classes and properties a question needs, with how many instances hold each property and the values of small classes), `commit_at` (the commit of a date) and `compare` (one query at two points, the rows paired by entity). |
 | `lbb_rdf` | Import RDF documents or add facts with SPARQL `INSERT DATA`. |
 | `lbb_embeddings` | Inspect search setup and preview the text to embed. |
 | `lbb_embeddings_manage` | Set up or refresh embeddings, or change the embedding model. |
 | `lbb_embeddings_delete` | Delete an embedding and its stored vectors. |
+| `lbb_fit_sources` | Inspect fit from text and preview the text the fit reads. |
+| `lbb_fit_sources_manage` | Declare, dry-run or refresh a fit source. |
+| `lbb_fit_sources_delete` | Delete a fit source; its suggestions stay. |
 | `lbb_commit` | Write or retract JSON facts, or record search feedback. |
 | `lbb_configure` | Define record types and relationships, list and apply ontology starters (CRM, documents, work), publish validation rules, or keep the graph's notes and worked examples for questions in plain words (`get_rewrite_profile`, `set_rewrite_profile`). |
 | `lbb_evals` | Label query results and check whether later queries return the expected answers. Read the model checks of a graph, and agree with or correct a check that the user confirmed. |
+| `lbb_model_choice` | Read which model each use runs (question answers, query routing, search rerank, ontology fit, eval labels), and the trials that test other models against the graph's ground truth. |
+| `lbb_model_choice_manage` | Start or stop a trial, switch a use to a tested model that meets the bar, or revert to LBB's model. |
 | `lbb_models` | Compare retrieval settings, read model training datasets, or read a month of managed-model activity. |
 
 See [search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning/)

package/dist/query-tools.d.ts

@@ -0,0 +1,89 @@
+import type { LbbClient } from "@littlebigbrain/client";
+import { type Detail } from "./tool-contracts.js";
+/** One value of a row, as SPARQL 1.1 Query Results JSON writes it. */
+export interface Term {
+    type: string;
+    value: string;
+    datatype?: string | null;
+    "xml:lang"?: string | null;
+}
+/** A row as `{ variable: lexical value }`. */
+export declare function lexicalRow(row: Record<string, Term>): Record<string, string>;
+/** Entries of each list a page shows, by detail. */
+export declare function listLimit(detail: Detail): number;
+export interface NamesArgs {
+    text: string;
+    limit?: number;
+    detail?: string;
+    graph?: string;
+}
+/** `lbb_query mode=names`: the entities the text names, per name. */
+export declare function findNames(client: LbbClient, args: NamesArgs): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+export interface DescribeArgs {
+    question?: string;
+    classes?: string[];
+    properties?: string[];
+    detail?: string;
+    graph?: string;
+}
+/**
+ * `lbb_query mode=describe`: the parts of the graph a question needs. The
+ * compact and standard answers are the server's text; full adds the same
+ * description as JSON.
+ */
+export declare function describeGraph(client: LbbClient, args: DescribeArgs): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+export interface CommitAtArgs {
+    date?: string;
+    moment?: string;
+    graph?: string;
+}
+/** `lbb_query mode=commit_at`: the commit of a date or a moment. */
+export declare function commitAt(client: LbbClient, args: CommitAtArgs): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+interface ComparePoint {
+    as_of_commit_seq?: number;
+    date?: string;
+    moment?: string;
+}
+export interface CompareArgs {
+    query: string;
+    before: ComparePoint;
+    after?: ComparePoint;
+    key?: string[];
+    entailment?: "none" | "subclass" | "rdfs" | "owl";
+    max_rows?: number;
+    limit?: number;
+    compare_cursor?: string;
+    detail?: string;
+    graph?: string;
+}
+/**
+ * `lbb_query mode=compare`: one SELECT at two points, the rows paired by
+ * `key`. Each list shows one page with its total; `next` continues with the
+ * server's cursor.
+ */
+export declare function compareQuery(client: LbbClient, args: CompareArgs): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+export {};

package/dist/query-tools.js

@@ -0,0 +1,208 @@
+import { HARD_OUTPUT_CHARS } from "./tool-contracts.js";
+import { compactLimits, normalizeDetail, scoped, toolResult, truncateValue, } from "./tool-runtime.js";
+/** A row as `{ variable: lexical value }`. */
+export function lexicalRow(row) {
+    return Object.fromEntries(Object.entries(row).map(([name, term]) => [name, term.value]));
+}
+/** Entries of each list a page shows, by detail. */
+export function listLimit(detail) {
+    switch (detail) {
+        case "full":
+            return 500;
+        case "standard":
+            return 100;
+        default:
+            return 20;
+    }
+}
+/** Long strings cut by detail; every entry stays, so no cursor skips one. */
+function boundStrings(value, detail) {
+    return truncateValue(value, {
+        maxItems: Number.MAX_SAFE_INTEGER,
+        maxString: compactLimits(detail).maxString,
+    }, { truncated: false });
+}
+/** A tool result that must fit the MCP output budget whole. */
+function fitted(value, narrow) {
+    const text = JSON.stringify(value, null, 2);
+    if (Buffer.byteLength(text, "utf8") > HARD_OUTPUT_CHARS) {
+        throw new Error(`The answer exceeds the MCP output budget. ${narrow}`);
+    }
+    return toolResult(value);
+}
+/** `lbb_query mode=names`: the entities the text names, per name. */
+export async function findNames(client, args) {
+    const target = scoped(client, args.graph);
+    const response = await target.request("POST", "/v1/query/names", {
+        body: {
+            text: args.text,
+            ...(args.limit !== undefined ? { limit: args.limit } : {}),
+        },
+        retry: true,
+    });
+    const names = [];
+    for (const { text, ...candidate } of response.candidates) {
+        const last = names[names.length - 1];
+        if (last && last.text === text)
+            last.candidates.push(candidate);
+        else
+            names.push({ text, candidates: [candidate] });
+    }
+    const notes = [];
+    if (!response.index_ready) {
+        notes.push("The graph's name index is still building: ask again in a few seconds.");
+    }
+    else if (names.length === 0) {
+        notes.push('No name of the text matched an entity. Match the name in SPARQL instead, without case and on a short distinctive part, for example FILTER(CONTAINS(LCASE(STR(?label)), "quellm")).');
+    }
+    else {
+        notes.push("Use the first candidate of each name unless its class does not fit the question; put its IRI in the query (as a subject, an object or in VALUES) instead of matching the name.");
+    }
+    const count = response.candidates.length;
+    return fitted({
+        summary: `lbb_query.names: ${names.length} ${names.length === 1 ? "name" : "names"}, ${count} ${count === 1 ? "candidate" : "candidates"}`,
+        data: {
+            names,
+            index_ready: response.index_ready,
+            commit_seq: response.commit_seq,
+        },
+        notes,
+    }, "Pass a shorter text.");
+}
+/**
+ * `lbb_query mode=describe`: the parts of the graph a question needs. The
+ * compact and standard answers are the server's text; full adds the same
+ * description as JSON.
+ */
+export async function describeGraph(client, args) {
+    const detail = normalizeDetail(args.detail);
+    const target = scoped(client, args.graph);
+    const response = await target.request("POST", "/v1/query/describe", {
+        body: {
+            ...(args.question !== undefined ? { question: args.question } : {}),
+            ...(args.classes?.length ? { classes: args.classes } : {}),
+            ...(args.properties?.length ? { properties: args.properties } : {}),
+        },
+        retry: true,
+    });
+    const notes = [];
+    if (response.partial) {
+        notes.push("The server is still sampling the graph: coverage and the values of small classes can be missing. Ask again in a minute for the whole description.");
+    }
+    if (response.unknown?.length) {
+        notes.push(`The graph has no class or property ${response.unknown.join(", ")}.`);
+    }
+    notes.push("A property that few sampled instances hold (n of m) is rare: a filter on it returns few rows. Use the listed values of small classes as they are written.");
+    const data = {
+        commit_seq: response.commit_seq,
+        partial: response.partial,
+        text: response.text,
+        ...(response.unknown?.length ? { unknown: response.unknown } : {}),
+    };
+    if (detail === "full") {
+        data.classes = response.classes;
+        data.properties = response.properties;
+        data.statements = response.statements;
+        data.prefixes = response.prefixes;
+    }
+    return fitted({
+        summary: `lbb_query.describe: ${response.classes.length} classes, ${response.properties.length} properties`,
+        data,
+        notes,
+    }, "Name fewer classes, or use detail=standard.");
+}
+/** `lbb_query mode=commit_at`: the commit of a date or a moment. */
+export async function commitAt(client, args) {
+    if ((args.date === undefined) === (args.moment === undefined)) {
+        throw new Error("commit_at needs exactly one of date and moment");
+    }
+    const target = scoped(client, args.graph);
+    const response = await target.request("GET", "/v1/graph/commit-at", {
+        query: { date: args.date, moment: args.moment },
+        retry: true,
+    });
+    const notes = [];
+    if (typeof response.as_of_commit_seq === "number") {
+        notes.push(`Read the graph as it was then with lbb_query mode=sparql as_of_commit_seq=${response.as_of_commit_seq}, or compare two points with lbb_query mode=compare.`);
+    }
+    if (response.note)
+        notes.push(response.note);
+    return toolResult({
+        summary: typeof response.as_of_commit_seq === "number"
+            ? `lbb_query.commit_at: commit ${response.as_of_commit_seq}`
+            : "lbb_query.commit_at: no commit",
+        data: response,
+        notes,
+    });
+}
+/**
+ * `lbb_query mode=compare`: one SELECT at two points, the rows paired by
+ * `key`. Each list shows one page with its total; `next` continues with the
+ * server's cursor.
+ */
+export async function compareQuery(client, args) {
+    const detail = normalizeDetail(args.detail);
+    const target = scoped(client, args.graph);
+    const limit = args.limit ?? listLimit(detail);
+    const response = await target.request("POST", "/v1/query/compare", {
+        body: {
+            query: args.query,
+            before: args.before,
+            ...(args.after ? { after: args.after } : {}),
+            ...(args.key?.length ? { key: args.key } : {}),
+            ...(args.entailment ? { entailment: args.entailment } : {}),
+            ...(args.max_rows !== undefined ? { max_rows: args.max_rows } : {}),
+            limit,
+            ...(args.compare_cursor ? { cursor: args.compare_cursor } : {}),
+        },
+        retry: true,
+        query: { consistency: target.defaultConsistency },
+    });
+    const notes = [...(response.notes ?? [])];
+    const totals = response.totals;
+    const shown = {
+        added: response.added.length,
+        removed: response.removed.length,
+        changed: response.changed.length,
+    };
+    const cut = Object.keys(shown).filter((name) => response.offset + shown[name] < totals[name]);
+    if (cut.length) {
+        notes.push(`This page shows entries ${response.offset + 1} to ${response.offset + limit} of each list (${cut.map((name) => `${name}: ${totals[name]}`).join(", ")}). Call again with the arguments in next for the next page.`);
+    }
+    const data = boundStrings({
+        before: response.before,
+        after: response.after,
+        key: response.key ?? [],
+        totals,
+        added: response.added.map(lexicalRow),
+        removed: response.removed.map(lexicalRow),
+        changed: response.changed.map((change) => ({
+            key: lexicalRow(change.key),
+            before: change.before.map(lexicalRow),
+            after: change.after.map(lexicalRow),
+        })),
+        offset: response.offset,
+        ...(response.truncated ? { truncated: true } : {}),
+    }, detail);
+    const next = response.next_cursor
+        ? {
+            mode: "compare",
+            query: args.query,
+            before: args.before,
+            ...(args.after ? { after: args.after } : {}),
+            ...(args.key?.length ? { key: args.key } : {}),
+            ...(args.entailment ? { entailment: args.entailment } : {}),
+            ...(args.max_rows !== undefined ? { max_rows: args.max_rows } : {}),
+            limit,
+            compare_cursor: response.next_cursor,
+            ...(args.detail ? { detail: args.detail } : {}),
+            ...(args.graph ? { graph: args.graph } : {}),
+        }
+        : undefined;
+    return fitted({
+        summary: `lbb_query.compare: added ${totals.added}, removed ${totals.removed}, changed ${totals.changed}${response.truncated ? " [not complete: a point was not read whole]" : ""}`,
+        data,
+        ...(next ? { next } : {}),
+        notes,
+    }, "Pass a smaller limit, or project fewer variables.");
+}

package/dist/question.d.ts

@@ -11,7 +11,6 @@ export interface QuestionArgs {
     context?: string;
     route?: QuestionRoute;
     limit?: number;
-    run?: boolean;
     anchor?: string[];
     timeline?: TimelinePoint[];
     detail?: string;
@@ -26,7 +25,7 @@ export interface QuestionProgress {
     signal?: AbortSignal;
     report(progress: number, message: string): Promise<void>;
 }
-/** One event of a streamed rewrite, as this tool reads it. */
+/** One event of a streamed question, as this tool reads it. */
 type StreamEvent = {
     event: string;
     data: unknown;
@@ -34,11 +33,14 @@ type StreamEvent = {
 /** The progress message of a stream event, in short plain words. */
 export declare function progressMessage(event: StreamEvent): string | undefined;
 /**
- * `lbb_query mode=question`: the server turns the question into a SPARQL
- * query and, by default, runs it. The rows are bounded as `mode=sparql`
- * bounds them, and `next` continues the same query with `mode=sparql`.
- * With `progress`, the server streams its steps and each step is reported;
- * the result is the same.
+ * `lbb_query mode=question`: the server answers the question in plain words
+ * (`POST /v1/query/ask`). Its model runs queries in a bounded loop and
+ * reads their rows. The result holds the answer, its citations and chart
+ * hint, the steps, and the rows of the query the answer stands on, bounded
+ * as `mode=sparql`
+ * bounds them; `next` continues that query with `mode=sparql`. With
+ * `progress`, the server streams its steps and each step is reported; the
+ * result is the same.
  */
 export declare function answerQuestion(client: LbbClient, args: QuestionArgs, textFormat?: "compact" | "pretty", progress?: QuestionProgress): Promise<{
     content: {

package/dist/question.js

@@ -1,6 +1,6 @@
+import { lexicalRow, listLimit } from "./query-tools.js";
 import { QUESTION_MAX_ROWS } from "./tool-contracts.js";
 import { defaultRowLimit, normalizeDetail, queryEnvelope, queryToolResult, rowPageFrom, rowPageNext, scoped, } from "./tool-runtime.js";
-const REPAIR_ERROR_CHARS = 200;
 /** The progress message of a stream event, in short plain words. */
 export function progressMessage(event) {
     const data = (event.data ?? {});
@@ -13,41 +13,35 @@ export function progressMessage(event) {
                 : "";
             return `Route: ${String(data.kind)} (${String(data.by)}${confidence})`;
         }
-        case "query":
-            return `Wrote query ${String(data.attempt ?? 1)}`;
-        case "run":
-            return data.point === "before"
-                ? "Running the query at the earlier point"
-                : data.point === "after"
-                    ? "Running the query at the later point"
-                    : "Running the query";
-        case "rows": {
-            const count = Number(data.count);
-            return `${count} ${count === 1 ? "row" : "rows"} in ${String(data.ms)} ms`;
-        }
-        case "repair": {
-            const error = String(data.error ?? "");
-            const shown = error.length > REPAIR_ERROR_CHARS
-                ? `${error.slice(0, REPAIR_ERROR_CHARS - 1)}…`
-                : error;
-            return `Correcting the query: ${shown}`;
+        case "step": {
+            // A compare step counts the entries that differ, not rows.
+            const unit = data.tool === "compare" ? "difference" : "row";
+            const rows = typeof data.rows === "number"
+                ? `: ${data.rows} ${unit}${data.rows === 1 ? "" : "s"}`
+                : "";
+            const outcome = data.ok === false ? ": failed" : rows;
+            return `Step ${String(data.n)}, ${String(data.tool)} ${String(data.input ?? "")}${outcome}`;
         }
+        case "answer":
+            return "Answered";
         default:
             return undefined;
     }
 }
 /**
- * The rewrite as a stream of progress events. Each event becomes one
+ * The question as a stream of progress events. Each event becomes one
  * progress notification; the `done` event is the same response as the call
- * without a stream. A client release without `query.rewriteStream` answers
+ * without a stream. A client release without `query.askStream` answers
  * without progress.
  */
-async function streamedRewrite(target, body, progress) {
+async function streamedAnswer(target, body, progress) {
     const query = target.query;
-    if (typeof query.rewriteStream !== "function")
+    if (typeof query.askStream !== "function")
         return undefined;
+    const { question, ...options } = body;
     let step = 0;
-    for await (const event of query.rewriteStream.call(target.query, body, {
+    for await (const event of query.askStream.call(target.query, question, {
+        ...options,
         signal: progress.signal,
     })) {
         if (event.event === "done")
@@ -59,30 +53,50 @@ async function streamedRewrite(target, body, progress) {
         // A lost notification never fails the question.
         await progress.report(step, message).catch(() => undefined);
     }
-    throw new Error("the rewrite stream ended before its done event");
+    throw new Error("the answer stream ended before its done event");
 }
-/** A row of a comparison as `{ variable: lexical value }`. */
-function lexicalRow(row) {
-    return Object.fromEntries(Object.entries(row).map(([name, term]) => [name, term.value]));
+/** The totals of a comparison: the server's, else the lengths of its lists. */
+function historyTotals(history) {
+    return (history.totals ?? {
+        added: history.added?.length ?? 0,
+        removed: history.removed?.length ?? 0,
+        changed: history.changed?.length ?? 0,
+    });
 }
 /**
  * The history the tool returns: where the question read the graph, and for
- * a comparison the rows that differ as lexical values. The two runs stay
- * out: the later one is the result, and the rows that differ say what the
- * earlier one held.
+ * a comparison the rows that differ as lexical values, with the total of
+ * each list. Each list shows at most `limit` entries; `shown` says how many
+ * when a list is cut.
  */
-function historyView(history) {
+function historyView(history, limit) {
     const view = { ...history };
-    delete view.before;
-    delete view.after;
-    if (history.added)
-        view.added = history.added.map(lexicalRow);
-    if (history.removed)
-        view.removed = history.removed.map(lexicalRow);
+    if (!history.added && !history.removed && !history.changed)
+        return view;
+    const totals = historyTotals(history);
+    view.totals = totals;
+    const shown = {};
+    const show = (name, list, map) => {
+        if (!list)
+            return;
+        const kept = list.slice(0, limit);
+        view[name] = kept.map(map);
+        if (kept.length < (totals[name] ?? list.length))
+            shown[name] = kept.length;
+    };
+    show("added", history.added, lexicalRow);
+    show("removed", history.removed, lexicalRow);
+    show("changed", history.changed, (change) => ({
+        key: lexicalRow(change.key),
+        before: change.before.map(lexicalRow),
+        after: change.after.map(lexicalRow),
+    }));
+    if (Object.keys(shown).length)
+        view.shown = shown;
     return view;
 }
 /** What the agent should know about the history of the answer. */
-function historyNotes(history) {
+function historyNotes(history, limit, query) {
     if (!history)
         return [];
     const notes = [];
@@ -100,36 +114,55 @@ function historyNotes(history) {
     else if (history.as_of_date) {
         notes.push(`The server could not place ${history.as_of_date} (see error). Pass timeline=[{date, as_of_commit_seq}] to name the commit of each date, or run the query with lbb_query mode=sparql as_of_commit_seq=<commit>.`);
     }
-    if (history.compare && history.added && point) {
-        notes.push(`A comparison: the rows are the later run; history.added and history.removed hold the rows that changed since ${point}.${history.truncated ? " The difference is not complete: a run returned only its first rows, or more than 500 rows changed." : ""}`);
+    if (history.compare && (history.added || history.changed) && point) {
+        const totals = historyTotals(history);
+        // The compared query reads the later point.
+        const later = typeof query?.as_of_commit_seq === "number"
+            ? query.as_of_commit_seq
+            : undefined;
+        const keyed = history.key?.length
+            ? `paired by ${history.key.map((v) => `?${v}`).join(", ")}: history.added and history.removed hold the entities at one point only, history.changed the entities whose values differ`
+            : "history.added and history.removed hold the rows that differ (a changed value is a removed row and an added row)";
+        notes.push(`A comparison from ${point} to ${later === undefined ? "the latest commit" : `commit ${later}`}; ${keyed}. Totals: added ${totals.added}, removed ${totals.removed}, changed ${totals.changed}.`);
+        const cut = ["added", "removed", "changed"].filter((name) => totals[name] > limit);
+        if (cut.length && query) {
+            const after = later === undefined ? "" : ` after={"as_of_commit_seq": ${later}}`;
+            const key = history.key?.length
+                ? ` key=${JSON.stringify(history.key)}`
+                : "";
+            notes.push(`Each list shows at most ${limit} entries (${cut.map((name) => `${name}: ${totals[name]}`).join(", ")}; see history.shown). Read them all, page by page, with lbb_query mode=compare query=<the query> before={"as_of_commit_seq": ${history.as_of_commit_seq}}${after}${key}.`);
+        }
+        if (history.truncated) {
+            notes.push("The difference is not complete: a point was not read whole, or a list held more than 500 entries on the server. Use lbb_query mode=compare for the whole difference.");
+        }
     }
     return notes;
 }
 /**
- * `lbb_query mode=question`: the server turns the question into a SPARQL
- * query and, by default, runs it. The rows are bounded as `mode=sparql`
- * bounds them, and `next` continues the same query with `mode=sparql`.
- * With `progress`, the server streams its steps and each step is reported;
- * the result is the same.
+ * `lbb_query mode=question`: the server answers the question in plain words
+ * (`POST /v1/query/ask`). Its model runs queries in a bounded loop and
+ * reads their rows. The result holds the answer, its citations and chart
+ * hint, the steps, and the rows of the query the answer stands on, bounded
+ * as `mode=sparql`
+ * bounds them; `next` continues that query with `mode=sparql`. With
+ * `progress`, the server streams its steps and each step is reported; the
+ * result is the same.
  */
 export async function answerQuestion(client, args, textFormat, progress) {
     const detail = normalizeDetail(args.detail);
-    const run = args.run ?? true;
     const rowLimit = Math.min(args.limit ?? defaultRowLimit(detail), QUESTION_MAX_ROWS);
     const target = scoped(client, args.graph);
     const body = {
         question: args.question,
         ...(args.context !== undefined ? { context: args.context } : {}),
         ...(args.route !== undefined ? { route: args.route } : {}),
-        run,
-        ...(run ? { limit: rowLimit } : {}),
+        limit: rowLimit,
         ...(args.anchor?.length ? { anchor: args.anchor } : {}),
         ...(args.timeline?.length ? { timeline: args.timeline } : {}),
     };
-    // Each call uses model tokens, and the server corrects a failing query
-    // once, so a failed call is not retried.
-    const response = (progress ? await streamedRewrite(target, body, progress) : undefined) ??
-        (await target.request("POST", "/v1/query/rewrite", {
+    // Each call uses model tokens, so a failed call is not retried.
+    const response = (progress ? await streamedAnswer(target, body, progress) : undefined) ??
+        (await target.request("POST", "/v1/query/ask", {
             body,
             retry: false,
             query: { consistency: target.defaultConsistency },
@@ -137,6 +170,20 @@ export async function answerQuestion(client, args, textFormat, progress) {
     const { route, query, result } = response;
     const traceId = result?.trace_id ?? null;
     const answer = {
+        answer: response.answer
+            ? {
+                text: response.answer.text,
+                citations: response.answer.citations ?? [],
+                ...(response.answer.chart ? { chart: response.answer.chart } : {}),
+            }
+            : null,
+        steps: (response.steps ?? []).map((step) => ({
+            n: step.n,
+            tool: step.tool,
+            ok: step.ok,
+            ...(typeof step.rows === "number" ? { rows: step.rows } : {}),
+            ...(step.error ? { error: step.error } : {}),
+        })),
         route: { kind: route.kind, confidence: route.confidence, by: route.by },
         rationale: response.rationale,
         sparql: query?.sparql ?? null,
@@ -144,7 +191,9 @@ export async function answerQuestion(client, args, textFormat, progress) {
         ...(typeof query?.as_of_commit_seq === "number"
             ? { as_of_commit_seq: query.as_of_commit_seq }
             : {}),
-        ...(response.history ? { history: historyView(response.history) } : {}),
+        ...(response.history
+            ? { history: historyView(response.history, listLimit(detail)) }
+            : {}),
         error: response.error ?? null,
         trace_id: traceId,
         attempts: response.attempts,
@@ -160,9 +209,9 @@ export async function answerQuestion(client, args, textFormat, progress) {
     if (traceId) {
         notes.push(`eval trace ${traceId}: to label rows, read their item ids with lbb_evals action=trace trace_id=${traceId}, then call lbb_evals action=label trace_id=${traceId} item=<id> valid=true|false (or items=[…]).`);
     }
-    notes.push(...historyNotes(response.history));
-    if (response.error && query) {
-        notes.push("The last query failed (see error). Correct it and run it with lbb_query mode=sparql, or ask again with more context.");
+    notes.push(...historyNotes(response.history, listLimit(detail), query));
+    if (!response.answer) {
+        notes.push("The answer loop stopped before it answered (see error); the rows are the best ones it read. Continue with lbb_query mode=sparql, or ask again with more context.");
     }
     const label = `lbb_query.question: route ${route.kind} (${route.by}, confidence ${route.confidence.toFixed(2)})`;
     const data = result
@@ -186,13 +235,15 @@ export async function answerQuestion(client, args, textFormat, progress) {
         };
         return queryToolResult(queryEnvelope(label, { ...answer, ...data }, detail, rowPage, rowPageNext(cursorBase, rowPage), cursorBase, { textFormat, notes }), textFormat);
     }
-    // No rows to page: the query only, an ASK answer, or no query at all. The
+    // No rows to page: an ASK answer, a comparison, or no query at all. The
     // query text is returned whole.
     const summary = data
         ? `${label}: ran the query`
-        : query
-            ? `${label}: ${response.error ? "the query failed" : "the query, not run"}`
-            : `${label}: no query`;
+        : response.history?.compare
+            ? `${label}: compared two points`
+            : query
+                ? `${label}: no rows`
+                : `${label}: no query`;
     return queryToolResult({
         summary,
         data: { ...answer, ...(data ?? {}) },

package/dist/tool-contracts.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const DEFAULT_DETAIL = "compact";
 export const HARD_OUTPUT_CHARS = 80_000;
 export const MAX_QUERY_ROW_LIMIT = 5_000;
-/** The most rows `POST /v1/query/rewrite` returns from a run. */
+/** The most rows each query of `POST /v1/query/ask` returns. */
 export const QUESTION_MAX_ROWS = 1_000;
 /** Entity IRIs one question may anchor, and the characters of one. */
 export const QUESTION_MAX_ANCHORS = 10;
@@ -405,6 +405,17 @@ export const SPARQL_IRI_GUIDE = 'IRI scheme: relations are <https://littlebigbra
 // Search by meaning runs inside SPARQL text as a pattern, so an agent can
 // filter and join the hits in one query instead of a search then a lookup.
 export const SPARQL_SEARCH_GUIDE = 'Search by meaning inside the query (the graph needs an embedding; see lbb_embeddings action=list): PREFIX search: <https://littlebigbrain.com/search#> SELECT ?x ?score WHERE { ?x search:similarTo "card payments" ; search:score ?score . ?x <https://littlebigbrain.com/r/calls> ?y } ORDER BY DESC(?score) LIMIT 5. The other patterns filter and join the hits. One search:similarTo per query, with a variable subject, in the main group (not inside OPTIONAL, UNION, MINUS or a subquery). The object is text, an entity IRI (records like that one) or a vector literal. search:top N sets the hits (1 to 1000; default the query LIMIT, then 10) and search:embedding "name" searches one embedding. FILTER(?score > 0.8) keeps close hits. The result\'s search field reports the plan (nearest, filter_first or search_first), the hits and complete. For a question in words, add search:rerank true ; search:relevance ?r and ORDER BY DESC(?r): the rerank model (Jev) reads the best hits with the text, keeps the top that answer it and binds its answer (0 to 1); search.rerank reports the status. Only a text query reranks.';
+/** One point of `lbb_query mode=compare`: a commit, a date or a moment. */
+const comparePointSchema = z
+    .object({
+    as_of_commit_seq: z.number().int().min(0).optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional(),
+    moment: z.string().optional(),
+})
+    .strict();
 export const queryInputSchema = z.discriminatedUnion("mode", [
     z
         .object({
@@ -447,7 +458,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         query: z
             .string()
             .optional()
-            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10. ${SPARQL_SEARCH_GUIDE}`),
+            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10. ${SPARQL_SEARCH_GUIDE} compare: the SELECT to run at both points; leave out LIMIT.`),
         // Kept for an actionable error when an older connector sends this field.
         as_of: z
             .string()
@@ -474,7 +485,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         question: z
             .string()
             .min(1)
-            .describe("question: the question in plain words (required), 1 to 4,000 characters. The server writes the SPARQL query from a description of this graph, checks it, and runs it."),
+            .describe("question: the question in plain words (required), 1 to 4,000 characters. The server's model runs queries on this graph, reads their rows, and answers. describe: the question whose classes and properties to describe."),
         context: z
             .string()
             .optional()
@@ -489,23 +500,19 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             "unanswerable",
         ])
             .optional()
-            .describe("question: the kind of query, when you know it. Omit it and the router model selects it."),
+            .describe("question: the kind of question, when you know it. Omit it and the router model picks it."),
         limit: z
             .number()
             .int()
             .min(1)
             .max(QUESTION_MAX_ROWS)
             .optional()
-            .describe("question: rows the run returns, 1 to 1,000. Defaults by detail: compact=20, standard=100, full=1000."),
-        run: z
-            .boolean()
-            .optional()
-            .describe("question: run the query and return its rows. Defaults to true; false returns the query only."),
+            .describe("question: rows each query of the server's loop returns, 1 to 1,000. Defaults by detail: compact=20, standard=100, full=1000. names: candidates per name, 1 to 10 (default 5). compare: entries of each list per page, 1 to 1,000 (defaults by detail: 20, 100, 500)."),
         anchor: z
             .array(z.string().min(1).max(QUESTION_MAX_ANCHOR_CHARS))
             .max(QUESTION_MAX_ANCHORS)
             .optional()
-            .describe("question: entity IRIs the question is about, at most 10 (for example the record the user has open). The server reads each one, and the query uses these IRIs directly instead of matching their names."),
+            .describe("question: entity IRIs the question is about, at most 10 (for example the record the user has open). The server reads each one, and its queries use these IRIs directly instead of matching their names."),
         timeline: z
             .array(z
             .object({
@@ -541,7 +548,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         text: z
             .string()
             .optional()
-            .describe("The query text (required); embedded with the graph's model."),
+            .describe("search: the query text (required); embedded with the graph's model. names: the question, or the names, to find (required)."),
         top_k: z.number().int().positive().max(200).optional(),
         probe: z
             .number()
@@ -605,6 +612,82 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         ...readScope,
     })
         .strict(),
+    z
+        .object({
+        mode: z.literal("names"),
+        text: z
+            .string()
+            .min(1)
+            .max(4_000)
+            .describe("names: the question, or the names, to find (required)."),
+        limit: z.number().int().min(1).max(10).optional(),
+        ...readScope,
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("describe"),
+        question: z.string().max(4_000).optional(),
+        classes: z
+            .array(z.string().min(1))
+            .max(20)
+            .optional()
+            .describe("describe: class IRIs to describe, at most 20."),
+        properties: z
+            .array(z.string().min(1))
+            .max(50)
+            .optional()
+            .describe("describe: property IRIs to describe, at most 50."),
+        ...readScope,
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("commit_at"),
+        date: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/)
+            .optional()
+            .describe("commit_at: YYYY-MM-DD; the last commit written by the end of that day (UTC)."),
+        moment: z
+            .string()
+            .optional()
+            .describe("commit_at: RFC 3339, e.g. 2026-06-18T12:00:00Z; the last commit written at or before it."),
+        ...readScope,
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("compare"),
+        query: z
+            .string()
+            .min(1)
+            .describe("compare: the SELECT to run at both points. Leave out LIMIT: the server reads up to max_rows rows a point, page by page."),
+        before: comparePointSchema.describe('compare: the earlier point (required): {"as_of_commit_seq": n}, {"date": "YYYY-MM-DD"} or {"moment": "RFC 3339"}.'),
+        after: comparePointSchema
+            .optional()
+            .describe("compare: the later point; defaults to the latest commit."),
+        key: z
+            .array(z.string().min(1))
+            .max(8)
+            .optional()
+            .describe('compare: the variables that identify a row\'s entity, e.g. ["contact"]. With a key the rows are paired: added and removed hold the entities at one point only, changed the entities whose values differ. Without one whole rows are compared.'),
+        entailment: z.enum(["none", "subclass", "rdfs", "owl"]).optional(),
+        max_rows: z
+            .number()
+            .int()
+            .min(1)
+            .max(50_000)
+            .optional()
+            .describe("compare: rows to read per point, 1 to 50,000 (default 20,000). Past it the result says truncated."),
+        limit: z.number().int().min(1).max(1_000).optional(),
+        compare_cursor: z
+            .string()
+            .optional()
+            .describe("compare: the cursor of the page before, from next; pass it with the same arguments."),
+        ...readScope,
+    })
+        .strict(),
 ]);
 export const configureInputSchema = z.discriminatedUnion("action", [
     z

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { metadataPage } from "./metadata-pages.js";
 import { answerQuestion, } from "./question.js";
+import { commitAt, compareQuery, describeGraph, findNames, } from "./query-tools.js";
 import { registerRdfTool } from "./rdf-tool.js";
 import { queryTiming } from "./query-observer.js";
 import { DESTRUCTIVE, IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, yearMonthSchema, } from "./tool-contracts.js";
@@ -63,7 +64,7 @@ export function registerLbbTools(server, client, options = {}) {
         });
     });
     server.registerTool("lbb_query", {
-        description: "Analytical and expert reads. Modes: question (a question in plain words), structured (SPARQL-subset JSON body), sparql (SPARQL text), search (instances by meaning over every searchable class; filter narrows by class and relationship; every hit checked against the graph), analyze. Use mode=question when you have a question in plain words and no SPARQL query: the server selects the kind of query (route), writes the SPARQL query from a description of the graph, checks it, runs it, and returns the route, the rationale, the query and its rows. Continue or correct that query with mode=sparql. Each question uses model tokens and counts toward a daily limit of the stack. SPARQL is the query language; search finds what the words describe. SPARQL text can also search by meaning inside the query with ?x <https://littlebigbrain.com/search#similarTo> \"words\", so the other patterns filter and join the hits in one query; the result's search field reports the plan. To plan a search: lbb_embeddings action=list, then SPARQL for a class's relationships on a sample, then mode=search with explain=true to check the resolved filter before the real search (lbb_inspect action=guide has the queries). Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
+        description: "Analytical and expert reads. Modes: question (a question in plain words), structured (SPARQL-subset JSON body), sparql (SPARQL text), search (instances by meaning over every searchable class; filter narrows by class and relationship; every hit checked against the graph), analyze, and four tools for writing your own queries: names, describe, commit_at, compare. names: before a query that names an entity (a person, a company), find its IRI with text=<the question or the names>; use the first candidate, not a CONTAINS match on the name. describe: before a query on classes or properties you have not seen, read them with question=<the question> (or classes/properties as IRIs): how many sampled instances hold each property (a filter on a rare one returns few rows), the values of small classes such as stages, examples and schema statements. commit_at: for a question about a date, find the commit of date=YYYY-MM-DD (or moment=RFC 3339), then run mode=sparql as_of_commit_seq=<it>. compare: for what changed between two points, run one SELECT at before and after (default the latest) with key=[the entity variable]; added, removed and changed come with totals and pages (next). Use mode=question when you have a question in plain words and no SPARQL query: the server picks the kind of question (route), runs queries in a bounded loop, reads their rows, and answers in plain words (about 8 s). The result holds the answer with citations and a chart hint (kind, x, y: columns of the rows), the steps, the route, and the query and rows the answer stands on. Continue or correct that query with mode=sparql. Each question uses model tokens and counts toward a daily limit of the stack. SPARQL is the query language; search finds what the words describe. SPARQL text can also search by meaning inside the query with ?x <https://littlebigbrain.com/search#similarTo> \"words\", so the other patterns filter and join the hits in one query; the result's search field reports the plan. To plan a search: lbb_embeddings action=list, then SPARQL for a class's relationships on a sample, then mode=search with explain=true to check the resolved filter before the real search (lbb_inspect action=guide has the queries). Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
         inputSchema: queryWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs, extra) => {
@@ -300,6 +301,29 @@ export function registerLbbTools(server, client, options = {}) {
                 }
             })();
         }
+        if (args.mode === "names" ||
+            args.mode === "describe" ||
+            args.mode === "commit_at" ||
+            args.mode === "compare") {
+            const toolArgs = args;
+            return (async () => {
+                try {
+                    switch (args.mode) {
+                        case "names":
+                            return await findNames(client, toolArgs);
+                        case "describe":
+                            return await describeGraph(client, toolArgs);
+                        case "commit_at":
+                            return await commitAt(client, toolArgs);
+                        default:
+                            return await compareQuery(client, toolArgs);
+                    }
+                }
+                catch (error) {
+                    return errorResult(await enrichError(client, error));
+                }
+            })();
+        }
         if (args.mode === "search") {
             const searchArgs = args;
             // The caller's detail shapes the hits like every other mode: compact
@@ -476,8 +500,242 @@ export function registerLbbTools(server, client, options = {}) {
         }
         return scoped(client, graph).embeddings.delete(name);
     }));
+    // Fit from text: fit sources declared on classes, like embeddings.
+    const fitSetup = {
+        class: z
+            .string()
+            .optional()
+            .describe("preview/declare/dry_run: the class IRI whose instances hold the text."),
+        from: z
+            .array(z.string())
+            .optional()
+            .describe("preview/declare/dry_run: the fields that hold the text, as embedding paths (transcript, label, about/label, <https://…>). Omit for the long text facts of the class."),
+        exclude: z
+            .array(z.string())
+            .optional()
+            .describe("preview/declare/dry_run: fields to drop from the automatic choice."),
+        context: z
+            .string()
+            .optional()
+            .describe('preview/declare/dry_run: one sentence about the text, e.g. "interviews with employees about their work processes" (at most 500 characters).'),
+    };
+    const fitDeclaration = (args) => {
+        if (!args.class)
+            throw new Error("this action requires class");
+        return {
+            class: args.class,
+            ...(args.name ? { name: args.name } : {}),
+            ...(args.from ? { from: args.from } : {}),
+            ...(args.exclude ? { exclude: args.exclude } : {}),
+            ...(args.context ? { context: args.context } : {}),
+        };
+    };
+    server.registerTool("lbb_fit_sources", {
+        description: "Fit from text, read only: fit sources declared on classes. A fit source names the fields of a class that hold text (transcripts, documents); the server reads every instance, proposes ontology changes (classes, properties, relations) with verbatim quotes, checks them, and files them as ontology suggestions with origin id fit:<name>. list shows each source's status (progress, lag, instances read, proposals kept and dropped, suggestions per status, this month's spend, last error) and the stack's monthly budget; get shows one; preview shows the fields, every candidate field of the class and the text of sample instances, calls no model and stores nothing. Declare, refresh or dry-run with lbb_fit_sources_manage; list the suggestions with lbb_inspect action=ontology_suggestions.",
+        inputSchema: {
+            action: z.enum(["list", "get", "preview"]),
+            name: z.string().optional().describe("get: the fit source name."),
+            ...fitSetup,
+            sample: z.number().int().positive().max(20).optional(),
+            iris: z
+                .array(z.string())
+                .optional()
+                .describe("preview: the instances to show instead of a sample."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, (args) => run(client, `lbb_fit_sources.${args.action}`, args.detail, () => {
+        const fit = scoped(client, args.graph).ontology.fitSources;
+        switch (args.action) {
+            case "list":
+                return fit.list();
+            case "get":
+                if (!args.name)
+                    throw new Error("get requires name");
+                return fit.get(args.name);
+            case "preview":
+                return fit.preview({
+                    ...fitDeclaration(args),
+                    ...(args.sample ? { sample: args.sample } : {}),
+                    ...(args.iris ? { iris: args.iris } : {}),
+                });
+        }
+    }));
+    server.registerTool("lbb_fit_sources_manage", {
+        description: "Declare, dry-run or refresh a fit source (fit from text). Run lbb_fit_sources action=preview first and show the user the text the fit reads. dry_run runs the models on the first part of up to 3 instances (at most 60 s; truncated when one did not finish) and returns every proposal with its quote, its support score and what the checks made of it; it files nothing but spends model budget. declare sets the class, the fields and the context; the job then reads every instance and files suggestions (an existing source changes only what you name). refresh asks the job to run now and returns the status at once; the job also runs by itself after each published commit, so poll lbb_fit_sources action=get for progress. Nothing changes the ontology until a person accepts a suggestion.",
+        inputSchema: {
+            action: z.enum(["declare", "dry_run", "refresh"]),
+            name: z
+                .string()
+                .optional()
+                .describe("The fit source name (refresh: required)."),
+            ...fitSetup,
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_fit_sources_manage.${args.action}`, args.detail, () => {
+        const fit = scoped(client, args.graph).ontology.fitSources;
+        switch (args.action) {
+            case "declare":
+                return fit.declare(fitDeclaration(args));
+            case "dry_run":
+                return fit.preview({ ...fitDeclaration(args), propose: true });
+            case "refresh":
+                if (!args.name)
+                    throw new Error("refresh requires name");
+                return fit.refresh(args.name);
+        }
+    }));
+    server.registerTool("lbb_fit_sources_delete", {
+        description: "Delete a fit source: the fit stops reading its class. The suggestions it filed stay. Ask the user first; confirm must repeat the name.",
+        inputSchema: {
+            name: z.string().describe("The fit source name."),
+            confirm: z.string().describe("The same name again, to confirm."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: DESTRUCTIVE,
+    }, ({ name, confirm, detail, graph }) => run(client, "lbb_fit_sources_delete", detail, () => {
+        if (confirm !== name) {
+            throw new Error("confirm must repeat the fit source name");
+        }
+        return scoped(client, graph).ontology.fitSources.delete(name);
+    }));
+    const modelUse = z
+        .enum(["ask", "route", "rerank", "fit", "label"])
+        .describe("A use of a model: ask = question answers, route = query routing, rerank = search rerank, fit = ontology fit, label = eval labels.");
+    server.registerTool("lbb_model_choice", {
+        description: "Model choice, read only: which model each use of a model on the graph runs, and trials that test other models against the graph's ground truth (the checked calls: a person's review, else the judge's verdict). options shows per use the model it runs now (current), LBB's model (default), a switch (switched), its checked calls, and the models a trial can test with their efforts, prices and whether the server holds their key; available=false with a reason when trials cannot run. trials lists the trials, newest first, each with its report: calls compared, both models' right share, mean score (0 to 1), cost per call and median time, the difference with its 95% interval (delta, ci_low, ci_high), outcome (too_few, better, same, worse) and qualifies (meets the bar: at least 20 calls, at most 5 points worse at the low end, no more failures, cheaper or better). trial reads one trial with its compared calls; trial_call reads one call with both answers and the ground truth. switches lists the switched uses. Start, stop, switch or revert with lbb_model_choice_manage.",
+        inputSchema: {
+            action: z.enum([
+                "options",
+                "trials",
+                "trial",
+                "trial_call",
+                "switches",
+            ]),
+            trial_id: z
+                .string()
+                .optional()
+                .describe("trial / trial_call: the trial id."),
+            call_id: z
+                .string()
+                .optional()
+                .describe("trial_call: a call id from the trial's calls."),
+            job: modelUse
+                .optional()
+                .describe("trials: only the trials of this use."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe("trials: at most this many, newest first (default 20)."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, (args) => run(client, `lbb_model_choice.${args.action}`, args.detail, () => {
+        const models = scoped(client, args.graph).models;
+        switch (args.action) {
+            case "options":
+                return models.trials.options();
+            case "trials":
+                return models.trials.list({ job: args.job, limit: args.limit });
+            case "trial":
+                if (!args.trial_id)
+                    throw new Error("trial requires trial_id");
+                return models.trials.get(args.trial_id);
+            case "trial_call":
+                if (!args.trial_id || !args.call_id) {
+                    throw new Error("trial_call requires trial_id and call_id");
+                }
+                return models.trials.call(args.trial_id, args.call_id);
+            case "switches":
+                return models.switches.list();
+        }
+    }));
+    server.registerTool("lbb_model_choice_manage", {
+        description: "Model choice, writes. start tests a candidate model on the uses in jobs (without jobs, every use it can do that has checked calls): the server answers those checked calls again with the candidate and scores it and the model in use against the same ground truth. It changes no model and spends at most the trial budget ($3.00 by default) of model and judge cost; an open trial of the same use and candidate comes back as it is. Pick candidates from lbb_model_choice action=options (provider anthropic with an effort, or typesafe jev-latest). A trial runs by itself: poll lbb_model_choice action=trial until its status is no longer running. stop ends a trial; it keeps what it compared. switch makes the trial's use run its candidate on this graph from the next call on; only a trial that qualifies and compared with the model in use switches (ask to a Claude model, route to a Jev model). Show the user the trial's report (score, difference and interval, cost per call, time) and switch only what the user confirmed. revert puts the use back on LBB's model.",
+        inputSchema: {
+            action: z.enum(["start", "stop", "switch", "revert"]),
+            provider: z
+                .enum(["anthropic", "typesafe"])
+                .optional()
+                .describe("start: the candidate's provider."),
+            model: z
+                .string()
+                .optional()
+                .describe("start: the candidate model id, e.g. claude-haiku-5-5 or jev-latest."),
+            effort: z
+                .enum(["low", "medium", "high", "xhigh", "max"])
+                .optional()
+                .describe("start: the effort of a Claude candidate."),
+            jobs: z
+                .array(modelUse)
+                .optional()
+                .describe("start: the uses to test it on."),
+            target: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("start: the calls to compare (default 40)."),
+            days: z
+                .number()
+                .int()
+                .positive()
+                .max(30)
+                .optional()
+                .describe("start: the days the trial takes new checks (default 14)."),
+            trial_id: z
+                .string()
+                .optional()
+                .describe("stop / switch: the trial id."),
+            job: modelUse
+                .optional()
+                .describe("revert: the use to put back on LBB's model."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_model_choice_manage.${args.action}`, args.detail, () => {
+        const models = scoped(client, args.graph).models;
+        switch (args.action) {
+            case "start":
+                if (!args.provider || !args.model) {
+                    throw new Error("start requires provider and model");
+                }
+                return models.trials.create({
+                    candidate: {
+                        provider: args.provider,
+                        model: args.model,
+                        ...(args.effort ? { effort: args.effort } : {}),
+                    },
+                    ...(args.jobs ? { jobs: args.jobs } : {}),
+                    ...(args.target ? { target: args.target } : {}),
+                    ...(args.days ? { days: args.days } : {}),
+                });
+            case "stop":
+                if (!args.trial_id)
+                    throw new Error("stop requires trial_id");
+                return models.trials.stop(args.trial_id);
+            case "switch":
+                if (!args.trial_id)
+                    throw new Error("switch requires trial_id");
+                return models.switches.create({ trial: args.trial_id });
+            case "revert":
+                if (!args.job)
+                    throw new Error("revert requires job");
+                return models.switches.revert(args.job);
+        }
+    }));
     server.registerTool("lbb_evals", {
-        description: "Managed evals: the thumbs up / thumbs down of the graph, per result. A query run with `request` (lbb_query) records a trace with one item per result (hit or row); trace reads it back with the item ids. label marks one result (item + valid) or several (items) relevant or not; the labels become the golden's ground truth. golden freezes a query (every result it returns now is relevant). run replays every golden at the current commit: pass when every relevant result is back and no wrong one is; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed.",
+        description: "Managed evals: ground truth for the questions an app asks and the searches it runs. A query run with `request` (lbb_query, also mode=question) records a trace: the question, the query that answered it, the type of that query (`query_type`: sparql, hybrid = search by meaning with conditions, search = search by meaning alone) and one item per result (hit or row); trace reads it back with the item ids. label has two forms. On a question's trace, valid alone judges the whole answer: valid=true makes the trace's query the golden query of the question; valid=false with sparql gives the right query, which becomes the golden query; valid=false alone marks the answer wrong. item + valid (or items) judges one result, a citation of the answer: the ground truth of the hits of a search by meaning, and a result marked wrong must not come back for any type. golden freezes a stored query or a search (every result it returns now is relevant). run checks every golden at the current commit: a question is asked again through the query rewriter, then the type of the query it wrote is compared with the expected type, its rows with the rows of the golden query at the same commit (`query_check`), and its results with the judged results; a search is done again; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, ask = the answer of a question, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed.",
         inputSchema: {
             action: z.enum([
                 "summary",
@@ -507,7 +765,7 @@ export function registerLbbTools(server, client, options = {}) {
             valid: z
                 .boolean()
                 .optional()
-                .describe("label: true = the result answers the request (thumbs up), false = it does not."),
+                .describe("label: true = the result answers the request (thumbs up), false = it does not. Without item or items, on a question's trace: the whole answer is right (true) or wrong (false)."),
             items: z
                 .array(z
                 .object({
@@ -529,7 +787,7 @@ export function registerLbbTools(server, client, options = {}) {
             sparql: z
                 .string()
                 .optional()
-                .describe("golden: the query to freeze (the search text for surface=search)."),
+                .describe("golden: the query to freeze (the search text for surface=search). label: with valid=false and no item, the right query for the question; the server checks and runs it once."),
             surface: z
                 .enum(["sparql", "search"])
                 .optional()
@@ -566,7 +824,15 @@ export function registerLbbTools(server, client, options = {}) {
                 .optional()
                 .describe("checks_summary / checks: the month, yyyy-mm (UTC). Defaults to the current month."),
             job: z
-                .enum(["rerank", "route", "rewrite", "fit", "propose", "label"])
+                .enum([
+                "rerank",
+                "route",
+                "ask",
+                "rewrite",
+                "fit",
+                "propose",
+                "label",
+            ])
                 .optional()
                 .describe("checks: only the checks of one job."),
             verdict: z
@@ -616,13 +882,19 @@ export function registerLbbTools(server, client, options = {}) {
             case "label":
                 if (!trace_id)
                     throw new Error("label requires trace_id");
-                if (!item && !items?.length)
-                    throw new Error("label requires item (with valid) or items");
                 if (item && valid === undefined)
                     throw new Error("label requires valid with item");
+                if (!item && !items?.length && valid === undefined)
+                    throw new Error("label requires item (with valid), items, or valid alone for the answer of a question");
+                if (sparql !== undefined &&
+                    (item || items?.length || valid !== false))
+                    throw new Error("label takes sparql (the right query) only with valid=false and no item");
                 return target.evals.label(trace_id, {
                     ...(item ? { item, valid } : {}),
                     ...(items?.length ? { items } : {}),
+                    // The answer of a question as a whole.
+                    ...(!item && !items?.length ? { valid } : {}),
+                    ...(sparql !== undefined ? { sparql } : {}),
                     by,
                     note,
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for little big brain: search, graph queries, and data import",
   "license": "Apache-2.0",
   "repository": {
@@ -52,7 +52,7 @@
     "test:coverage": "npm run clean:test && tsc -p tsconfig.test.json && node --test --experimental-test-coverage --test-coverage-include=test-dist/*.js --test-coverage-exclude=test-dist/*.test.js --test-coverage-exclude=test-dist/stdio.js --test-coverage-exclude=test-dist/test-support.js --test-coverage-lines=90 --test-coverage-branches=70 --test-coverage-functions=85 \"test-dist/**/*.test.js\""
   },
   "dependencies": {
-    "@littlebigbrain/client": "^0.20.0",
+    "@littlebigbrain/client": "^0.22.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },