@littlebigbrain/mcp 0.2.5 → 0.2.7

package/README.md

@@ -1,6 +1,6 @@
 # @littlebigbrain/mcp
 
-Eleven task-shaped [MCP](https://modelcontextprotocol.io) tools that let Claude, Cursor, Codex, or any MCP client search, query, and write a [Little Big Brain](https://littlebigbrain.com) graph. Ships two ways: a hosted endpoint with OAuth sign-in, and a local stdio server.
+Ten task-shaped [MCP](https://modelcontextprotocol.io) tools that let Claude, Cursor, Codex, or any MCP client search, query, and write a [Little Big Brain](https://littlebigbrain.com) graph. Ships two ways: a hosted endpoint with OAuth sign-in, and a local stdio server.
 
 ## Hosted (OAuth) — recommended
 
@@ -59,16 +59,15 @@ missing.
 | Tool | Use it for |
 | --- | --- |
 | `lbb_search` | hybrid retrieval, multi-query fusion, optional path following |
-| `lbb_ask` | grounded answers with citations |
 | `lbb_decode` | constrained relation decoding |
 | `lbb_ground` | vocabulary completion and resolution |
-| `lbb_inspect` | ontology, entity, state, history, provenance, traversal |
-| `lbb_query` | SPARQL, structured analytics, SHACL, inference |
+| `lbb_inspect` | ontology, schema, entity, state, history, provenance, traversal |
+| `lbb_query` | SPARQL and structured analytics |
 | `lbb_commit` | facts, properties, and embeddings |
 | `lbb_observe` | conversation episodes plus reviewed extraction |
 | `lbb_branch` | isolation branches and validated merge |
-| `lbb_configure` | ontology, schema, and inference rules |
-| `lbb_index` | BM25, vector, and adjacency refresh |
+| `lbb_models` | shadow evaluation and training datasets |
+| `lbb_configure` | ontology definition and atomic schema publication |
 
 Read tools return compact structured envelopes by default — use `detail`, `row_limit`, and returned cursors to page without silently truncating. Write tools derive an idempotency key unless you provide one.
 

package/dist/tool-contracts.js

@@ -42,11 +42,6 @@ export const graphScope = {
 export const jsonObjectSchema = z.record(z.string(), z.unknown());
 export const jsonObjectArraySchema = z.array(jsonObjectSchema);
 export const readScope = { detail: detailSchema, ...graphScope };
-// Typed shape for inference rules (define_rules / infer / shacl include_derived).
-// Advertising the structure is what makes a rule's full power discoverable: a
-// term can be a fixed entity (not just a variable), so a rule can match or derive
-// a constant value (e.g. a status); and `not_exists` adds stratified negation, so
-// a rule can express a universal condition like "all children complete".
 export const entitySelectorSchema = z
     .object({
     entity_type: z
@@ -112,54 +107,6 @@ export const searchFeedbackSchema = z
         .min(1),
 })
     .passthrough();
-export const ruleTermSchema = z
-    .union([
-    z
-        .object({
-        var: z.string().describe("A variable, joined across patterns by name"),
-    })
-        .passthrough(),
-    z.object({ entity: entitySelectorSchema }).passthrough(),
-])
-    .describe('A rule term: { "var": "x" } (a variable) or { "entity": { "entity_type": "DeliveryStatus", "name": "Complete" } } (a fixed entity used as a constant in the body or head)');
-export const ruleTriplePatternSchema = z
-    .object({
-    subject: ruleTermSchema.optional(),
-    predicate: z
-        .string()
-        .optional()
-        .describe('Relation name. In a rule body, the reserved "rdf:type" makes a type-membership constraint: the object names a class ({ entity: { entity_type: "Contact" } }, no name) and matches every entity of that class and its subtypes (rdfs:subClassOf closure), so one rule keyed on a supertype fires for all subtypes. Not allowed in a head or an exists/not_exists filter.'),
-    object: ruleTermSchema.optional(),
-})
-    .passthrough();
-export const ruleCombinatorSchema = z
-    .union([
-    z.object({ exists: z.array(ruleTriplePatternSchema) }).passthrough(),
-    z.object({ not_exists: z.array(ruleTriplePatternSchema) }).passthrough(),
-])
-    .describe("An existence filter over the body solutions: { exists: [...] } (semijoin — keep rows with a compatible match) or { not_exists: [...] } (negation/antijoin — keep rows with none)");
-export const inferenceRuleSchema = z
-    .object({
-    name: z.string(),
-    order: z
-        .number()
-        .int()
-        .optional()
-        .describe("Run order, low to high (a determinism hint)"),
-    body: z
-        .array(ruleTriplePatternSchema)
-        .optional()
-        .describe("The condition: a basic graph pattern over current edges (asserted + already-derived), joined on shared variables. Terms may be variables or fixed entities."),
-    combinators: z
-        .array(ruleCombinatorSchema)
-        .optional()
-        .describe('exists/not_exists filters folded over the body. not_exists is stratified negation — it lets a rule express a universal condition, e.g. derive "phase complete" only when not_exists an incomplete deliverable. A negation cycle is rejected.'),
-    head: ruleTriplePatternSchema
-        .optional()
-        .describe("The triple derived once per body solution. Every head variable must be bound by the body; a fixed-entity object derives a constant (e.g. set the rolled-up status to the Complete entity)."),
-})
-    .passthrough();
-export const inferenceRuleArraySchema = z.array(inferenceRuleSchema);
 export const ontologyFormatSchema = z.enum([
     "auto",
     "turtle",
@@ -189,7 +136,7 @@ export const shapeSourceSchema = z
     format: shapeFormatSchema.optional(),
 })
     .strict();
-export const schemaModeSchema = z.enum(["warn", "reject"]);
+export const schemaModeSchema = z.enum(["off", "warn", "reject"]);
 export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
     z
         .object({
@@ -342,19 +289,6 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
         .object({ action: z.literal("ontology_conformance"), ...readScope })
         .strict(),
     z.object({ action: z.literal("schema"), ...readScope }).strict(),
-    z.object({ action: z.literal("schema_audit"), ...readScope }).strict(),
-    z.object({ action: z.literal("rules"), ...readScope }).strict(),
-    z
-        .object({
-        action: z.literal("schema_preview"),
-        ontology: ontologySourceSchema.optional(),
-        shapes: shapeSourceSchema.optional(),
-        base_ontology_version: z.number().int().nonnegative().optional(),
-        base_shapes_version: z.number().int().nonnegative().optional(),
-        desired_mode: schemaModeSchema.optional(),
-        ...readScope,
-    })
-        .strict(),
     z
         .object({
         action: z.literal("ontology_search"),
@@ -388,52 +322,6 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
         ...readScope,
     })
         .strict(),
-    z
-        .object({
-        action: z.literal("edges"),
-        entity_id: z
-            .string()
-            .optional()
-            .describe("Entity id (hex); alternative to entity_type+name"),
-        entity_type: z.string().optional(),
-        name: z.string().optional(),
-        direction: z
-            .enum(["out", "in", "both"])
-            .optional()
-            .describe("Edges out of / into / touching the entity (default both)."),
-        relation: z
-            .string()
-            .optional()
-            .describe("Filter to a single relation name."),
-        row_limit: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe("Max edges returned this page (server caps at 1000; default 150)."),
-        cursor: z
-            .string()
-            .optional()
-            .describe("Opaque cursor from the previous page's `next_cursor`. The response is the unified list envelope { object:'list', data, has_more, next_cursor, total_count }; page a high-degree node (entity detail hard-caps its edge sample) by feeding next_cursor back here until has_more is false. Each row carries valid_time for a per-edge timeline."),
-        offset: z
-            .number()
-            .int()
-            .nonnegative()
-            .optional()
-            .describe("Legacy alias for `cursor` (still accepted); prefer paging with `cursor`."),
-        as_of: z
-            .string()
-            .optional()
-            .describe("Valid-time snapshot pin (RFC3339)."),
-        as_of_commit_seq: z
-            .number()
-            .int()
-            .nonnegative()
-            .optional()
-            .describe("Snapshot pin: list edges as of this commit_seq."),
-        ...readScope,
-    })
-        .strict(),
     z
         .object({
         action: z.literal("state"),
@@ -549,52 +437,6 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         ...readScope,
     })
         .strict(),
-    z
-        .object({
-        mode: z.literal("shacl"),
-        shacl_mode: z
-            .enum(["select", "validate"])
-            .optional()
-            .describe("select returns focus nodes; validate returns a report"),
-        shapes: jsonObjectArraySchema.optional(),
-        rules: inferenceRuleArraySchema.optional(),
-        include_derived: z.boolean().optional(),
-        as_of: z.string().optional(),
-        explain: z.boolean().optional(),
-        top_k: z.number().int().positive().optional(),
-        ...readScope,
-    })
-        .strict(),
-    z
-        .object({
-        mode: z.literal("infer"),
-        rules: inferenceRuleArraySchema.optional(),
-        as_of: z.string().optional(),
-        as_of_commit_seq: z
-            .number()
-            .int()
-            .nonnegative()
-            .optional()
-            .describe("Snapshot pin: run inference as of this commit_seq. Errors if past head."),
-        max_rounds: z.number().int().positive().optional(),
-        max_derived: z.number().int().positive().optional(),
-        max_solutions: z.number().int().positive().optional(),
-        ...readScope,
-    })
-        .strict(),
-    z
-        .object({
-        mode: z.literal("retrieval_premises"),
-        anchor_type: z.string(),
-        anchor_name: z.string(),
-        relation: z.string(),
-        query: z.string(),
-        threshold: z.number().min(0).max(1).optional(),
-        max_premises: z.number().int().positive().optional(),
-        query_top_k: z.number().int().positive().optional(),
-        ...readScope,
-    })
-        .strict(),
     z
         .object({
         mode: z.literal("analyze"),
@@ -623,21 +465,12 @@ export const configureInputSchema = z.discriminatedUnion("action", [
         merge_default: z.boolean().optional(),
     })
         .strict(),
-    z
-        .object({
-        action: z.literal("define_rules"),
-        rules: inferenceRuleArraySchema,
-        confirm_empty: z.boolean().optional(),
-        ...graphScope,
-    })
-        .strict(),
     z
         .object({
         action: z.literal("publish_schema"),
-        preview_digest: z.string(),
-        shapes: shapeSourceSchema,
         ontology: ontologySourceSchema.optional(),
-        desired_mode: schemaModeSchema,
+        shapes: shapeSourceSchema.optional(),
+        desired_mode: schemaModeSchema.optional(),
         confirm_restrictive: z.boolean().optional(),
         ...graphScope,
     })
@@ -662,8 +495,8 @@ export const configureInputSchema = z.discriminatedUnion("action", [
  * schema is a ZodObject (the SDK reads `.shape` via `normalizeObjectSchema`). A
  * `z.discriminatedUnion` has `.options`, not `.shape`, so the SDK silently falls
  * back to an empty `{ type: "object", properties: {} }` advertisement — and
- * clients then stringify every object-valued argument (the `schema_preview`
- * `ontology`/`shapes` sources, the structured-query `body`, …), which the server
+ * clients then stringify every object-valued argument (for example, the
+ * structured-query `body`), which the server
  * rejects as `Expected object, received string`.
  *
  * Flatten the union into a single ZodObject purely for advertisement and

package/dist/tool-runtime.js

@@ -417,55 +417,6 @@ export function toolResult(value) {
         structuredContent: value,
     };
 }
-// `lbb_inspect action=entity` returns the full incoming/outgoing/history arrays,
-// but the display truncates them to the detail cap (compact shows 5) while
-// `counts` still reports the true totals — so a high-degree node reads as "5
-// edges" unless the caller already knows to switch to the paged `edges`/`history`
-// reads. Make that self-documenting: when a sample is capped, attach the true
-// counts plus ready-to-run paged reads so the workaround is discoverable in the
-// response instead of tribal knowledge.
-export function entityEdgeCapHint(data, detail, identity) {
-    if (!data || typeof data !== "object")
-        return {};
-    const record = data;
-    const cap = compactLimits(normalizeDetail(detail)).maxItems;
-    const lengthOf = (field) => {
-        const value = record[field];
-        return Array.isArray(value) ? value.length : 0;
-    };
-    const capped = {};
-    const fullReads = [];
-    const edgeReads = [
-        { field: "incoming", direction: "in" },
-        { field: "outgoing", direction: "out" },
-    ];
-    for (const { field, direction } of edgeReads) {
-        const total = lengthOf(field);
-        if (total > cap) {
-            capped[field] = total;
-            fullReads.push({
-                tool: "lbb_inspect",
-                arguments: { action: "edges", direction, ...identity },
-            });
-        }
-    }
-    if (lengthOf("history") > cap) {
-        capped.history = lengthOf("history");
-        fullReads.push({
-            tool: "lbb_inspect",
-            arguments: { action: "history", ...identity },
-        });
-    }
-    if (Object.keys(capped).length === 0)
-        return {};
-    return {
-        edge_sample: {
-            note: `This node's edge/history arrays are a display sample capped at ${cap} per field; counts holds the true totals. Read the full set with these paged reads (cursor through them until has_more=false).`,
-            capped_totals: capped,
-            full_reads: fullReads,
-        },
-    };
-}
 export function errorResult(error) {
     const payload = error instanceof LbbError
         ? {
@@ -635,8 +586,6 @@ export function searchBody(p) {
             lexical: mode === "hybrid" || mode === "lexical",
             bm25: mode === "hybrid" || mode === "bm25",
             vector: mode === "hybrid" || mode === "vector",
-            bm25_source: "persisted",
-            vector_source: "persisted",
             consistency: "strong",
             profile: resolveProfile(p.profile),
         },
@@ -706,7 +655,7 @@ export function sparqlKeyLabel(value) {
     }
     return String(value);
 }
-export function buildPossibilities(relations, entityTypes = []) {
+export function buildPossibilities(relations) {
     const possibilities = [
         {
             name: "Entity composition",
@@ -789,26 +738,6 @@ export function buildPossibilities(relations, entityTypes = []) {
             },
         });
     }
-    const topType = entityTypes[0]?.name;
-    if (top && topType) {
-        possibilities.push({
-            name: `${topType} nodes that participate in ${top}`,
-            description: `Select every ${topType} that is the source of at least one ${top} edge.`,
-            chart: "bar",
-            run: {
-                tool: "lbb_query",
-                args: {
-                    mode: "shacl",
-                    shapes: [
-                        {
-                            targetClass: topType,
-                            property: [{ path: top, min_count: 1, bind: "targets" }],
-                        },
-                    ],
-                },
-            },
-        });
-    }
     return possibilities;
 }
 export async function guide(scopedClient) {
@@ -827,15 +756,14 @@ export async function guide(scopedClient) {
         capability: {
             search: "Use lbb_search for natural-language retrieval, optional multi-query fusion, and optional path following.",
             search_feedback: "After a lbb_search result set is useful or clearly wrong, write relevance labels with lbb_commit mode=search_feedback. Use grade 3 for ideal/good results, grade 1 for partially relevant results, and grade 0 for bad results. Include the original query, search_id when present, target identity, rank, score, and an optional split train/eval/unspecified. These labels are stored in __lbb_feedback/main and later exported as qrels-style training/eval data; they are not customer facts.",
-            inspect: "Use lbb_inspect for ontology, RDF/SHACL schema, stored rules, metadata, state/history/why, exact traversals, and this guide.",
+            inspect: "Use lbb_inspect for ontology, schema metadata, the published conformance report, metadata, state/history/why, exact traversals, and this guide.",
             ontology_decorations: "lbb_inspect action=ontology returns a decoration_status catalog: each ontology decoration is enforced (the engine acts on it — state_reducer, value_type, super_types, properties, supernode_policy; cardinality, which GET /v1/ontology/conformance audits as sh:maxCount; and inverse_name/symmetric, which SPARQL resolves as relation aliases — an inverse name is queryable directly (lowered to ^forward, no stored inverse triple) and a symmetric relation matches both directions), advisory (transitive, temporal_semantics, required), or reserved (stored but unwired — default_weight, resolvable, alias/embedding_fields). You can also always reverse any relation in SPARQL by flipping the triple pattern or using ^forward. Each relation_def also carries edge_count — the number of current edges of that relation in this branch's snapshot — so you can tell at a glance which declared relations are actually populated (edge_count 0 = declared but unused) without a separate summary call.",
-            query: 'Use lbb_query for structured SPARQL-subset bodies, SPARQL text, SHACL shapes, inference previews, retrieval premises, and canned analysis. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property ({ property: { var, field, as } }) or a calendar bucket of a datetime property ({ date_bucket: { var, field, granularity: month|day|…, as } }), with scalar keys returned per group under value_keys[as] — so per-category breakdowns (e.g. by area) and time series (e.g. commits per month) are single server-side queries over typed attributes, not 700 entity fetches bucketed by hand. These typed scalar attributes are set via entity_properties and read back flat under attributes on entity/list reads (there is no nested metadata.attributes blob); discover the queryable field names via lbb_inspect action=ontology (property_defs) or action=schema, and see the lbb_query body field for a copy-paste commits-per-area-per-month example. A FILTER entry has the exact shape { compare: { op: eq|ne|lt|le|gt|ge, left: <term>, right: <term> } } (also and/or/not), where a <term> is { var }, { property: { var, field } }, or { value: { str|i64|f64|bool|date_time|entity } } — e.g. filters: [{ compare: { op: "ge", left: { property: { var: "d", field: "amount" } }, right: { value: { f64: 1000000 } } } }]. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> (NAME lowercased; reverse with ^) and types <https://littlebigbrain.com/class/NAME> used as `?x a <…/class/NAME>` — the local name is always lowercase, and the tool auto-lowercases /r/, /class/, /p/ IRI local names (noting each rewrite) so a stray uppercase does not silently match nothing; entities are content-addressed, so match a named entity by `?e <http://www.w3.org/2000/01/rdf-schema#label> "Name"` rather than constructing its IRI. Off-graph, a stack also serves the native SPARQL 1.1 Protocol at /sparql for off-the-shelf SPARQL clients.',
+            query: "Use lbb_query for structured SPARQL-subset bodies, SPARQL text, and canned analysis. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
             write: "Use lbb_commit for fact writes and search relevance feedback; omitted idempotency keys are content-derived so retries dedupe. Set typed scalar attributes via entity_properties once the field is registered (add it on a live graph with lbb_configure evolve_ontology add_property). For feedback, use mode=search_feedback rather than fact triplets.",
-            configure: "Use lbb_configure to define a new ontology, evolve an existing one in place (add_entity_type / add_relation / add_property / widen, rename, narrow/remove), publish a previewed RDF/SHACL schema bundle, or replace stored rules after previewing them with lbb_query mode=infer.",
-            inference: "Rule body/head terms are { var } or { entity: { entity_type, name } } — a fixed entity lets a rule match or derive a constant value (e.g. a status). A not_exists combinator adds stratified negation for universal conditions. Roll-up example: rule 1 head { var: phase } HAS_INCOMPLETE_DELIVERABLE { var: d }, body phase HAS_DELIVERABLE d, not_exists [ d HAS_DELIVERY_STATUS { entity: DeliveryStatus/Complete } ]; rule 2 head phase HAS_ROLLUP_STATUS { entity: DeliveryStatus/Complete }, body phase HAS_DELIVERABLE any, not_exists [ phase HAS_INCOMPLETE_DELIVERABLE x ] — derives complete only when every deliverable is complete.",
+            configure: "Use lbb_configure to define a new ontology, evolve an existing one in place, or atomically publish ontology/SHACL bundle metadata. Conformance validation runs durably after publication.",
         },
-        possibilities: buildPossibilities(relations, entityTypes),
-        how_to: "Ground with lbb_inspect action=guide, retrieve with lbb_search, rate useful/partial/bad retrieval results with lbb_commit mode=search_feedback when you have a judgment, inspect exact entities/schema/rules with lbb_inspect, preview analysis or inference with lbb_query, then write graph facts with lbb_commit or configuration with lbb_configure only when intended.",
+        possibilities: buildPossibilities(relations),
+        how_to: "Ground with lbb_inspect action=guide, retrieve with lbb_search, rate useful/partial/bad retrieval results when you have a judgment, inspect exact entities/schema with lbb_inspect, run analysis with lbb_query, then write graph facts with lbb_commit or configuration with lbb_configure only when intended.",
     };
 }
 export async function analyze(scopedClient, p) {
@@ -885,8 +813,6 @@ export async function analyze(scopedClient, p) {
                 lexical: true,
                 bm25: true,
                 vector: true,
-                bm25_source: "persisted",
-                vector_source: "persisted",
                 consistency: "strong",
             },
             facets: [{ field }],
@@ -969,101 +895,6 @@ export function ontologyDefineBody(p) {
         merge_default: p.merge_default ?? false,
     };
 }
-export function schemaSourceBody(source) {
-    if (source === undefined)
-        return undefined;
-    return {
-        source: source.source,
-        format: source.format ?? "auto",
-    };
-}
-export function schemaPreviewBody(p) {
-    const ontology = schemaSourceBody(p.ontology);
-    const shapes = schemaSourceBody(p.shapes);
-    if (ontology === undefined && shapes === undefined) {
-        throw new Error("schema_preview requires an ontology or shapes source");
-    }
-    return {
-        ontology,
-        shapes,
-        base_ontology_version: p.base_ontology_version ?? null,
-        base_shapes_version: p.base_shapes_version ?? null,
-        desired_mode: p.desired_mode ?? "warn",
-    };
-}
-export function schemaPublishBody(p) {
-    return {
-        preview_digest: p.preview_digest,
-        ontology: schemaSourceBody(p.ontology),
-        shapes: schemaSourceBody(p.shapes),
-        desired_mode: p.desired_mode,
-        confirm_restrictive: p.confirm_restrictive ?? false,
-    };
-}
-export function choosePublishMode(response, requested) {
-    const modes = Array.isArray(response.publish_mode_allowed)
-        ? response.publish_mode_allowed
-        : [];
-    if (modes.includes(requested))
-        return requested === "reject" ? "reject" : "warn";
-    if (modes.includes("warn"))
-        return "warn";
-    if (modes.includes("reject"))
-        return "reject";
-    return undefined;
-}
-export function auditSummary(audit) {
-    if (!audit || typeof audit !== "object")
-        return undefined;
-    const a = audit;
-    return {
-        conforms: a.conforms,
-        result_count: a.result_count,
-        messages: a.messages,
-        sample_results: Array.isArray(a.results)
-            ? a.results.slice(0, 5)
-            : undefined,
-    };
-}
-export async function schemaPreview(target, p) {
-    const body = schemaPreviewBody(p);
-    const response = (await target.schema.preview(body));
-    const desiredMode = typeof response.desired_mode === "string"
-        ? response.desired_mode
-        : String(body.desired_mode);
-    const publishMode = choosePublishMode(response, desiredMode);
-    const suggestedPublish = publishMode && body.shapes
-        ? {
-            tool: "lbb_configure",
-            args: {
-                action: "publish_schema",
-                graph: p.graph,
-                branch: p.branch,
-                preview_digest: response.preview_digest,
-                desired_mode: publishMode,
-                confirm_restrictive: response.verdict === "restrictive" && publishMode === "warn"
-                    ? true
-                    : undefined,
-                ontology: body.ontology,
-                shapes: body.shapes,
-            },
-        }
-        : undefined;
-    return {
-        graph: response.graph,
-        verdict: response.verdict,
-        can_publish: response.can_publish,
-        publish_mode_allowed: response.publish_mode_allowed,
-        preview_digest: response.preview_digest,
-        desired_mode: response.desired_mode,
-        proposed_ontology_version: response.proposed_ontology_version,
-        proposed_shapes_version: response.proposed_shapes_version,
-        diff: response.diff,
-        audit: auditSummary(response.audit),
-        messages: response.messages,
-        suggested_publish_schema: suggestedPublish,
-    };
-}
 /**
  * Register the hard-break v2 little big brain tool belt on an MCP server. The surface is
  * task-oriented for agents; each tool dispatches to the existing @littlebigbrain/client

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, } from "./tool-contracts.js";
-import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, entityEdgeCapHint, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, requireString, resolveProfile, rowPageFrom, rowPageNext, run, schemaPreview, schemaPublishBody, scoped, searchBody, searchFeedbackHint, stableJson, toolResult, } from "./tool-runtime.js";
+import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, requireString, resolveProfile, rowPageFrom, rowPageNext, run, scoped, searchBody, searchFeedbackHint, stableJson, toolResult, } from "./tool-runtime.js";
 export function registerLbbTools(server, client) {
     server.registerTool("lbb_search", {
         description: "Natural-language retrieval over Little Big Brain. Use `query` for one phrasing, `queries` for reciprocal-rank fusion across phrasings, and `follow_paths: true` when you want bounded graph paths from text-resolved seed entities. When you can judge returned results, call lbb_commit mode=search_feedback with good=3, partial=1, bad=0 so Little Big Brain can build customer-specific qrels for embedding training.",
@@ -62,8 +62,6 @@ export function registerLbbTools(server, client) {
                     lexical: true,
                     bm25: true,
                     vector: true,
-                    bm25_source: "persisted",
-                    vector_source: "persisted",
                     consistency: "strong",
                     profile: resolveProfile(profile),
                 },
@@ -85,61 +83,14 @@ export function registerLbbTools(server, client) {
     }, (data) => ({
         feedback: searchFeedbackHint(data, { query, queries, graph, branch }),
     })));
-    server.registerTool("lbb_ask", {
-        description: "Ask a natural-language question about the graph and get a grounded answer with citations. The database snaps the question to its real vocabulary (never invented), retrieves against the pinned snapshot, and answers. `mode` is `resident_planner` when a small resident model synthesized the prose, or `grounding_only` when it returns the grounded evidence for your own model to finish. Prefer this over lbb_search when you want a direct, cited answer rather than a ranked list; set `execute: false` to get only the grounding — the real vocabulary the question maps to — without retrieval. The response `explain` block reports how much the database narrowed (vocabulary candidates the question snapped to, plus retrieved entity/assertion counts) and the per-stage latency (ground / retrieve / synth / total ms), so you can see the pipeline that produced the answer.",
-        inputSchema: {
-            question: z
-                .string()
-                .describe("The natural-language question to answer from the graph"),
-            top_k: z
-                .number()
-                .int()
-                .positive()
-                .max(25)
-                .optional()
-                .describe("Max citations to return (default 8)"),
-            execute: z
-                .boolean()
-                .optional()
-                .describe("Run retrieval and answer (default true); false returns only the grounding"),
-            as_of: z
-                .string()
-                .optional()
-                .describe("Valid-time cursor (RFC 3339): retrieval reflects facts true at this instant"),
-            as_of_commit_seq: z
-                .number()
-                .int()
-                .nonnegative()
-                .optional()
-                .describe("Snapshot pin: retrieval and citations reproduce the graph as of this commit sequence"),
-            detail: detailSchema,
-            ...graphScope,
-        },
-        annotations: READ_ONLY,
-    }, ({ question, top_k, execute, as_of, as_of_commit_seq, detail, graph, branch, }) => run(client, "lbb_ask", detail, () => scoped(client, graph, branch).ask({
-        question,
-        top_k,
-        execute,
-        ...(as_of !== undefined ? { as_of_valid_time: as_of } : {}),
-        ...(as_of_commit_seq !== undefined ? { as_of_commit_seq } : {}),
-    })));
     server.registerTool("lbb_decode", {
-        description: "Name the relation between two entities. The database narrows the candidates to the relations its type signatures admit for the (source type, target type) pair; if the pair admits exactly one, the database answers alone (`mode: forced`, no model call). Otherwise a small model fine-tuned on this graph's own edges picks from the narrowed set (`mode: model_narrowed`), constrained to real vocabulary so it can only emit a relation that can exist. You can OMIT the types — pass just the names and the database recovers each type by resolving the name to a real entity (echoed in `resolved_source`/`resolved_target`). Use it to fill a missing edge label, verify a relationship, or assemble structured triples. Returns the `relation`, the admissible `candidates`, and `signature_forced`.",
+        description: "Name the relation between two entities from the admissible published vocabulary. Types may be omitted and resolved from entity names.",
         inputSchema: {
-            source_name: z.string().describe("Source entity display name"),
-            source_type: z
-                .string()
-                .optional()
-                .describe("Source entity type; omit to have the DB recover it from the name"),
-            target_name: z.string().describe("Target entity display name"),
-            target_type: z
-                .string()
-                .optional()
-                .describe("Target entity type; omit to have the DB recover it from the name"),
-            use_model_when_forced: z
-                .boolean()
-                .optional()
-                .describe("Call the model even when the type pair forces one relation (default false — a forced pair is answered by the DB alone)"),
+            source_name: z.string(),
+            source_type: z.string().optional(),
+            target_name: z.string(),
+            target_type: z.string().optional(),
+            use_model_when_forced: z.boolean().optional(),
             detail: detailSchema,
             ...graphScope,
         },
@@ -150,19 +101,14 @@ export function registerLbbTools(server, client) {
         use_model_when_forced,
     })));
     server.registerTool("lbb_ground", {
-        description: "Ground your terms to the graph's real vocabulary before you query or write, so you never guess a type, relation, or property name. Actions: `complete` — narrowed autocomplete: completes a prefix against the real vocabulary, optionally narrowed to the relations a (src_type, dst_type) pair actually admits (so you only propose relations that can exist); `resolve` — snap free text to the single nearest real vocabulary item by embedding/lexical similarity, never fabricating a name; `audit` — groundability report: signature sparsity, name semantics, sampled narrowing recall, and a narrow / narrow+finetune / lexical recommendation for this graph.",
+        description: "Ground terms to the graph's published vocabulary. complete autocompletes a prefix, resolve snaps free text to real vocabulary, and audit reports graph groundability.",
         inputSchema: {
-            action: z
-                .enum(["complete", "resolve", "audit"])
-                .describe("complete = narrowed vocabulary autocomplete; resolve = snap free text to the nearest real vocabulary; audit = groundability report"),
+            action: z.enum(["complete", "resolve", "audit"]),
             prefix: z
                 .string()
                 .optional()
                 .describe("[complete] Text prefix to complete against the real vocabulary"),
-            text: z
-                .string()
-                .optional()
-                .describe("[resolve] Free text to snap to the nearest real vocabulary item"),
+            text: z.string().optional().describe("[resolve] Free text to resolve"),
             src_type: z
                 .string()
                 .optional()
@@ -181,20 +127,20 @@ export function registerLbbTools(server, client) {
                 "property",
             ]))
                 .optional()
-                .describe("[complete/resolve] Restrict to these vocabulary kinds (default: all)"),
+                .describe("Restrict to these vocabulary kinds (default: all)"),
             top_k: z
                 .number()
                 .int()
                 .positive()
                 .max(50)
                 .optional()
-                .describe("[complete/resolve] Max results (default 8)"),
+                .describe("Max results (default 8)"),
             sample: z
                 .number()
                 .int()
                 .positive()
                 .optional()
-                .describe("[audit] Entities to sample for narrowing-recall"),
+                .describe("[audit] Entities sampled for narrowing recall"),
             detail: detailSchema,
             ...graphScope,
         },
@@ -209,7 +155,7 @@ export function registerLbbTools(server, client) {
             });
         }
         if (action === "audit") {
-            return target.groundability(sample != null ? { sample } : {});
+            return target.groundability(sample == null ? {} : { sample });
         }
         const context = src_type !== undefined || dst_type !== undefined
             ? { src_type, dst_type }
@@ -222,7 +168,7 @@ export function registerLbbTools(server, client) {
         });
     }));
     server.registerTool("lbb_inspect", {
-        description: "Read graph context and exact graph facts. Actions: guide, ontology, ontology_conformance, schema, schema_preview, schema_audit, rules, ontology_search, metadata, entity, edges, state, history, transitions, why, traverse. entity returns one node's metadata, scalar attributes, current state, edges, history, and observations — its edge/history arrays are a display sample capped at the detail limit (counts holds the true totals), so on a high-degree node the response carries an `edge_sample` block with the capped totals and ready-to-run paged reads; follow those (or call edges/history directly, paged by row_limit/offset with direction/relation filters and an as_of/as_of_commit_seq pin) to read the full set — total_count tells you when to stop. transitions returns the ordered state-transition log of an entity's relation with dwell time at each value (cycle-time/process analysis). metadata includes temporal_coverage — check it before attempting as-of/daily views: as_of_valid_time_degenerate or single_commit_time means every point-in-time query returns the same snapshot. Use ontology_conformance to check the live data against the ontology's own capped-cardinality rules (derived SHACL sh:maxCount, whole-snapshot, never blocks a write) — distinct from schema_audit, which runs the separately-published SHACL shape bundle.",
+        description: "Read graph context and exact graph facts. Actions: guide, ontology, ontology_conformance, schema, ontology_search, metadata, entity, state, history, transitions, why, traverse. schema reads active ontology/SHACL bundle metadata without running validation. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's metadata, scalar attributes, bounded edge neighborhood, history, and observations. Use traverse for bounded path expansion or lbb_query for precise SPARQL edge selection.",
         inputSchema: inspectWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -243,20 +189,6 @@ export function registerLbbTools(server, client) {
                     return target.ontologyConformance();
                 case "schema":
                     return target.schema.view();
-                case "schema_preview":
-                    return schemaPreview(target, {
-                        graph: args.graph,
-                        branch: args.branch,
-                        ontology: args.ontology,
-                        shapes: args.shapes,
-                        base_ontology_version: args.base_ontology_version,
-                        base_shapes_version: args.base_shapes_version,
-                        desired_mode: args.desired_mode,
-                    });
-                case "schema_audit":
-                    return target.schema.audit();
-                case "rules":
-                    return target.graphRules();
                 case "ontology_search":
                     return target.ontologySearch({
                         query: args.query,
@@ -277,22 +209,6 @@ export function registerLbbTools(server, client) {
                         asOf: args.as_of,
                         asOfCommitSeq: args.as_of_commit_seq,
                     });
-                case "edges":
-                    // Paged edge listing — the way to read every edge of a high-degree
-                    // node, which `entity` hard-caps. Returns the unified list envelope;
-                    // page by feeding next_cursor back as `cursor` until has_more=false.
-                    return target.graphEdges({
-                        id: args.entity_id,
-                        type: args.entity_type,
-                        name: args.name,
-                        direction: args.direction,
-                        relation: args.relation,
-                        limit: args.row_limit,
-                        cursor: args.cursor,
-                        offset: args.offset,
-                        asOf: args.as_of,
-                        asOfCommitSeq: args.as_of_commit_seq,
-                    });
                 case "state":
                     return target.currentState({
                         entity: {
@@ -346,14 +262,10 @@ export function registerLbbTools(server, client) {
                         as_of_commit_seq: args.as_of_commit_seq ?? null,
                     });
             }
-        }, (data) => args.action === "entity"
-            ? entityEdgeCapHint(data, args.detail, args.entity_id
-                ? { entity_id: args.entity_id }
-                : { entity_type: args.entity_type, name: args.name })
-            : {});
+        });
     });
     server.registerTool("lbb_query", {
-        description: "Analytical and expert reads. Modes: structured (SPARQL-subset JSON body), sparql (SPARQL text), shacl, infer, retrieval_premises, analyze. 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 (see the sparql/structured field hints, and lbb_inspect action=ontology for exact names). For structured/sparql row paging, MCP owns limit/offset via row_limit/cursor; a cursor reuses the original query/body and pins continuation pages to the original head commit. When a single page's rows are complete server-side (row_page.has_more false) but too large for one MCP result, the envelope reports `rows_shown` (fewer than row_page.returned), keeps `truncated: true`, and hands back a `next` cursor that pages the same result set at a smaller row_limit — so a large fully-returned result is never silently cut without a way to read the rest.",
+        description: "Analytical and expert reads. Modes: structured (SPARQL-subset JSON body), sparql (SPARQL text), analyze. 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) => {
@@ -505,53 +417,53 @@ export function registerLbbTools(server, client) {
         }
         return run(client, `lbb_query.${args.mode}`, args.detail, async () => {
             const target = scoped(client, args.graph, args.branch);
-            switch (args.mode) {
-                case "shacl":
-                    return target.shacl({
-                        shapes: args.shapes ?? [],
-                        mode: args.shacl_mode ?? "select",
-                        include_derived: args.include_derived ?? false,
-                        rules: args.rules ?? [],
-                        as_of_valid_time: args.as_of ?? null,
-                        top_k: args.top_k ?? 10,
-                        explain: args.explain ?? false,
-                    });
-                case "infer":
-                    return target.infer({
-                        rules: args.rules ?? [],
-                        max_rounds: args.max_rounds ?? null,
-                        max_derived: args.max_derived ?? null,
-                        max_solutions: args.max_solutions ?? null,
-                        as_of_valid_time: args.as_of ?? null,
-                        as_of_commit_seq: args.as_of_commit_seq ?? null,
-                    });
-                case "retrieval_premises":
-                    return target.retrievalPremises({
-                        anchor: {
-                            entity_type: args.anchor_type,
-                            name: args.anchor_name,
-                        },
-                        relation: args.relation,
-                        model_id: "lbb-hash-lexical-v1",
-                        target_kind: "entity",
-                        calibration: { a: -1, b: 0 },
-                        threshold: args.threshold ?? 0.5,
-                        max_premises: args.max_premises ?? 50,
-                        query: args.query,
-                        query_top_k: args.query_top_k ?? 50,
-                    });
-                case "analyze":
-                    return analyze(target, {
-                        metric: args.metric,
-                        chart: args.chart,
-                        top_k: args.top_k,
-                        query: args.query,
-                        field: args.field,
-                        sparql: args.sparql,
-                    });
-            }
+            return analyze(target, {
+                metric: args.metric,
+                chart: args.chart,
+                top_k: args.top_k,
+                query: args.query,
+                field: args.field,
+                sparql: args.sparql,
+            });
         });
     });
+    server.registerTool("lbb_models", {
+        description: "Read model-training inputs or compare retrieval configurations over one pinned published snapshot. shadow_eval takes the API ShadowEvalRequest body; dataset actions return bounded training examples at an optional signal split.",
+        inputSchema: {
+            action: z.enum([
+                "shadow_eval",
+                "planner_dataset",
+                "planner_preference_dataset",
+                "suggest_dataset",
+                "extractor_dataset",
+            ]),
+            body: jsonObjectSchema.optional(),
+            limit: z.number().int().positive().optional(),
+            split_seq: z.number().int().nonnegative().optional(),
+            detail: detailSchema,
+            ...graphScope,
+        },
+        annotations: READ_ONLY,
+    }, ({ action, body, limit, split_seq, detail, graph, branch }) => run(client, `lbb_models.${action}`, detail, () => {
+        const target = scoped(client, graph, branch);
+        switch (action) {
+            case "shadow_eval":
+                if (!body)
+                    throw new Error("shadow_eval requires body");
+                return target.shadowEval(body);
+            case "planner_dataset":
+                return target.plannerDataset({ limit, splitSeq: split_seq });
+            case "planner_preference_dataset":
+                return target.plannerPreferenceDataset({
+                    limit,
+                    splitSeq: split_seq,
+                });
+            case "suggest_dataset":
+                return target.suggestDataset({ limit, splitSeq: split_seq });
+            case "extractor_dataset":
+                return target.extractorDataset({ limit, splitSeq: split_seq });
+        }
+    }));
     server.registerTool("lbb_commit", {
         description: "Write graph facts, retract them, or label search results. mode=facts writes triplets/embeddings/properties; mode=retract removes a wrongly-added fact (by edge or by entity) without a full reset; mode=search_feedback labels query/result relevance after lbb_search (Feedback grades: 3=ideal/good, 1=partial, 0=bad; include query, search_id when available, target, rank, score). Explicit idempotency_key wins; when omitted, MCP derives a stable content hash so content-identical retries dedupe. Facts mode defaults edge_idempotency to append; pass skip_unchanged for re-runnable backfills.",
         inputSchema: {
@@ -661,7 +573,7 @@ export function registerLbbTools(server, client) {
         });
     }));
     server.registerTool("lbb_configure", {
-        description: "Mutate stored graph configuration. Actions: define_ontology (create a new graph ontology), evolve_ontology (evolve an existing graph's ontology in place by name — add_entity_type / add_relation / add_property (a typed scalar field so entity_properties can write it) / widen_relation, rename and set-inverse/cardinality, and data-gated narrow/remove; bumps the ontology version, preserves every record, no migration), publish_schema (activate a previewed RDF/SHACL shape bundle), and define_rules (replace the branch's stored inference rules — body/head terms may be variables or fixed entities, and not_exists combinators add stratified negation for universal conditions).",
+        description: "Mutate stored graph configuration. Actions: define_ontology, evolve_ontology, and publish_schema. Schema publication atomically activates metadata and enqueues durable conformance; it never validates the whole graph in the request.",
         inputSchema: configureWireSchema,
         annotations: MUTATING,
     }, (rawArgs) => {
@@ -687,34 +599,17 @@ export function registerLbbTools(server, client) {
                     allow_data_conflicts: args.allow_data_conflicts ?? false,
                 });
             }
-            if (args.action === "publish_schema") {
-                return scoped(client, args.graph, args.branch).schema.publish(schemaPublishBody({
-                    preview_digest: args.preview_digest,
-                    ontology: args.ontology,
-                    shapes: args.shapes,
-                    desired_mode: args.desired_mode,
-                    confirm_restrictive: args.confirm_restrictive,
-                }));
-            }
-            if (args.rules.length === 0 && args.confirm_empty !== true) {
-                throw new Error("define_rules with an empty rules array requires confirm_empty=true");
+            if (args.ontology === undefined && args.shapes === undefined) {
+                throw new Error("publish_schema requires an ontology or shapes source");
             }
-            return scoped(client, args.graph, args.branch).defineRules({
-                rules: args.rules,
+            return scoped(client, args.graph, args.branch).schema.publish({
+                ontology: args.ontology,
+                shapes: args.shapes,
+                desired_mode: args.desired_mode,
+                confirm_restrictive: args.confirm_restrictive,
             });
         });
     });
-    server.registerTool("lbb_index", {
-        description: "Build or refresh persisted BM25, vector, and adjacency indexes so recently committed facts become searchable.",
-        inputSchema: {
-            background: z
-                .boolean()
-                .optional()
-                .describe("Run detached and poll metadata for completion"),
-            ...graphScope,
-        },
-        annotations: MUTATING,
-    }, ({ background, graph, branch }) => run(client, "lbb_index", "standard", () => scoped(client, graph, branch).indexRun({ background })));
     server.registerTool("lbb_branch", {
         description: "Branch lifecycle. Actions: create (fork a new branch off from_branch — the tool's `branch` argument names the NEW branch) and merge (validate-then-merge: replay from_branch's post-fork commits onto the scoped target branch — its fork parent — as ONE commit with event ids preserved; SHACL-validates the would-be merged state first and refuses with the report on violations; a fact superseded on the target after the fork wins over the branch's version, reported as a supersedure_race conflict; delete_source consumes the merged branch).",
         inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "MCP server for little big brain — graph and hybrid search tools for agents",
   "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.6.0",
+    "@littlebigbrain/client": "^0.9.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },