@littlebigbrain/mcp 0.10.0 → 0.12.0

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;
@@ -331,6 +331,73 @@ export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
     })
         .strict(),
 ]);
+const namedEntityInputSchema = z
+    .object({
+    type: z.string(),
+    name: z.string(),
+    key: z
+        .string()
+        .optional()
+        .describe("The record's external key, when it has one"),
+})
+    .strict();
+/** Graph facts a review item proposes; accepting commits them. */
+export const suggestedFactsSchema = z
+    .object({
+    triplets: z
+        .array(z
+        .object({
+        source: namedEntityInputSchema,
+        relation: z.string(),
+        target: namedEntityInputSchema,
+        confidence: z.number().min(0).max(1).optional(),
+        evidence: z
+            .unknown()
+            .optional()
+            .describe("Why the link holds: a string, or { text, source_id } as lbb_commit takes it"),
+    })
+        .passthrough())
+        .max(200)
+        .optional()
+        .describe("Links to commit, as lbb_commit takes triplets"),
+    entity_properties: z
+        .array(jsonObjectSchema)
+        .max(200)
+        .optional()
+        .describe("Fields to commit, each { type, name, properties: { field: value } } as lbb_commit takes them"),
+    replace_owned: z
+        .object({
+        subjects: z
+            .array(namedEntityInputSchema)
+            .max(1000)
+            .describe("The records this write is for"),
+        relations: z
+            .array(z.string())
+            .max(64)
+            .optional()
+            .describe("Owned relations: their current out-edges of the subjects that the facts do not write again are removed"),
+        properties: z
+            .array(z.string())
+            .max(64)
+            .optional()
+            .describe("Owned fields: the ones the facts do not set on a subject are removed"),
+        retract_entities: z
+            .array(namedEntityInputSchema)
+            .max(1000)
+            .optional()
+            .describe("Records the producer made and no longer makes"),
+    })
+        .strict()
+        .optional()
+        .describe("Replace the producer's owned edges and fields on its subjects in the same commit"),
+    summary: z
+        .string()
+        .max(500)
+        .optional()
+        .describe("One line about the facts for the reviewer"),
+})
+    .strict()
+    .describe("Graph facts a person confirms: accepting commits them after the change (at most 200 triplets and property rows together). Records graphs only");
 export const inspectInputSchema = z.discriminatedUnion("action", [
     z.object({ action: z.literal("guide"), ...readScope }).strict(),
     z
@@ -405,6 +472,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 +525,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 +552,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 +567,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 +615,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 +679,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
@@ -690,9 +840,10 @@ export const configureInputSchema = z.discriminatedUnion("action", [
             .describe("Short imperative text, e.g. 'Add class Contractor'"),
         change: z
             .array(ontologyEvolveOpSchema)
-            .min(1)
             .max(128)
-            .describe("The ontology operations a person applies by accepting, in order (same shapes as evolve_ontology ops)"),
+            .optional()
+            .describe("The ontology operations a person applies by accepting, in order (same shapes as evolve_ontology ops). Up to 128; may be empty or absent when facts is set"),
+        facts: suggestedFactsSchema.optional(),
         rationale: z
             .string()
             .max(4000)