@littlebigbrain/mcp 0.11.0 → 0.13.0

package/README.md

@@ -155,6 +155,10 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | `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. |

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/tool-contracts.js

@@ -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
@@ -773,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)

package/dist/tools.js

@@ -3,13 +3,15 @@ import { metadataPage } from "./metadata-pages.js";
 import { answerQuestion, } from "./question.js";
 import { commitAt, compareQuery, describeGraph, findNames, } from "./query-tools.js";
 import { registerRdfTool } from "./rdf-tool.js";
+import { registerFilesTool } from "./files-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";
 import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, queryToolResult, requireString, rowPageFrom, rowPageNext, run, scoped, stableJson, toolResult, } from "./tool-runtime.js";
 export function registerLbbTools(server, client, options = {}) {
     registerRdfTool(server, client);
+    registerFilesTool(server, client);
     server.registerTool("lbb_inspect", {
-        description: "Read graph context and exact graph facts. Actions: guide, graphs, publication, ontology, ontology_conformance, schema, ontology_search, metadata, entity, ontology_suggestions. graphs works before bootstrap; ontology_suggestions lists the ontology change suggestions that wait for review (or were decided). publication reports whether writes are queryable. ontology and schema return complete entries with page_size, section and cursor; follow next until absent. schema reads active native ontology/SHACL metadata without running validation. Query asserted RDF/OWL axioms separately with lbb_query. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's attributes and current relationships from the RDF read. For a node's past values, run SPARQL with as_of_commit_seq through lbb_query. Use lbb_query with SPARQL property paths for precise path selection.",
+        description: "Read graph context and exact graph facts. Actions: guide, graphs, publication, ontology, ontology_conformance, schema, ontology_search, metadata, entity, ontology_suggestions. graphs works before bootstrap; ontology_suggestions lists the ontology change suggestions that wait for review (or were decided); fact_count is how many graph facts (triplets and entity property rows) accepting one commits, and identity_count how many identities it links. publication reports whether writes are queryable. ontology and schema return complete entries with page_size, section and cursor; follow next until absent. schema reads active native ontology/SHACL metadata without running validation. Query asserted RDF/OWL axioms separately with lbb_query. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's attributes and current relationships from the RDF read. For a node's past values, run SPARQL with as_of_commit_seq through lbb_query. Use lbb_query with SPARQL property paths for precise path selection.",
         inputSchema: inspectWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -356,7 +358,7 @@ export function registerLbbTools(server, client, options = {}) {
         });
     });
     server.registerTool("lbb_models", {
-        description: "Read model-training inputs or compare retrieval configurations over one pinned published snapshot, or read what the managed models did. shadow_eval takes the API ShadowEvalRequest body; dataset actions return bounded training examples at an optional signal split. activity reads one month of the stack's model use (all graphs): calls, items, estimated tokens and cost per feature (index, search, fit, judge, training) and model, by day and by graph, the months with activity, and the model each feature uses now.",
+        description: "Read model-training inputs or compare retrieval configurations over one pinned published snapshot, or read what the managed models did. shadow_eval takes the API ShadowEvalRequest body; dataset actions return bounded training examples at an optional signal split. activity reads one month of the stack's model use (all graphs): calls, items, estimated tokens and cost per feature (index, search, fit, judge, training, rerank, rewrite, trial, workflows) and model, by day and by graph, the workflows' calls per workflow and job (by_workflow), the months with activity, and the model each feature uses now.",
         inputSchema: {
             action: z.enum([
                 "shadow_eval",
@@ -603,6 +605,190 @@ export function registerLbbTools(server, client, options = {}) {
         }
         return scoped(client, graph).ontology.fitSources.delete(name);
     }));
+    // Starter workflows and triggered workflows: one API over everything that
+    // runs when a class of the graph changes. search.embed and ontology.fit
+    // are the embeddings and fit sources above, through the same stored
+    // documents.
+    const workflowSetup = {
+        starter: z
+            .string()
+            .optional()
+            .describe("The starter workflow's catalog id from action=starters, e.g. search.embed (embeddings on a class), ontology.fit (fit from text) or workflow (a developer workflow: your worker's workflow gets the instances). get/preview/use/refresh/pause/resume: required."),
+        class: z
+            .string()
+            .optional()
+            .describe("preview/use: the class whose instances the workflow watches (an IRI, or a name the ontology knows). Required unless the starter workflow's watch is fixed."),
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe("preview/use: the fields whose change triggers the workflow, as embedding paths (transcript, label, about/label, <https://…>). Omit for the starter workflow's own choice."),
+        exclude: z
+            .array(z.string())
+            .optional()
+            .describe("preview/use: fields to drop from the automatic choice."),
+        params: jsonObjectSchema
+            .optional()
+            .describe('preview/use: the starter workflow\'s own settings, as listed in its catalog entry: search.embed takes model, dim and title; ontology.fit takes context (one sentence about the text, e.g. {"context": "interviews with employees"}); workflow takes none.'),
+        workflow: z
+            .object({
+            workflow_type: z
+                .string()
+                .describe("The workflow type your worker serves, e.g. word-count."),
+            version: z.string().describe("Its version, e.g. v1."),
+        })
+            .strict()
+            .optional()
+            .describe("preview/use, developer workflow (starter=workflow) only, required there: the workflow of your worker that receives the messages. Creating it creates the instance starter.<name>."),
+        owns: z
+            .object({
+            classes: z.array(z.string()).max(64).optional(),
+            relations: z.array(z.string()).max(64).optional(),
+            properties: z.array(z.string()).max(64).optional(),
+        })
+            .strict()
+            .optional()
+            .describe("preview/use, developer workflow only: what your code writes. classes it creates instances of, relations it writes as out-edges of the watched instances, properties it writes on them. Owned outputs never trigger the workflow itself."),
+        batch: z
+            .number()
+            .int()
+            .min(1)
+            .max(64)
+            .optional()
+            .describe("preview/use, developer workflow only: instances per message, 1 to 64 (default 16)."),
+    };
+    const workflowRequest = (args) => {
+        if (!args.starter)
+            throw new Error("this action requires starter");
+        if (!args.class && (args.fields || args.exclude)) {
+            throw new Error("fields and exclude need class");
+        }
+        return {
+            starter: args.starter,
+            ...(args.name ? { name: args.name } : {}),
+            ...(args.class
+                ? {
+                    watch: {
+                        class: args.class,
+                        ...(args.fields ? { fields: args.fields } : {}),
+                        ...(args.exclude ? { exclude: args.exclude } : {}),
+                    },
+                }
+                : {}),
+            ...(args.params ? { params: args.params } : {}),
+            ...(args.gate !== undefined ? { gate: { below: args.gate } } : {}),
+            ...(args.budget_usd_per_month !== undefined
+                ? { budget_usd_per_month: args.budget_usd_per_month }
+                : {}),
+            ...(args.workflow ? { workflow: args.workflow } : {}),
+            ...(args.owns ? { owns: args.owns } : {}),
+            ...(args.batch !== undefined ? { batch: args.batch } : {}),
+        };
+    };
+    const workflowRef = (args) => {
+        if (!args.starter || !args.name) {
+            throw new Error("this action requires starter and name");
+        }
+        return { starter: args.starter, name: args.name };
+    };
+    server.registerTool("lbb_workflows", {
+        description: "Starter workflows and triggered workflows, read only. A starter workflow is a template; a triggered workflow is a workflow created from one on the graph. It watches a class: when a published commit adds or changes instances of the class (or changes the watched fields), the workflow reads them and does its work. search.embed keeps an embedding of the class (the same as lbb_embeddings); ontology.fit reads text fields and files ontology suggestions (the same as lbb_fit_sources); workflow (a developer workflow) sends the new and changed instances to a workflow of the developer's worker as trigger messages, and that code writes the facts the workflow owns. documents.parse reads uploaded PDF files into pages with line boxes, documents.link connects mentions of the same thing across the documents (it writes DocEntry and DocMention instances and links each mention to the entry that defines or describes it), documents.map proposes each link as a FactProposal in the graph's own ontology (fact_subject, fact_predicate, fact_object, fact_confidence, fact_evidence) for a review workflow, and values.extract fills chosen properties from text, each value with a quote; read the files and their pages with lbb_files. starters lists the starter workflows this server offers with their group, settings and whether each can run here. list shows every triggered workflow of the graph with its state (backfilling, ready, paused, failed, unavailable), lag, counters, this month's spend and last error; get shows one (starter and name) with its own status in details (for workflow: the messages sent, the instances waiting, the message in flight and whether it is paused). preview shows what creating one would do (the resolved watch, the instance count and the workflow's own preview; for workflow, the first messages it would send), calls no model and stores nothing. Message workflows of the workflow engine are not listed here. Create, refresh, pause or resume with lbb_workflows_manage; delete with lbb_workflows_delete.",
+        inputSchema: {
+            action: z.enum(["starters", "list", "get", "preview"]),
+            name: z
+                .string()
+                .optional()
+                .describe("get: the triggered workflow's name. preview: the name a new workflow would get."),
+            ...workflowSetup,
+            sample: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe("preview: how many sample instances to show."),
+            iris: z
+                .array(z.string())
+                .optional()
+                .describe("preview: the instances to show instead of a sample."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, (args) => run(client, `lbb_workflows.${args.action}`, args.detail, () => {
+        const workflows = scoped(client, args.graph).workflows;
+        switch (args.action) {
+            case "starters":
+                return workflows.starters.list();
+            case "list":
+                return workflows.triggered.list();
+            case "get":
+                return workflows.triggered.get(workflowRef(args));
+            case "preview":
+                return workflows.triggered.preview({
+                    ...workflowRequest(args),
+                    ...(args.sample ? { sample: args.sample } : {}),
+                    ...(args.iris ? { iris: args.iris } : {}),
+                });
+        }
+    }));
+    server.registerTool("lbb_workflows_manage", {
+        description: "Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. A workflow that calls models (ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending; resume lets it catch up. search.embed and ontology.fit cannot be paused.",
+        inputSchema: {
+            action: z.enum(["use", "refresh", "pause", "resume"]),
+            name: z
+                .string()
+                .optional()
+                .describe("The triggered workflow's name, [a-z0-9][a-z0-9-]{0,62} (refresh, pause, resume: required; use: omit for the class's local name)."),
+            ...workflowSetup,
+            gate: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("use: outputs below this confidence go to review instead of the graph, for a workflow with a review gate."),
+            budget_usd_per_month: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("use: a monthly model budget in USD for this workflow, below the stack's own."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_workflows_manage.${args.action}`, args.detail, () => {
+        const workflows = scoped(client, args.graph).workflows;
+        switch (args.action) {
+            case "use":
+                return workflows.starters.use(workflowRequest(args));
+            case "refresh":
+                return workflows.triggered.refresh(workflowRef(args));
+            case "pause":
+                return workflows.triggered.pause(workflowRef(args), true);
+            case "resume":
+                return workflows.triggered.pause(workflowRef(args), false);
+        }
+    }));
+    server.registerTool("lbb_workflows_delete", {
+        description: "Delete a triggered workflow: it stops following its class, and what it wrote stays. Deleting search.embed deletes the embedding and its vectors, so its class stops being searchable; the suggestions an ontology.fit filed stay; a developer workflow leaves its workflow instance and the facts its code wrote. Ask the user first; confirm must repeat the name.",
+        inputSchema: {
+            starter: z
+                .string()
+                .describe("The starter workflow's catalog id, e.g. search.embed."),
+            name: z.string().describe("The triggered workflow's name."),
+            confirm: z.string().describe("The same name again, to confirm."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: DESTRUCTIVE,
+    }, ({ starter, name, confirm, detail, graph }) => run(client, "lbb_workflows_delete", detail, () => {
+        if (confirm !== name) {
+            throw new Error("confirm must repeat the workflow name");
+        }
+        return scoped(client, graph).workflows.triggered.delete({
+            starter,
+            name,
+        });
+    }));
     const modelUse = z
         .enum(["ask", "route", "rerank", "fit", "label"])
         .describe("A use of a model: ask = question answers, route = query routing, rerank = search rerank, fit = ontology fit, label = eval labels.");
@@ -735,7 +921,7 @@ export function registerLbbTools(server, client, options = {}) {
         }
     }));
     server.registerTool("lbb_evals", {
-        description: "Managed evals: ground truth for the questions an app asks and the searches it runs. A query run with `request` (lbb_query, also mode=question) records a trace: the question, the query that answered it, the type of that query (`query_type`: sparql, hybrid = search by meaning with conditions, search = search by meaning alone) and one item per result (hit or row); trace reads it back with the item ids. label has two forms. On a question's trace, valid alone judges the whole answer: valid=true makes the trace's query the golden query of the question; valid=false with sparql gives the right query, which becomes the golden query; valid=false alone marks the answer wrong. item + valid (or items) judges one result, a citation of the answer: the ground truth of the hits of a search by meaning, and a result marked wrong must not come back for any type. golden freezes a stored query or a search (every result it returns now is relevant). run checks every golden at the current commit: a question is asked again through the query rewriter, then the type of the query it wrote is compared with the expected type, its rows with the rows of the golden query at the same commit (`query_check`), and its results with the judged results; a search is done again; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, ask = the answer of a question, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed.",
+        description: "Managed evals: ground truth for the questions an app asks and the searches it runs. A query run with `request` (lbb_query, also mode=question) records a trace: the question, the query that answered it, the type of that query (`query_type`: sparql, hybrid = search by meaning with conditions, search = search by meaning alone) and one item per result (hit or row); trace reads it back with the item ids. label has two forms. On a question's trace, valid alone judges the whole answer: valid=true makes the trace's query the golden query of the question; valid=false with sparql gives the right query, which becomes the golden query; valid=false alone marks the answer wrong; route with valid=true (or valid=false with sparql) names the route the question expects, and valid=true alone takes the trace's route. item + valid (or items) judges one result, a citation of the answer: the ground truth of the hits of a search by meaning, and a result marked wrong must not come back for any type. golden freezes a stored query or a search (every result it returns now is relevant). run checks every golden at the current commit: a question is asked again through the query rewriter, then the type of the query it wrote is compared with the expected type, its rows with the rows of the golden query at the same commit (`query_check`), and its results with the judged results, and the router's pick with the golden's route (route_check, which does not change the verdict); a search is done again; new results open a review trace. run_answers checks your own app's answers instead: ask each question golden's request with your own loop, then send answers=[{golden, sparql, route}] (route = the route of lbb_query mode=question with route mode, sparql absent for an unanswerable question, error for a failure); the server runs each query and checks it the same way, and the runs form the app's own series (runner; results with runner reads them). judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, ask = the answer of a question, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed.",
         inputSchema: {
             action: z.enum([
                 "summary",
@@ -748,6 +934,7 @@ export function registerLbbTools(server, client, options = {}) {
                 "accept",
                 "delete",
                 "run",
+                "run_answers",
                 "results",
                 "settings",
                 "checks_summary",
@@ -788,6 +975,58 @@ export function registerLbbTools(server, client, options = {}) {
                 .string()
                 .optional()
                 .describe("golden: the query to freeze (the search text for surface=search). label: with valid=false and no item, the right query for the question; the server checks and runs it once."),
+            route: z
+                .enum([
+                "lookup",
+                "aggregate",
+                "search",
+                "history",
+                "schema",
+                "unanswerable",
+            ])
+                .optional()
+                .describe("label: with valid=true, or valid=false with sparql, the route the question expects."),
+            answers: z
+                .array(z
+                .object({
+                golden: z.string().min(1),
+                sparql: z.string().optional(),
+                entailment: z
+                    .enum(["none", "subclass", "rdfs", "owl"])
+                    .optional(),
+                as_of_commit_seq: z.number().int().nonnegative().optional(),
+                route: z
+                    .object({
+                    kind: z.enum([
+                        "lookup",
+                        "aggregate",
+                        "search",
+                        "history",
+                        "schema",
+                        "unanswerable",
+                    ]),
+                    confidence: z.number(),
+                    by: z.enum(["caller", "router", "rewriter"]),
+                    probabilities: z.record(z.string(), z.number()).optional(),
+                })
+                    .strict()
+                    .optional(),
+                reply: z
+                    .object({
+                    text: z.string(),
+                    citations: z.array(z.string()).optional(),
+                })
+                    .optional(),
+                error: z.string().optional(),
+                cost_micro_usd: z.number().int().nonnegative().optional(),
+            })
+                .strict())
+                .optional()
+                .describe("run_answers: one answer per question golden your app asked: golden (its id), sparql (the query whose rows hold the answer; leave it out when the question is unanswerable), entailment, as_of_commit_seq, route (as the router returned it), reply, error (your app failed), cost_micro_usd."),
+            runner: z
+                .string()
+                .optional()
+                .describe("run_answers / results: your app's name, lower-case letters, digits and -, at most 40 characters (default app). results without runner reads the server's runs."),
             surface: z
                 .enum(["sparql", "search"])
                 .optional()
@@ -819,7 +1058,7 @@ export function registerLbbTools(server, client, options = {}) {
             consistency: z
                 .enum(["strong", "eventual"])
                 .optional()
-                .describe("run / accept: strong reads the head, eventual the last published commit."),
+                .describe("run / run_answers / accept: strong reads the head, eventual the last published commit."),
             month: yearMonthSchema
                 .optional()
                 .describe("checks_summary / checks: the month, yyyy-mm (UTC). Defaults to the current month."),
@@ -868,7 +1107,7 @@ export function registerLbbTools(server, client, options = {}) {
             ...graphScope,
         },
         annotations: MUTATING,
-    }, ({ action, trace_id, item, valid, items, by, note, sparql, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, month, job, verdict, reviewed, after, call_id, agree, score, reference, detail, graph, }) => run(client, `lbb_evals.${action}`, detail, () => {
+    }, ({ action, trace_id, item, valid, items, by, note, sparql, route, answers, runner, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, month, job, verdict, reviewed, after, call_id, agree, score, reference, detail, graph, }) => run(client, `lbb_evals.${action}`, detail, () => {
         const target = scoped(client, graph);
         switch (action) {
             case "summary":
@@ -889,12 +1128,18 @@ export function registerLbbTools(server, client, options = {}) {
                 if (sparql !== undefined &&
                     (item || items?.length || valid !== false))
                     throw new Error("label takes sparql (the right query) only with valid=false and no item");
+                if (route !== undefined &&
+                    (item ||
+                        items?.length ||
+                        (valid !== true && sparql === undefined)))
+                    throw new Error("label takes route only with valid=true, or valid=false with sparql, and no item");
                 return target.evals.label(trace_id, {
                     ...(item ? { item, valid } : {}),
                     ...(items?.length ? { items } : {}),
                     // The answer of a question as a whole.
                     ...(!item && !items?.length ? { valid } : {}),
                     ...(sparql !== undefined ? { sparql } : {}),
+                    ...(route !== undefined ? { route } : {}),
                     by,
                     note,
                 });
@@ -924,8 +1169,12 @@ export function registerLbbTools(server, client, options = {}) {
                 return target.evals.deleteGolden(golden_id);
             case "run":
                 return target.evals.run({ consistency });
+            case "run_answers":
+                if (!answers?.length)
+                    throw new Error("run_answers requires answers");
+                return target.evals.runAnswers({ answers, ...(runner ? { runner } : {}) }, { consistency });
             case "results":
-                return target.evals.results({ limit });
+                return target.evals.results({ limit, runner });
             case "settings":
                 return target.evals.settings();
             case "checks_summary":
@@ -1077,7 +1326,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), 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.",
+        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; facts files graph facts for review, which accepting commits after the change, and change may be empty when facts is set), 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) => {
@@ -1098,10 +1347,14 @@ export function registerLbbTools(server, client, options = {}) {
             }
             if (args.action === "suggest_ontology_change") {
                 const agent = args.agent ?? "mcp agent";
+                const change = args.change ?? [];
+                if (!change.length && !args.facts)
+                    throw new Error("suggest_ontology_change needs change, facts, or both");
                 return scoped(client, args.graph).ontology.suggestions.create({
                     title: args.title,
                     rationale: args.rationale ?? "",
-                    change: args.change,
+                    change,
+                    ...(args.facts ? { facts: args.facts } : {}),
                     origin: { kind: "agent", id: agent, label: agent },
                     ...(args.anchor ? { anchor: args.anchor } : {}),
                     ...(args.key ? { key: args.key } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.11.0",
+  "version": "0.13.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.22.0",
+    "@littlebigbrain/client": "^0.25.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },