@littlebigbrain/mcp 0.9.0 → 0.10.0

package/README.md

@@ -118,7 +118,19 @@ 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.
+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.
 
 For your own data, start with `lbb_inspect` using `action: "guide"` or
 `action: "ontology"`. Imported Resource Description Framework (RDF) data keeps
@@ -135,7 +147,7 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | `lbb_embeddings_manage` | Set up or refresh embeddings, or change the embedding model. |
 | `lbb_embeddings_delete` | Delete an embedding and its stored vectors. |
 | `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_models` | Compare retrieval settings, read model training datasets, or read a month of managed-model activity. |
 

package/dist/question.d.ts

@@ -1,20 +1,46 @@
 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;
 }
+/**
+ * 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 rewrite, 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 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.
  */
-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,11 +1,118 @@
 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 ?? {});
+    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 "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}`;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * The rewrite 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 progress.
+ */
+async function streamedRewrite(target, body, progress) {
+    const query = target.query;
+    if (typeof query.rewriteStream !== "function")
+        return undefined;
+    let step = 0;
+    for await (const event of query.rewriteStream.call(target.query, body, {
+        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 rewrite 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 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.
+ */
+function historyView(history) {
+    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);
+    return view;
+}
+/** What the agent should know about the history of the answer. */
+function historyNotes(history) {
+    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 && 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." : ""}`);
+    }
+    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.
  */
-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);
@@ -16,14 +123,17 @@ export async function answerQuestion(client, args, textFormat) {
         ...(args.route !== undefined ? { route: args.route } : {}),
         run,
         ...(run ? { 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 },
-    });
+    const response = (progress ? await streamedRewrite(target, body, progress) : undefined) ??
+        (await target.request("POST", "/v1/query/rewrite", {
+            body,
+            retry: false,
+            query: { consistency: target.defaultConsistency },
+        }));
     const { route, query, result } = response;
     const traceId = result?.trace_id ?? null;
     const answer = {
@@ -34,18 +144,23 @@ 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) } : {}),
         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>.`);
-    }
+    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.");
     }

package/dist/tool-contracts.js

@@ -4,6 +4,12 @@ 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. */
 export const QUESTION_MAX_ROWS = 1_000;
+/** Entity IRIs one question may anchor, and the characters of one. */
+export const QUESTION_MAX_ANCHORS = 10;
+export const QUESTION_MAX_ANCHOR_CHARS = 2_000;
+/** Dated points one question's timeline may carry, and the characters of a label. */
+export const QUESTION_MAX_TIMELINE = 200;
+export const QUESTION_MAX_TIMELINE_LABEL_CHARS = 200;
 export const READ_ONLY = { readOnlyHint: true };
 export const IDEMPOTENT_WRITE = {
     readOnlyHint: false,
@@ -398,7 +404,7 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
 export const SPARQL_IRI_GUIDE = 'IRI scheme: relations are <https://littlebigbrain.com/r/NAME> (NAME lowercased, e.g. writes_to; reverse a relation with the ^ path operator, no stored inverse triple). Types are <https://littlebigbrain.com/class/NAME> (lowercased), matched as `?x a <…/class/NAME>` with explicit entailment=subclass, rdfs, or owl for inference (default none). Property fields are <https://littlebigbrain.com/p/NAME> (lowercased). The local name is ALWAYS lowercase — an uppercase one (e.g. <…/r/FOR_CLIENT>) is a different, non-existent IRI that silently matches nothing; this tool auto-lowercases the local name of /r/, /class/, and /p/ IRIs for you and adds a `notes` entry when it does, so a stray uppercase still resolves. (Structured mode\'s `predicate` is case-insensitive on its own.) Entities are content-addressed <https://littlebigbrain.com/e/HASH> — never build an entity IRI from a name; anchor a named entity by its label instead: `?e <http://www.w3.org/2000/01/rdf-schema#label> "Acme"`. Discover the exact relation and type names with lbb_inspect action=ontology. SELECT and ASK only (CONSTRUCT/DESCRIBE are rejected).';
 // 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.';
+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.';
 export const queryInputSchema = z.discriminatedUnion("mode", [
     z
         .object({
@@ -495,6 +501,33 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             .boolean()
             .optional()
             .describe("question: run the query and return its rows. Defaults to true; false returns the query only."),
+        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."),
+        timeline: z
+            .array(z
+            .object({
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe("YYYY-MM-DD."),
+            as_of_commit_seq: z
+                .number()
+                .int()
+                .min(0)
+                .describe("The commit that holds the graph as it was on that date."),
+            label: z
+                .string()
+                .max(QUESTION_MAX_TIMELINE_LABEL_CHARS)
+                .optional()
+                .describe("A name for the point, such as a milestone."),
+        })
+            .strict())
+            .max(QUESTION_MAX_TIMELINE)
+            .optional()
+            .describe("question: dated points that stand for the graph's commits, at most 200. A question about a date reads the commit of the latest point on or before it. Use it when the commits stand for other dates than the days they were written (a demo's milestones, an import of old records); without it the server reads the last commit written by the end of that day."),
         ...readScope,
     })
         .strict(),
@@ -695,6 +728,48 @@ export const configureInputSchema = z.discriminatedUnion("action", [
         ...graphScope,
     })
         .strict(),
+    z
+        .object({
+        action: z.literal("get_rewrite_profile"),
+        ...graphScope,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("set_rewrite_profile"),
+        notes: z
+            .string()
+            .max(8000)
+            .optional()
+            .describe("What the data means for questions: which property holds the current state, what 'me' or 'my' means, which records to leave out. At most 8,000 characters"),
+        examples: z
+            .array(z
+            .object({
+            question: z.string().min(1).max(1000),
+            sparql: z
+                .string()
+                .min(1)
+                .max(4000)
+                .describe("A SELECT or ASK query with its PREFIX lines; the server parses it"),
+            note: z.string().max(1000).optional(),
+        })
+            .strict())
+            .max(20)
+            .optional()
+            .describe("Up to 20 worked examples: a question and the query that answers it on this graph"),
+        expected_version: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("The version get_rewrite_profile returned (0 for none): another stored version answers 409 conflict and stores nothing"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Check the profile and answer what a write would store, without storing it"),
+        ...graphScope,
+    })
+        .strict(),
 ]);
 /**
  * MCP's `registerTool` advertises a JSON Schema for an input only when the

package/dist/tool-runtime.js

@@ -660,7 +660,7 @@ export async function guide(scopedClient) {
             search_feedback: "When a result set is useful or clearly wrong, write relevance labels with lbb_commit mode=search_feedback. Use grade 3 for ideal/good results, grade 1 for partially relevant results, and grade 0 for bad results. Include the original query, search_id when present, target identity, rank, score, and an optional split train/eval/unspecified. These labels are stored in __lbb_feedback/main and later exported as qrels-style training/eval data; they are not customer facts.",
             inspect: "Use lbb_inspect for ontology, schema metadata, the published conformance report, metadata, entities, and this guide. Use lbb_query with SPARQL property paths for exact path queries.",
             ontology_decorations: "lbb_inspect action=ontology returns a decoration_status catalog: each ontology decoration is enforced (the engine acts on it — state_reducer, value_type, super_types, properties, supernode_policy; cardinality, which GET /v1/ontology/conformance audits as sh:maxCount; and inverse_name/symmetric, which SPARQL resolves as relation aliases — an inverse name is queryable directly (lowered to ^forward, no stored inverse triple) and a symmetric relation matches both directions), advisory (transitive, temporal_semantics, required), or reserved (stored but unwired — default_weight, resolvable, alias/embedding_fields). You can also always reverse any relation in SPARQL by flipping the triple pattern or using ^forward. Each relation_def also carries edge_count — the number of current edges of that relation in this graph's snapshot — so you can tell at a glance which declared relations are actually populated (edge_count 0 = declared but unused) without a separate summary call.",
-            search: "Use lbb_query mode=search to find instances by meaning. It covers every searchable class; filter narrows it by class and by relationship, and the graph checks every hit. To plan a search: (1) lbb_embeddings action=list gives the searchable classes, the facts each text is made from, and the graph's model. (2) lbb_query mode=sparql shows the relationships of a class on a sample: PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?p (COUNT(DISTINCT ?s) AS ?n) (SAMPLE(?l) AS ?example) WHERE { { SELECT ?s WHERE { ?s a <CLASS> } LIMIT 500 } ?s ?p ?o . FILTER(isIRI(?o) && ?p != rdf:type) OPTIONAL { ?o rdfs:label ?l } } GROUP BY ?p ORDER BY DESC(?n); write ?o ?p ?s for the links into the class, and SELECT ?c WHERE { ?c rdfs:subClassOf* <CLASS> } (same prefixes) for its subclasses. (3) lbb_query mode=search with filter [{class}, {via, to}] and explain=true returns the plan: the resolved relationship and entities, the allowed count, and the mode, with no model call. Check it, then run the search without explain. A name in to resolves against labels (a small typo too); an unknown relationship or name answers with the options. To search and filter in one query, use SPARQL text: PREFIX search: <https://littlebigbrain.com/search#> SELECT ?x ?score WHERE { ?x search:similarTo \"words\" ; search:score ?score . ?x a <CLASS> } ORDER BY DESC(?score) LIMIT 10. Any other pattern on ?x filters the hits; the result's search field reports the plan and complete. (4) For a question in words, rerank=true lets the rerank model (Jev) put first the hits that answer it; each hit then carries relevance (0 to 1), and the search takes about 0.3 s more. Without rerank the graph's search setting decides.",
+            search: "Use lbb_query mode=search to find instances by meaning. It covers every searchable class; filter narrows it by class and by relationship, and the graph checks every hit. To plan a search: (1) lbb_embeddings action=list gives the searchable classes, the facts each text is made from, and the graph's model. (2) lbb_query mode=sparql shows the relationships of a class on a sample: PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?p (COUNT(DISTINCT ?s) AS ?n) (SAMPLE(?l) AS ?example) WHERE { { SELECT ?s WHERE { ?s a <CLASS> } LIMIT 500 } ?s ?p ?o . FILTER(isIRI(?o) && ?p != rdf:type) OPTIONAL { ?o rdfs:label ?l } } GROUP BY ?p ORDER BY DESC(?n); write ?o ?p ?s for the links into the class, and SELECT ?c WHERE { ?c rdfs:subClassOf* <CLASS> } (same prefixes) for its subclasses. (3) lbb_query mode=search with filter [{class}, {via, to}] and explain=true returns the plan: the resolved relationship and entities, the allowed count, and the mode, with no model call. Check it, then run the search without explain. A name in to resolves against labels (a small typo too); an unknown relationship or name answers with the options. To search and filter in one query, use SPARQL text: PREFIX search: <https://littlebigbrain.com/search#> SELECT ?x ?score WHERE { ?x search:similarTo \"words\" ; search:score ?score . ?x a <CLASS> } ORDER BY DESC(?score) LIMIT 10. Any other pattern on ?x filters the hits; the result's search field reports the plan and complete. (4) For a question in words, rerank=true lets the rerank model (Jev) put first the hits that answer it; each hit then carries relevance (0 to 1), and the search takes about 0.3 s more. Without rerank the graph's search setting decides. In SPARQL text, add search:rerank true ; search:relevance ?r to the search triples and ORDER BY DESC(?r); a SPARQL search reranks only then.",
             query: "Use lbb_query for questions in plain words (mode=question), structured SPARQL-subset bodies, SPARQL text, and canned analysis. SPARQL is the only query surface; mode=question also returns the SPARQL query the server wrote for the question. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
             write: "Use lbb_commit for fact writes and relevance feedback; omitted idempotency keys are content-derived so retries dedupe. Set typed scalar attributes via entity_properties once the field is registered (add it on a live graph with lbb_configure evolve_ontology add_property). For feedback, use mode=search_feedback rather than fact triplets.",
             configure: "Use lbb_configure dry_run=true to preview definitions, ordered evolution (including add_super_types), or SHACL publication. Definition extracts native metadata; use lbb_rdf import to store full RDF/OWL and lbb_rdf update for additive INSERT DATA; RDF deletion/replacement is unsupported. Follow every lbb_inspect ontology/schema next cursor; fields are complete and metadata changes invalidate the cursor. Publication is asynchronous: inspect action=publication, then verify asserted axioms AND expected answers with lbb_query entailment=owl. SHACL conformance alone does not prove ontology completeness. First identify the questions the model must answer, reusable vocabularies, dates, evidence, and distinctions such as hypothesis versus confirmed fact.",

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { metadataPage } from "./metadata-pages.js";
-import { answerQuestion } from "./question.js";
+import { answerQuestion, } from "./question.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";
@@ -66,7 +66,7 @@ export function registerLbbTools(server, client, options = {}) {
         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.",
         inputSchema: queryWireSchema,
         annotations: READ_ONLY,
-    }, (rawArgs) => {
+    }, (rawArgs, extra) => {
         const parsed = queryInputSchema.safeParse(rawArgs);
         if (!parsed.success)
             return errorResult(parsed.error);
@@ -250,6 +250,10 @@ export function registerLbbTools(server, client, options = {}) {
                     if (search && !search.complete) {
                         notes.push(`search bound ${search.hits} of the ${search.top} hits asked for (complete: false): fewer entities satisfy the rest of the query among the candidates the search may score. When at most 20,000 entities match the other patterns, the search scores every match.`);
                     }
+                    const rerank = search?.rerank ?? undefined;
+                    if (rerank && rerank.status !== "applied") {
+                        notes.push(`search:rerank did not apply (${rerank.status}${rerank.error ? `: ${rerank.error}` : ""}): the rows hold the most similar hits, and the relevance variable is unbound.`);
+                    }
                     const data = timing.measure("query_results_parse", () => JSON.parse(response.results));
                     const rowPage = rowPageFrom(response);
                     const cursorBase = {
@@ -275,9 +279,21 @@ export function registerLbbTools(server, client, options = {}) {
         }
         if (args.mode === "question") {
             const questionArgs = args;
+            // A call with a progress token gets one notification per step of
+            // the server's work; the result is the same.
+            const progressToken = extra._meta?.progressToken;
+            const progress = progressToken === undefined
+                ? undefined
+                : {
+                    signal: extra.signal,
+                    report: (progress, message) => extra.sendNotification({
+                        method: "notifications/progress",
+                        params: { progressToken, progress, message },
+                    }),
+                };
             return (async () => {
                 try {
-                    return await answerQuestion(client, questionArgs, options.queryTextFormat);
+                    return await answerQuestion(client, questionArgs, options.queryTextFormat, progress);
                 }
                 catch (error) {
                     return errorResult(await enrichError(client, error));
@@ -789,7 +805,7 @@ export function registerLbbTools(server, client, options = {}) {
         });
     }));
     server.registerTool("lbb_configure", {
-        description: "Manage native schema metadata. Actions: define_ontology (friendly spec with super_types), evolve_ontology (ordered edits including add_super_types), list_starters (the base ontologies crm, documents and work, each with its status on the graph: absent, partial or applied, what applying adds, and conflicts), apply_starter (add what the graph lacks of a starter in one ontology version; a relation the graph has is widened; refused with starter_conflict when the graph holds a term differently; dry_run previews), publish_schema (SHACL activation), suggest_ontology_change (file a change for a person to review instead of applying it; prefer it when the graph's owner reviews ontology changes, and list the result with lbb_inspect action=ontology_suggestions). define, evolve and publish support dry_run previews. Definition/import here extracts native metadata; it does NOT store the complete RDF/OWL document as queryable graph facts. Use lbb_rdf import for full OWL and lbb_rdf update for additive INSERT DATA revisions; RDF deletions are unsupported. Publish_schema accepts unchanged ontology plus shapes; use define/evolve for native ontology changes. Publication enqueues durable conformance; a preview does not validate the whole graph.",
+        description: "Manage native schema metadata. Actions: define_ontology (friendly spec with super_types), evolve_ontology (ordered edits including add_super_types), list_starters (the base ontologies crm, documents and work, each with its status on the graph: absent, partial or applied, what applying adds, and conflicts), apply_starter (add what the graph lacks of a starter in one ontology version; a relation the graph has is widened; refused with starter_conflict when the graph holds a term differently; dry_run previews), publish_schema (SHACL activation), suggest_ontology_change (file a change for a person to review instead of applying it; prefer it when the graph's owner reviews ontology changes, and list the result with lbb_inspect action=ontology_suggestions), get_rewrite_profile and set_rewrite_profile (the graph's notes and up to 20 worked question-to-SPARQL examples that lbb_query mode=question reads for every question; pass the version you read as expected_version). define, evolve, publish and set_rewrite_profile support dry_run previews. Definition/import here extracts native metadata; it does NOT store the complete RDF/OWL document as queryable graph facts. Use lbb_rdf import for full OWL and lbb_rdf update for additive INSERT DATA revisions; RDF deletions are unsupported. Publish_schema accepts unchanged ontology plus shapes; use define/evolve for native ontology changes. Publication enqueues durable conformance; a preview does not validate the whole graph.",
         inputSchema: configureWireSchema,
         annotations: MUTATING,
     }, (rawArgs) => {
@@ -823,6 +839,18 @@ export function registerLbbTools(server, client, options = {}) {
             if (args.action === "list_starters") {
                 return scoped(client, args.graph).ontology.starters.list();
             }
+            if (args.action === "get_rewrite_profile") {
+                return scoped(client, args.graph).query.rewriteProfile();
+            }
+            if (args.action === "set_rewrite_profile") {
+                return scoped(client, args.graph).query.setRewriteProfile({
+                    notes: args.notes ?? "",
+                    examples: args.examples ?? [],
+                    ...(args.expected_version !== undefined
+                        ? { expected_version: args.expected_version }
+                        : {}),
+                }, { dryRun: args.dry_run });
+            }
             if (args.action === "apply_starter") {
                 return scoped(client, args.graph).ontology.starters.apply(args.starter, {
                     dryRun: args.dry_run,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.9.0",
+  "version": "0.10.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.19.0",
+    "@littlebigbrain/client": "^0.20.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },