@littlebigbrain/mcp 0.10.0 → 0.12.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,23 @@ 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_workflows` | List the starter workflows this server offers and the workflows created from them on a graph (triggered workflows), read one with its status, and preview a new one. |
+| `lbb_workflows_manage` | Create a workflow from a starter workflow on a class (a developer workflow with its workflow type, owned outputs and batch), ask it to run now, or pause and resume a developer workflow. |
+| `lbb_workflows_delete` | Delete a triggered workflow. What it wrote stays. |
+| `lbb_files` | List the files of a graph, and read the parsed pages of one: each line with its id, its box on the page and its text. |
 | `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/files-tool.d.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LbbClient, Schemas } from "@littlebigbrain/client";
+/** Lines one `pages` call returns by default, and at most. */
+export declare const FILE_LINES_DEFAULT = 200;
+export declare const FILE_LINES_MAX = 1000;
+/** Characters of one line's text a call shows; a longer text is cut with "…". */
+export declare const FILE_LINE_CHARS = 400;
+/** Characters of lines one call returns at most, so the result fits an MCP answer. */
+export declare const FILE_LINES_BUDGET = 60000;
+type FilePage = Schemas["FilePage"];
+/** One line as the tool shows it: `<id> [x0,y0,x1,y1] <text>`. */
+export declare function fileLineText(line: Schemas["FileLine"]): string;
+export interface PageLinesWindow {
+    /** Lines of the first page to skip (they were shown by the call before). */
+    lineOffset: number;
+    maxLines: number;
+    /** Only lines whose text holds this, ignoring case. */
+    contains?: string;
+}
+export interface PageLinesAnswer {
+    pages: Array<{
+        page: number;
+        width: number;
+        height: number;
+        lines_total: number;
+        lines_matching: number;
+        lines: string[];
+    }>;
+    shown: number;
+    /** Where the next call starts when lines were left out. */
+    next?: {
+        from: number;
+        line_offset: number;
+    };
+}
+/**
+ * The lines of parsed pages as short strings, at most `maxLines` and
+ * {@link FILE_LINES_BUDGET} characters, from `lineOffset` of the first page.
+ * `next` names the page and the offset of the first line left out.
+ */
+export declare function pageLines(pages: FilePage[], window: PageLinesWindow): PageLinesAnswer;
+export declare function registerFilesTool(server: McpServer, client: LbbClient): void;
+export {};

package/dist/files-tool.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { READ_ONLY, detailSchema, graphScope } from "./tool-contracts.js";
+import { enrichError, errorResult, run, scoped, toolResult, } from "./tool-runtime.js";
+/** Lines one `pages` call returns by default, and at most. */
+export const FILE_LINES_DEFAULT = 200;
+export const FILE_LINES_MAX = 1_000;
+/** Characters of one line's text a call shows; a longer text is cut with "…". */
+export const FILE_LINE_CHARS = 400;
+/** Characters of lines one call returns at most, so the result fits an MCP answer. */
+export const FILE_LINES_BUDGET = 60_000;
+/** One line as the tool shows it: `<id> [x0,y0,x1,y1] <text>`. */
+export function fileLineText(line) {
+    const text = line.text.length > FILE_LINE_CHARS
+        ? `${line.text.slice(0, FILE_LINE_CHARS - 1)}…`
+        : line.text;
+    return `${line.id} [${line.box.join(",")}] ${text}`;
+}
+/**
+ * The lines of parsed pages as short strings, at most `maxLines` and
+ * {@link FILE_LINES_BUDGET} characters, from `lineOffset` of the first page.
+ * `next` names the page and the offset of the first line left out.
+ */
+export function pageLines(pages, window) {
+    const needle = window.contains?.trim().toLowerCase();
+    const answer = { pages: [], shown: 0 };
+    let budget = FILE_LINES_BUDGET;
+    for (const [index, page] of pages.entries()) {
+        const skip = index === 0 ? window.lineOffset : 0;
+        const shown = [];
+        let matching = 0;
+        let stoppedAt;
+        for (const [position, line] of page.lines.entries()) {
+            if (position < skip)
+                continue;
+            if (needle && !line.text.toLowerCase().includes(needle))
+                continue;
+            matching += 1;
+            if (stoppedAt !== undefined)
+                continue;
+            const text = fileLineText(line);
+            if (answer.shown >= window.maxLines || text.length > budget) {
+                stoppedAt = position;
+                continue;
+            }
+            shown.push(text);
+            answer.shown += 1;
+            budget -= text.length;
+        }
+        answer.pages.push({
+            page: page.page,
+            width: page.width,
+            height: page.height,
+            lines_total: page.lines.length,
+            lines_matching: matching,
+            lines: shown,
+        });
+        if (stoppedAt !== undefined) {
+            answer.next = { from: page.page, line_offset: stoppedAt };
+            break;
+        }
+    }
+    return answer;
+}
+const SHA256 = /^[0-9a-fA-F]{64}$/;
+/** The SHA-256 of the file a call names, by `sha256` or by its exact name. */
+async function fileSha(target, args) {
+    if (args.sha256) {
+        if (!SHA256.test(args.sha256.trim()))
+            throw new Error("sha256 is 64 hexadecimal characters");
+        return { sha256: args.sha256.trim().toLowerCase() };
+    }
+    if (!args.name)
+        throw new Error("pages needs sha256 or name");
+    const { files } = await target.files.list();
+    const named = files.filter((file) => file.name === args.name);
+    if (named.length === 1)
+        return { sha256: named[0].sha256, name: named[0].name };
+    if (named.length > 1)
+        throw new Error(`several files are named ${args.name}; pass sha256: ${named.map((file) => file.sha256).join(", ")}`);
+    const names = files.slice(0, 20).map((file) => file.name);
+    throw new Error(`no file is named ${args.name}${names.length ? `; the graph has ${names.join(", ")}` : "; the graph has no files"}`);
+}
+export function registerFilesTool(server, client) {
+    server.registerTool("lbb_files", {
+        description: "Files of the graph, read only. A file is a document the graph holds (its bytes and a Document entity); the documents.parse workflow (lbb_workflows) reads the text layer of each PDF into pages with every line and its box. list shows the files with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count). pages reads parsed pages of one file (sha256, or name for an exact file name): from is the first 0-based page index (the page of a region and of a DocEntry or DocMention), to the page after the last one (default from+1). Each line comes as `<line id> [x0,y0,x1,y1] <text>`: the id is p<page number>-l<line number>, both from 1, and the box is normalized to the page (0 to 1, origin top left). contains keeps the lines that hold a text; max_lines caps the lines (default 200). When lines were left out, next names the from and line_offset of the next call. A file not parsed yet answers file_not_parsed.",
+        inputSchema: {
+            action: z.enum(["list", "pages"]),
+            sha256: z
+                .string()
+                .optional()
+                .describe("pages: the file's SHA-256 (64 hex characters)."),
+            name: z
+                .string()
+                .optional()
+                .describe("pages: the file's exact name, when you do not have its sha256."),
+            from: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("pages: the first page index, 0-based. Default 0."),
+            to: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("pages: the page index after the last one. Default from+1; at most 50 pages per call."),
+            line_offset: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("pages: lines of the first page to skip, from a previous call's next."),
+            max_lines: z
+                .number()
+                .int()
+                .positive()
+                .max(FILE_LINES_MAX)
+                .optional()
+                .describe(`pages: the most lines to return. Default ${FILE_LINES_DEFAULT}.`),
+            contains: z
+                .string()
+                .optional()
+                .describe("pages: only the lines whose text holds this, ignoring case."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        const target = scoped(client, args.graph);
+        if (args.action === "list") {
+            return run(client, "lbb_files.list", args.detail, async () => {
+                const { files } = await target.files.list();
+                return { files };
+            });
+        }
+        try {
+            const file = await fileSha(target, args);
+            const from = args.from ?? 0;
+            const to = args.to ?? from + 1;
+            if (to <= from)
+                throw new Error("to must be above from");
+            const answer = await target.files.pages(file.sha256, { from, to });
+            const lines = pageLines(answer.pages, {
+                lineOffset: args.line_offset ?? 0,
+                maxLines: args.max_lines ?? FILE_LINES_DEFAULT,
+                contains: args.contains,
+            });
+            const label = file.name ?? answer.sha256.slice(0, 12);
+            const range = answer.to - answer.from > 1
+                ? `pages ${answer.from} to ${answer.to - 1}`
+                : `page ${answer.from}`;
+            return toolResult({
+                summary: `${label}, ${range} of ${answer.page_count} (0-based): ${lines.shown} lines${lines.next ? ", more after next" : ""}`,
+                data: {
+                    sha256: answer.sha256,
+                    parser: answer.parser,
+                    page_count: answer.page_count,
+                    from: answer.from,
+                    to: answer.to,
+                    line_format: "<line id> [x0,y0,x1,y1] <text>",
+                    pages: lines.pages,
+                },
+                ...(lines.next
+                    ? {
+                        truncated: true,
+                        next: {
+                            action: "pages",
+                            sha256: answer.sha256,
+                            from: lines.next.from,
+                            to: answer.to,
+                            line_offset: lines.next.line_offset,
+                            ...(args.contains ? { contains: args.contains } : {}),
+                        },
+                    }
+                    : {}),
+            });
+        }
+        catch (error) {
+            return errorResult(await enrichError(client, error));
+        }
+    });
+}

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: {