@littlebigbrain/mcp 0.15.1 → 0.16.0

package/dist/tool-contracts.js

@@ -11,12 +11,6 @@ export const QUESTION_MAX_ANCHOR_CHARS = 2_000;
 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,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false,
-};
 export const MUTATING = {
     readOnlyHint: false,
     destructiveHint: false,
@@ -132,7 +126,9 @@ export const searchFeedbackSchema = z
     query: z.string().min(1),
     search_id: z.string().optional(),
     snapshot: z.record(z.string(), z.unknown()).optional(),
-    profile: z.string().optional(),
+    profile: z
+        .enum(["baseline", "scored_atom_v1", "graph_aware_v1", "ndcg_v1"])
+        .nullish(),
     model_id: z.string().optional(),
     labeler_id: z.string().optional(),
     labels: z
@@ -259,6 +255,34 @@ export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
             .boolean()
             .optional()
             .describe("Advisory required flag (not enforced on commit)"),
+        unit: z
+            .string()
+            .optional()
+            .describe("Unit of an i64 or f64 field, e.g. mm, cm, kg, m2 or h. Writers that read text, such as values.extract, convert numbers to it"),
+        allowed_values: z
+            .array(z.string())
+            .optional()
+            .describe("Enforced allowed values (sh:in): a commit with another value for the field is refused. For keyword, text, i64 and bool fields only"),
+    })
+        .strict(),
+    z
+        .object({
+        op: z.literal("set_property_unit"),
+        property: z.string().describe("An existing i64 or f64 field, by name"),
+        unit: z
+            .string()
+            .optional()
+            .describe("The unit's symbol, as add_property takes it; omit it to clear the unit. Stored values are not converted"),
+    })
+        .strict(),
+    z
+        .object({
+        op: z.literal("set_property_constraint"),
+        property: z.string().describe("An existing field, by name"),
+        allowed_values: z
+            .array(z.string())
+            .optional()
+            .describe("The allowed values that later commits are checked against; empty or absent clears the constraint. Stored values are not checked again"),
     })
         .strict(),
     z
@@ -331,16 +355,54 @@ export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
     })
         .strict(),
 ]);
+// The inputs below are as loose as the server: an optional field takes
+// null, and a field the server does not know passes through (the server
+// ignores it). 0.15 callers send `source_id: null` and `key: null`.
+/** A box on a page: 0-based page, coordinates normalized to the page (0 to 1). */
+export const regionSchema = z
+    .object({
+    page: z.number().int().nonnegative(),
+    x0: z.number().min(0).max(1),
+    y0: z.number().min(0).max(1),
+    x1: z.number().min(0).max(1),
+    y1: z.number().min(0).max(1),
+    confidence: z.number().min(0).max(1),
+})
+    .passthrough();
+/** Why a link holds: a string, or the text with its source and page box. */
+export const evidenceSchema = z.union([
+    z.string(),
+    z
+        .object({
+        text: z.string().nullish(),
+        source_id: z.string().nullish(),
+        region: regionSchema.nullish(),
+        observation_id: z.string().nullish(),
+    })
+        .passthrough(),
+]);
+/** A vector you computed for one record. */
+export const entityEmbeddingSchema = z
+    .object({
+    type: z.string(),
+    name: z.string(),
+    key: z.string().nullish(),
+    entity_id: z.string().nullish(),
+    model_id: z.string(),
+    vector: z.array(z.number()),
+    metric: z.enum(["cosine", "dot", "l2"]).nullish(),
+})
+    .passthrough();
 const namedEntityInputSchema = z
     .object({
     type: z.string(),
     name: z.string(),
     key: z
         .string()
-        .optional()
+        .nullish()
         .describe("The record's external key, when it has one"),
 })
-    .strict();
+    .passthrough();
 /** Graph facts a review item proposes; accepting commits them. */
 export const suggestedFactsSchema = z
     .object({
@@ -351,9 +413,8 @@ export const suggestedFactsSchema = z
         relation: z.string(),
         target: namedEntityInputSchema,
         confidence: z.number().min(0).max(1).optional(),
-        evidence: z
-            .unknown()
-            .optional()
+        evidence: evidenceSchema
+            .nullish()
             .describe("Why the link holds: a string, or { text, source_id } as lbb_commit takes it"),
     })
         .passthrough())
@@ -398,6 +459,127 @@ export const suggestedFactsSchema = z
 })
     .strict()
     .describe("Graph facts a person confirms: accepting commits them after the change (at most 200 triplets and property rows together). Records graphs only");
+/** The facts as the API takes them. */
+export function suggestedFactsBody(facts) {
+    return {
+        ...facts,
+        // Rows pass through as lbb_commit takes them; the server coerces each
+        // value to its field's declared type.
+        entity_properties: facts.entity_properties,
+    };
+}
+/** A person's answer to a review item, or to one value of a workflow test. */
+export const reviewAnswerSchema = z
+    .object({
+    decision: z
+        .enum(["accept", "reject", "correct", "choose", "cant_tell"])
+        .describe("accept, reject, correct (with value), choose (with option) or cant_tell"),
+    value: z
+        .union([z.number(), z.string(), z.boolean()])
+        .optional()
+        .describe("correct: the right value, in the property's type. A number may name its unit, e.g. 450 mm"),
+    option: z
+        .string()
+        .optional()
+        .describe("choose: the id of the chosen option or grade"),
+    note: z
+        .string()
+        .max(1000)
+        .optional()
+        .describe("Why, in a few words; for an answer item, the answer text. At most 1,000 characters"),
+})
+    .strict();
+/** A workflow to test before it exists: the create request of a values.extract workflow. */
+export const testInstallSchema = z
+    .object({
+    starter: z.string().describe("The starter workflow, values.extract"),
+    name: z
+        .string()
+        .optional()
+        .describe("The name the workflow would get; default the class's local name"),
+    watch: z
+        .object({
+        class: z.string().describe("The class whose instances it reads"),
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe("The fields that hold the text, as embedding paths"),
+        exclude: z.array(z.string()).optional(),
+    })
+        .strict()
+        .optional(),
+    params: jsonObjectSchema
+        .optional()
+        .describe("The starter workflow's settings, as its catalog entry lists them (the properties to fill, the context)"),
+    gate: z
+        .object({
+        below: z
+            .number()
+            .min(0)
+            .max(1)
+            .describe("Values below this support go to review"),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/** One label of `lbb_evals action=label`: a result and whether it answers the request. */
+export const evalLabelItemSchema = z
+    .object({
+    id: z.string(),
+    valid: z.boolean(),
+    note: z.string().optional(),
+})
+    .strict();
+/** A value a correct run writes, or, in leave_out, one it must not write. */
+const evalExpectedValueSchema = z
+    .object({
+    property: z.string(),
+    value: z
+        .union([z.number(), z.string(), z.boolean(), z.null()])
+        .describe("Numbers compare as numbers, text in lower case. In leave_out, null means no value at all"),
+    accept: z
+        .array(z.string())
+        .optional()
+        .describe("Other spellings a text value may take, lower case"),
+    stated: z
+        .string()
+        .optional()
+        .describe("The number and unit as the text states them, e.g. 450 mm"),
+    quote: z
+        .string()
+        .optional()
+        .describe("Words of the text that state the value"),
+    reason: z.string().optional().describe("Why a value is left out"),
+})
+    .strict();
+/** One example of a values dataset. */
+export const evalDatasetItemSchema = z
+    .object({
+    name: z
+        .string()
+        .describe("The input's name, unique in the dataset; the same name replaces"),
+    text: z
+        .string()
+        .max(40_000)
+        .optional()
+        .describe("The input text, at most 40,000 characters"),
+    values: z.array(evalExpectedValueSchema).optional(),
+    leave_out: z.array(evalExpectedValueSchema).optional(),
+    iri: z.string().optional().describe("The instance the input came from"),
+    case: z
+        .string()
+        .optional()
+        .describe("What the example shows, in one sentence"),
+    source: z
+        .object({
+        kind: z.enum(["test", "review", "answer_key"]),
+        id: z.string().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const inspectInputSchema = z.discriminatedUnion("action", [
     z.object({ action: z.literal("guide"), ...readScope }).strict(),
     z
@@ -444,6 +626,36 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
     z
         .object({
         action: z.literal("entity"),
+        version: z.literal("records/1").optional(),
+        iri: z
+            .string()
+            .optional()
+            .describe("Authoritative full RDF IRI; selects the lossless records/1 read."),
+        key: z
+            .string()
+            .optional()
+            .describe("Stable key with entity_type, resolved from the activated schema at the read snapshot."),
+        schema_revision: z
+            .string()
+            .optional()
+            .describe("Expected opaque schema revision for a records/1 read."),
+        consistency: z.enum(["strong", "eventual"]).optional(),
+        limits: z
+            .object({
+            properties: z.number().int().positive().max(10_000).optional(),
+            outgoing: z.number().int().positive().max(10_000).optional(),
+            incoming: z.number().int().positive().max(10_000).optional(),
+            assertions: z.number().int().positive().max(100).optional(),
+            assertion_statements: z
+                .number()
+                .int()
+                .positive()
+                .max(10_000)
+                .optional(),
+        })
+            .strict()
+            .optional()
+            .describe("Lossless records/1 section bounds. Exceeding a bound refuses the read instead of truncating it."),
         entity_id: z
             .string()
             .optional()
@@ -465,10 +677,9 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
     })
         .strict(),
 ]);
-// The graph's RDF projection uses a fixed IRI scheme; teaching it here lets an
-// agent write a valid query on the first attempt instead of round-tripping
-// through the ontology to reverse-engineer term IRIs.
-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).';
+// Native records use a conventional projection; imported RDF keeps its exact IRIs.
+// Explain both so agents do not remint or normalize arbitrary vocabulary.
+export const SPARQL_IRI_GUIDE = 'Imported RDF retains its exact, case-sensitive IRIs. Use returned IRIs unchanged; lbb_inspect action=entity iri=<full IRI> reads any subject with records/1. The following convention applies only to native records: 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. 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.';

package/dist/tool-runtime.js

@@ -212,6 +212,18 @@ export function compactLimits(detail) {
             return { maxItems: 5, maxString: 300 };
     }
 }
+/**
+ * Items one list page asks for: `limit`, at most `most` (the route's own
+ * cap) and at most the items the detail level shows (5, 20 or 100), so the
+ * detail level never cuts the page. A page over the output budget
+ * (HARD_OUTPUT_CHARS) is cut too: `runPage` then asks the server again for
+ * the items that fit, so next_cursor continues after the last item the
+ * caller saw.
+ */
+export function pageLimit(detail, limit, most) {
+    const shown = compactLimits(normalizeDetail(detail)).maxItems;
+    return Math.min(limit ?? shown, shown, most);
+}
 export function truncateValue(value, limits, state) {
     if (typeof value === "string") {
         if (value.length <= limits.maxString)
@@ -267,10 +279,75 @@ export function defaultSummary(label, value, truncated) {
         : "";
     return `${label}${countText}${truncated ? " [truncated]" : ""}`;
 }
+/** The next_cursor of a list page, kept whole: a cut cursor is no cursor. */
+function keepCursor(value, data) {
+    const cursor = value?.next_cursor;
+    return typeof cursor === "string" && data && typeof data === "object"
+        ? { ...data, next_cursor: cursor }
+        : data;
+}
+/** The items of a list page (`{data, has_more, next_cursor}`), else undefined. */
+function pageItems(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const page = value;
+    return Array.isArray(page.data) &&
+        ("next_cursor" in page || "has_more" in page)
+        ? page.data
+        : undefined;
+}
+/** Whether the envelope of `value` fits the output budget without the hard cap. */
+function fitsOutput(label, value, detailArg) {
+    const detail = normalizeDetail(detailArg);
+    const state = { truncated: false };
+    const data = keepCursor(value, truncateValue(value, compactLimits(detail), state));
+    const text = JSON.stringify({
+        summary: defaultSummary(label, value, state.truncated),
+        data,
+        counts: countsFor(value),
+        truncated: state.truncated || undefined,
+        next: state.truncated ? { detail: nextDetail(detail) } : undefined,
+    }, null, 2);
+    // A margin for the fields the envelope adds beside the page.
+    return text.length <= HARD_OUTPUT_CHARS - 512;
+}
+/**
+ * Run a call that answers one list page. `fetch(limit)` asks the server
+ * for at most `limit` items after the call's cursor. When the page does
+ * not fit the output budget, the envelope would cut it to a few items
+ * while next_cursor points after the last item asked for; so the server
+ * is asked again for the items that fit, and next_cursor continues after
+ * the last item shown.
+ */
+export async function runPage(client, label, detail, limit, fetch) {
+    try {
+        let page = await fetch(limit);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const items = pageItems(page);
+            if (!items || items.length <= 1 || fitsOutput(label, page, detail))
+                break;
+            let lo = 1;
+            let hi = items.length - 1;
+            while (lo < hi) {
+                const mid = Math.ceil((lo + hi) / 2);
+                const fits = fitsOutput(label, { ...page, data: items.slice(0, mid) }, detail);
+                if (fits)
+                    lo = mid;
+                else
+                    hi = mid - 1;
+            }
+            page = await fetch(lo);
+        }
+        return toolResult(envelope(label, page, detail));
+    }
+    catch (error) {
+        return errorResult(await enrichError(client, error));
+    }
+}
 export function envelope(label, value, detailArg, next) {
     const detail = normalizeDetail(detailArg);
     const state = { truncated: false };
-    let data = truncateValue(value, compactLimits(detail), state);
+    let data = keepCursor(value, truncateValue(value, compactLimits(detail), state));
     let result = {
         summary: defaultSummary(label, value, state.truncated),
         data,
@@ -284,7 +361,7 @@ export function envelope(label, value, detailArg, next) {
     if (text.length <= HARD_OUTPUT_CHARS)
         return result;
     const hardState = { truncated: true };
-    data = truncateValue(value, { maxItems: 3, maxString: 120 }, hardState);
+    data = keepCursor(value, truncateValue(value, { maxItems: 3, maxString: 120 }, hardState));
     result = {
         summary: `${label} [hard-capped for MCP output]`,
         data,
@@ -297,10 +374,10 @@ export function envelope(label, value, detailArg, next) {
         return result;
     return {
         summary: `${label} [hard-capped for MCP output]`,
-        data: {
+        data: keepCursor(value, {
             note: "The response was too large for the MCP tool result. Narrow the query or request a smaller top_k.",
             preview: text.slice(0, 20_000),
-        },
+        }),
         counts: countsFor(value),
         truncated: true,
         next: { ...(next ?? {}), detail: "full" },
@@ -404,6 +481,14 @@ export function toolResult(value) {
         structuredContent: value,
     };
 }
+/** An error the tool raises itself, with its own code (`approval_declined`). */
+export class ToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
 export function errorResult(error) {
     const payload = error instanceof LbbError
         ? {
@@ -417,7 +502,7 @@ export function errorResult(error) {
         }
         : {
             type: "tool_error",
-            code: "tool_error",
+            code: error instanceof ToolError ? error.code : "tool_error",
             message: error instanceof Error ? error.message : String(error),
             param: null,
             request_id: null,
@@ -709,6 +794,7 @@ export async function analyze(scopedClient, p) {
     }
     else if (metric === "sparql") {
         const body = requireObject(p.sparql, "sparql");
+        // The body is the caller's JSON; the server checks it.
         const res = (await scopedClient.sparql(body));
         const groups = res.groups ?? [];
         const first = groups[0];