@littlebigbrain/mcp 0.10.0 → 0.12.0

package/dist/tools.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 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) => {
@@ -63,7 +66,7 @@ export function registerLbbTools(server, client, options = {}) {
         });
     });
     server.registerTool("lbb_query", {
-        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.",
+        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, and four tools for writing your own queries: names, describe, commit_at, compare. names: before a query that names an entity (a person, a company), find its IRI with text=<the question or the names>; use the first candidate, not a CONTAINS match on the name. describe: before a query on classes or properties you have not seen, read them with question=<the question> (or classes/properties as IRIs): how many sampled instances hold each property (a filter on a rare one returns few rows), the values of small classes such as stages, examples and schema statements. commit_at: for a question about a date, find the commit of date=YYYY-MM-DD (or moment=RFC 3339), then run mode=sparql as_of_commit_seq=<it>. compare: for what changed between two points, run one SELECT at before and after (default the latest) with key=[the entity variable]; added, removed and changed come with totals and pages (next). Use mode=question when you have a question in plain words and no SPARQL query: the server picks the kind of question (route), runs queries in a bounded loop, reads their rows, and answers in plain words (about 8 s). The result holds the answer with citations and a chart hint (kind, x, y: columns of the rows), the steps, the route, and the query and rows the answer stands on. 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, extra) => {
@@ -300,6 +303,29 @@ export function registerLbbTools(server, client, options = {}) {
                 }
             })();
         }
+        if (args.mode === "names" ||
+            args.mode === "describe" ||
+            args.mode === "commit_at" ||
+            args.mode === "compare") {
+            const toolArgs = args;
+            return (async () => {
+                try {
+                    switch (args.mode) {
+                        case "names":
+                            return await findNames(client, toolArgs);
+                        case "describe":
+                            return await describeGraph(client, toolArgs);
+                        case "commit_at":
+                            return await commitAt(client, toolArgs);
+                        default:
+                            return await compareQuery(client, toolArgs);
+                    }
+                }
+                catch (error) {
+                    return errorResult(await enrichError(client, error));
+                }
+            })();
+        }
         if (args.mode === "search") {
             const searchArgs = args;
             // The caller's detail shapes the hits like every other mode: compact
@@ -476,8 +502,426 @@ export function registerLbbTools(server, client, options = {}) {
         }
         return scoped(client, graph).embeddings.delete(name);
     }));
+    // Fit from text: fit sources declared on classes, like embeddings.
+    const fitSetup = {
+        class: z
+            .string()
+            .optional()
+            .describe("preview/declare/dry_run: the class IRI whose instances hold the text."),
+        from: z
+            .array(z.string())
+            .optional()
+            .describe("preview/declare/dry_run: the fields that hold the text, as embedding paths (transcript, label, about/label, <https://…>). Omit for the long text facts of the class."),
+        exclude: z
+            .array(z.string())
+            .optional()
+            .describe("preview/declare/dry_run: fields to drop from the automatic choice."),
+        context: z
+            .string()
+            .optional()
+            .describe('preview/declare/dry_run: one sentence about the text, e.g. "interviews with employees about their work processes" (at most 500 characters).'),
+    };
+    const fitDeclaration = (args) => {
+        if (!args.class)
+            throw new Error("this action requires class");
+        return {
+            class: args.class,
+            ...(args.name ? { name: args.name } : {}),
+            ...(args.from ? { from: args.from } : {}),
+            ...(args.exclude ? { exclude: args.exclude } : {}),
+            ...(args.context ? { context: args.context } : {}),
+        };
+    };
+    server.registerTool("lbb_fit_sources", {
+        description: "Fit from text, read only: fit sources declared on classes. A fit source names the fields of a class that hold text (transcripts, documents); the server reads every instance, proposes ontology changes (classes, properties, relations) with verbatim quotes, checks them, and files them as ontology suggestions with origin id fit:<name>. list shows each source's status (progress, lag, instances read, proposals kept and dropped, suggestions per status, this month's spend, last error) and the stack's monthly budget; get shows one; preview shows the fields, every candidate field of the class and the text of sample instances, calls no model and stores nothing. Declare, refresh or dry-run with lbb_fit_sources_manage; list the suggestions with lbb_inspect action=ontology_suggestions.",
+        inputSchema: {
+            action: z.enum(["list", "get", "preview"]),
+            name: z.string().optional().describe("get: the fit source name."),
+            ...fitSetup,
+            sample: z.number().int().positive().max(20).optional(),
+            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_fit_sources.${args.action}`, args.detail, () => {
+        const fit = scoped(client, args.graph).ontology.fitSources;
+        switch (args.action) {
+            case "list":
+                return fit.list();
+            case "get":
+                if (!args.name)
+                    throw new Error("get requires name");
+                return fit.get(args.name);
+            case "preview":
+                return fit.preview({
+                    ...fitDeclaration(args),
+                    ...(args.sample ? { sample: args.sample } : {}),
+                    ...(args.iris ? { iris: args.iris } : {}),
+                });
+        }
+    }));
+    server.registerTool("lbb_fit_sources_manage", {
+        description: "Declare, dry-run or refresh a fit source (fit from text). Run lbb_fit_sources action=preview first and show the user the text the fit reads. dry_run runs the models on the first part of up to 3 instances (at most 60 s; truncated when one did not finish) and returns every proposal with its quote, its support score and what the checks made of it; it files nothing but spends model budget. declare sets the class, the fields and the context; the job then reads every instance and files suggestions (an existing source changes only what you name). refresh asks the job to run now and returns the status at once; the job also runs by itself after each published commit, so poll lbb_fit_sources action=get for progress. Nothing changes the ontology until a person accepts a suggestion.",
+        inputSchema: {
+            action: z.enum(["declare", "dry_run", "refresh"]),
+            name: z
+                .string()
+                .optional()
+                .describe("The fit source name (refresh: required)."),
+            ...fitSetup,
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_fit_sources_manage.${args.action}`, args.detail, () => {
+        const fit = scoped(client, args.graph).ontology.fitSources;
+        switch (args.action) {
+            case "declare":
+                return fit.declare(fitDeclaration(args));
+            case "dry_run":
+                return fit.preview({ ...fitDeclaration(args), propose: true });
+            case "refresh":
+                if (!args.name)
+                    throw new Error("refresh requires name");
+                return fit.refresh(args.name);
+        }
+    }));
+    server.registerTool("lbb_fit_sources_delete", {
+        description: "Delete a fit source: the fit stops reading its class. The suggestions it filed stay. Ask the user first; confirm must repeat the name.",
+        inputSchema: {
+            name: z.string().describe("The fit source name."),
+            confirm: z.string().describe("The same name again, to confirm."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: DESTRUCTIVE,
+    }, ({ name, confirm, detail, graph }) => run(client, "lbb_fit_sources_delete", detail, () => {
+        if (confirm !== name) {
+            throw new Error("confirm must repeat the fit source name");
+        }
+        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 writes DocEntry and DocMention instances and links each mention to its entry, and infer.llm 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, infer.llm) 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 or infer.llm) 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.");
+    server.registerTool("lbb_model_choice", {
+        description: "Model choice, read only: which model each use of a model on the graph runs, and trials that test other models against the graph's ground truth (the checked calls: a person's review, else the judge's verdict). options shows per use the model it runs now (current), LBB's model (default), a switch (switched), its checked calls, and the models a trial can test with their efforts, prices and whether the server holds their key; available=false with a reason when trials cannot run. trials lists the trials, newest first, each with its report: calls compared, both models' right share, mean score (0 to 1), cost per call and median time, the difference with its 95% interval (delta, ci_low, ci_high), outcome (too_few, better, same, worse) and qualifies (meets the bar: at least 20 calls, at most 5 points worse at the low end, no more failures, cheaper or better). trial reads one trial with its compared calls; trial_call reads one call with both answers and the ground truth. switches lists the switched uses. Start, stop, switch or revert with lbb_model_choice_manage.",
+        inputSchema: {
+            action: z.enum([
+                "options",
+                "trials",
+                "trial",
+                "trial_call",
+                "switches",
+            ]),
+            trial_id: z
+                .string()
+                .optional()
+                .describe("trial / trial_call: the trial id."),
+            call_id: z
+                .string()
+                .optional()
+                .describe("trial_call: a call id from the trial's calls."),
+            job: modelUse
+                .optional()
+                .describe("trials: only the trials of this use."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe("trials: at most this many, newest first (default 20)."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, (args) => run(client, `lbb_model_choice.${args.action}`, args.detail, () => {
+        const models = scoped(client, args.graph).models;
+        switch (args.action) {
+            case "options":
+                return models.trials.options();
+            case "trials":
+                return models.trials.list({ job: args.job, limit: args.limit });
+            case "trial":
+                if (!args.trial_id)
+                    throw new Error("trial requires trial_id");
+                return models.trials.get(args.trial_id);
+            case "trial_call":
+                if (!args.trial_id || !args.call_id) {
+                    throw new Error("trial_call requires trial_id and call_id");
+                }
+                return models.trials.call(args.trial_id, args.call_id);
+            case "switches":
+                return models.switches.list();
+        }
+    }));
+    server.registerTool("lbb_model_choice_manage", {
+        description: "Model choice, writes. start tests a candidate model on the uses in jobs (without jobs, every use it can do that has checked calls): the server answers those checked calls again with the candidate and scores it and the model in use against the same ground truth. It changes no model and spends at most the trial budget ($3.00 by default) of model and judge cost; an open trial of the same use and candidate comes back as it is. Pick candidates from lbb_model_choice action=options (provider anthropic with an effort, or typesafe jev-latest). A trial runs by itself: poll lbb_model_choice action=trial until its status is no longer running. stop ends a trial; it keeps what it compared. switch makes the trial's use run its candidate on this graph from the next call on; only a trial that qualifies and compared with the model in use switches (ask to a Claude model, route to a Jev model). Show the user the trial's report (score, difference and interval, cost per call, time) and switch only what the user confirmed. revert puts the use back on LBB's model.",
+        inputSchema: {
+            action: z.enum(["start", "stop", "switch", "revert"]),
+            provider: z
+                .enum(["anthropic", "typesafe"])
+                .optional()
+                .describe("start: the candidate's provider."),
+            model: z
+                .string()
+                .optional()
+                .describe("start: the candidate model id, e.g. claude-haiku-5-5 or jev-latest."),
+            effort: z
+                .enum(["low", "medium", "high", "xhigh", "max"])
+                .optional()
+                .describe("start: the effort of a Claude candidate."),
+            jobs: z
+                .array(modelUse)
+                .optional()
+                .describe("start: the uses to test it on."),
+            target: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("start: the calls to compare (default 40)."),
+            days: z
+                .number()
+                .int()
+                .positive()
+                .max(30)
+                .optional()
+                .describe("start: the days the trial takes new checks (default 14)."),
+            trial_id: z
+                .string()
+                .optional()
+                .describe("stop / switch: the trial id."),
+            job: modelUse
+                .optional()
+                .describe("revert: the use to put back on LBB's model."),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: MUTATING,
+    }, (args) => run(client, `lbb_model_choice_manage.${args.action}`, args.detail, () => {
+        const models = scoped(client, args.graph).models;
+        switch (args.action) {
+            case "start":
+                if (!args.provider || !args.model) {
+                    throw new Error("start requires provider and model");
+                }
+                return models.trials.create({
+                    candidate: {
+                        provider: args.provider,
+                        model: args.model,
+                        ...(args.effort ? { effort: args.effort } : {}),
+                    },
+                    ...(args.jobs ? { jobs: args.jobs } : {}),
+                    ...(args.target ? { target: args.target } : {}),
+                    ...(args.days ? { days: args.days } : {}),
+                });
+            case "stop":
+                if (!args.trial_id)
+                    throw new Error("stop requires trial_id");
+                return models.trials.stop(args.trial_id);
+            case "switch":
+                if (!args.trial_id)
+                    throw new Error("switch requires trial_id");
+                return models.switches.create({ trial: args.trial_id });
+            case "revert":
+                if (!args.job)
+                    throw new Error("revert requires job");
+                return models.switches.revert(args.job);
+        }
+    }));
     server.registerTool("lbb_evals", {
-        description: "Managed evals: the thumbs up / thumbs down of the graph, per result. A query run with `request` (lbb_query) records a trace with one item per result (hit or row); trace reads it back with the item ids. label marks one result (item + valid) or several (items) relevant or not; the labels become the golden's ground truth. golden freezes a query (every result it returns now is relevant). run replays every golden at the current commit: pass when every relevant result is back and no wrong one is; 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, 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. 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.",
         inputSchema: {
             action: z.enum([
                 "summary",
@@ -507,7 +951,7 @@ export function registerLbbTools(server, client, options = {}) {
             valid: z
                 .boolean()
                 .optional()
-                .describe("label: true = the result answers the request (thumbs up), false = it does not."),
+                .describe("label: true = the result answers the request (thumbs up), false = it does not. Without item or items, on a question's trace: the whole answer is right (true) or wrong (false)."),
             items: z
                 .array(z
                 .object({
@@ -529,7 +973,7 @@ export function registerLbbTools(server, client, options = {}) {
             sparql: z
                 .string()
                 .optional()
-                .describe("golden: the query to freeze (the search text for surface=search)."),
+                .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."),
             surface: z
                 .enum(["sparql", "search"])
                 .optional()
@@ -566,7 +1010,15 @@ export function registerLbbTools(server, client, options = {}) {
                 .optional()
                 .describe("checks_summary / checks: the month, yyyy-mm (UTC). Defaults to the current month."),
             job: z
-                .enum(["rerank", "route", "rewrite", "fit", "propose", "label"])
+                .enum([
+                "rerank",
+                "route",
+                "ask",
+                "rewrite",
+                "fit",
+                "propose",
+                "label",
+            ])
                 .optional()
                 .describe("checks: only the checks of one job."),
             verdict: z
@@ -616,13 +1068,19 @@ export function registerLbbTools(server, client, options = {}) {
             case "label":
                 if (!trace_id)
                     throw new Error("label requires trace_id");
-                if (!item && !items?.length)
-                    throw new Error("label requires item (with valid) or items");
                 if (item && valid === undefined)
                     throw new Error("label requires valid with item");
+                if (!item && !items?.length && valid === undefined)
+                    throw new Error("label requires item (with valid), items, or valid alone for the answer of a question");
+                if (sparql !== undefined &&
+                    (item || items?.length || valid !== false))
+                    throw new Error("label takes sparql (the right query) only with valid=false 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 } : {}),
                     by,
                     note,
                 });
@@ -805,7 +1263,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) => {
@@ -826,10 +1284,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.10.0",
+  "version": "0.12.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.20.0",
+    "@littlebigbrain/client": "^0.23.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },