@littlebigbrain/mcp 0.9.0 → 0.11.0

package/README.md

@@ -114,11 +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 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
@@ -129,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), or publish validation rules. |
+| `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

@@ -1,20 +1,48 @@
 import type { LbbClient } from "@littlebigbrain/client";
 type QuestionRoute = "lookup" | "aggregate" | "search" | "history" | "schema" | "unanswerable";
+/** A date and the commit that holds the graph as it was then. */
+interface TimelinePoint {
+    date: string;
+    as_of_commit_seq: number;
+    label?: string;
+}
 export interface QuestionArgs {
     question: string;
     context?: string;
     route?: QuestionRoute;
     limit?: number;
-    run?: boolean;
+    anchor?: string[];
+    timeline?: TimelinePoint[];
     detail?: string;
     graph?: string;
 }
 /**
- * `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`.
+ * Progress of one question: the tool call asked for it with a
+ * `_meta.progressToken`. `report` sends one MCP progress notification.
+ */
+export interface QuestionProgress {
+    /** Stops the server's work when the tool call is cancelled. */
+    signal?: AbortSignal;
+    report(progress: number, message: string): Promise<void>;
+}
+/** One event of a streamed question, as this tool reads it. */
+type StreamEvent = {
+    event: string;
+    data: unknown;
+};
+/** 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 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"): Promise<{
+export declare function answerQuestion(client: LbbClient, args: QuestionArgs, textFormat?: "compact" | "pretty", progress?: QuestionProgress): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/question.js

@@ -1,32 +1,189 @@
+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";
+/** The progress message of a stream event, in short plain words. */
+export function progressMessage(event) {
+    const data = (event.data ?? {});
+    switch (event.event) {
+        case "grounding":
+            return "Read the graph description";
+        case "route": {
+            const confidence = typeof data.confidence === "number"
+                ? `, ${data.confidence.toFixed(2)}`
+                : "";
+            return `Route: ${String(data.kind)} (${String(data.by)}${confidence})`;
+        }
+        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 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.askStream` answers
+ * without progress.
+ */
+async function streamedAnswer(target, body, progress) {
+    const query = target.query;
+    if (typeof query.askStream !== "function")
+        return undefined;
+    const { question, ...options } = body;
+    let step = 0;
+    for await (const event of query.askStream.call(target.query, question, {
+        ...options,
+        signal: progress.signal,
+    })) {
+        if (event.event === "done")
+            return event.data;
+        const message = progressMessage(event);
+        if (message === undefined)
+            continue;
+        step += 1;
+        // A lost notification never fails the question.
+        await progress.report(step, message).catch(() => undefined);
+    }
+    throw new Error("the answer stream ended before its done event");
+}
+/** 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, 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, limit) {
+    const view = { ...history };
+    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, limit, query) {
+    if (!history)
+        return [];
+    const notes = [];
+    const point = typeof history.as_of_commit_seq === "number"
+        ? `commit ${history.as_of_commit_seq}${history.label ? ` (${history.label})` : ""}`
+        : undefined;
+    if (history.as_of_date && point) {
+        const by = history.resolved_by === "timeline"
+            ? "the timeline"
+            : history.resolved_by === "commit_time"
+                ? "the commit times"
+                : "the request";
+        notes.push(`The question names ${history.as_of_date}; the server read ${point}, found by ${by}.`);
+    }
+    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 || 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`.
+ * `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) {
+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 = await target.request("POST", "/v1/query/rewrite", {
-        body,
-        retry: false,
-        query: { consistency: target.defaultConsistency },
-    });
+    // 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 },
+        }));
     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,
@@ -34,20 +191,27 @@ export async function answerQuestion(client, args, textFormat) {
         ...(typeof query?.as_of_commit_seq === "number"
             ? { as_of_commit_seq: query.as_of_commit_seq }
             : {}),
-        ...(response.history ? { history: response.history } : {}),
+        ...(response.history
+            ? { history: historyView(response.history, listLimit(detail)) }
+            : {}),
         error: response.error ?? null,
         trace_id: traceId,
         attempts: response.attempts,
+        ...(response.linked?.length ? { linked: response.linked } : {}),
+        ...(response.anchors?.length ? { anchors: response.anchors } : {}),
     };
     const notes = [];
+    for (const anchor of response.anchors ?? []) {
+        if (anchor.note) {
+            notes.push(`anchor ${anchor.iri}: ${anchor.note}.`);
+        }
+    }
     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=[…]).`);
     }
-    if (response.history?.as_of_date) {
-        notes.push(`The question names the date ${response.history.as_of_date}. Find the commit of that date, then run the query with lbb_query mode=sparql as_of_commit_seq=<commit>.`);
-    }
-    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
@@ -71,13 +235,15 @@ export async function answerQuestion(client, args, textFormat) {
         };
         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 ?? {}) },