@littlebigbrain/client 0.4.2 → 0.5.0

package/README.md

@@ -1,169 +1,112 @@
 # @littlebigbrain/client
 
-TypeScript client for the [little big brain](https://littlebigbrain.com) graph + hybrid search HTTP
-API. Request and response types are generated from the committed
-[`contracts/openapi.json`](https://github.com/littlebigbrains/lbb-typescript/blob/main/contracts/openapi.json) (the single source of
-truth, derived from the Rust `lbb-api` types); the client itself is a thin,
-dependency-free wrapper over the platform `fetch`.
+Typed TypeScript client for little big brain: ingest, BM25/vector/graph index,
+authorized hybrid search, traversal, ontology, feedback, and training jobs.
+Runs on Node 18+, browsers, and edge workers using the platform `fetch`.
 
 ```sh
 npm install @littlebigbrain/client
 ```
 
-## Usage
+## Five-minute start
 
 ```ts
-import { LbbClient, LbbError } from "@littlebigbrain/client";
+import { LbbClient } from "@littlebigbrain/client";
 
 const lbb = new LbbClient({
   baseUrl: "https://db.eu.littlebigbrain.com",
-  apiKey: process.env.LBB_API_KEY, // lbb_sk_test_… or lbb_sk_live_…
+  apiKey: process.env.LBB_API_KEY,
 });
-
 const graph = lbb.graph("main");
 
 await graph.facts.create({
-  triplets: [
-    {
-      source: { type: "SERVICE", name: "auth-service" },
-      relation: "WRITES_TO",
-      target: { type: "DATABASE", name: "user-db" },
-      confidence: 0.93,
-      evidence: "auth-service writes identity records to user-db",
-    },
-  ],
-}, {
-  idempotencyKey: "import-2026-06-13",
-});
+  triplets: [{
+    source: { type: "CONCEPT", name: "policy-42" },
+    relation: "RELATED_TO",
+    target: { type: "CONCEPT", name: "seven-year retention" },
+    evidence: "Customer records are retained for seven years.",
+  }],
+}, { idempotencyKey: "policy-42-v1" });
 
 await graph.indexes.run({ wait: true });
 
-const results = await graph.search.hybrid("which systems store customer identity data", {
-  topK: 5,
-  source: "persisted",
-  consistency: "strong",
-  targets: ["entities", "assertions"],
-});
-for (const assertion of results.assertions ?? []) {
-  console.log(assertion.relation?.name, assertion.score);
-}
+const results = await graph.search.hybrid(
+  "How long are customer records retained?",
+  { topK: 10, source: "persisted", consistency: "strong" },
+);
 ```
 
-Use `client.graph("name")` to scope graph writes and `client.rawRequest(...)`
-when you need response metadata (`requestId`, `version`, headers). Every method
-returns parsed JSON and throws `LbbError` with `status`, `type`, `code`,
-`message`, `param`, `requestId`, and `docUrl` on a non-2xx response.
-
-Requests have a 120-second per-attempt timeout by default (`timeoutMs: 0`
-disables it). Safe reads and idempotency-keyed writes retry `429`/`5xx` and
-network failures up to twice, honoring `Retry-After` with a one-minute cap.
-Bulk NDJSON and RDF imports receive an idempotency key automatically unless you
-provide one explicitly. The preferred namespaced surface accepts the same final
-request options everywhere: `timeoutMs`, `maxRetries`, `signal`, `headers`, and
-`idempotencyKey` for mutations.
+Methods return parsed JSON and throw `LbbError` on non-2xx responses. Safe
+reads and idempotency-keyed writes retry transient failures and honor
+`Retry-After`. Keep live stack keys on the server, never in browser bundles.
 
-## Preferred surface
+## Enterprise search integrations
 
-Scope once with `client.graph("name", { branch })`; its `facts`, `search`,
-`entities`, `indexes`, `schema`, `ontology`, `query`, and `context` namespaces
-all carry that graph and branch. The original flat methods remain available for
-compatibility.
+Keep the host product's users, connectors, tasks, and cursors in its existing
+database. Put searchable documents, passages, facts, embeddings, indexes,
+feedback, and model runs in little big brain:
 
-```ts
-const graph = lbb.graph("main", { branch: "review" });
-
-const answer = await graph.context.ask({ question: "what stores identity data?" });
-const ontology = await graph.ontology.view({ counts: true });
-const rows = await graph.query.sparql({ query: "SELECT ?s WHERE { ?s ?p ?o }" });
+1. Give every document/chunk/passage a stable external key.
+2. Bulk-import content, provenance, and native ACL/tag/project sets.
+3. Configure managed embeddings; build ANN, BM25, and adjacency once per batch.
+4. Filter by ACL inside the search request before ranking and return projected
+   fields on the ranked hits.
+5. Grade cited results, reconnect to durable trainer jobs, and require a
+   held-out quality plus latency gate before promotion.
 
-for await (const entity of graph.entities.iterate({ fields: ["owner", "status"] })) {
-  console.log(entity.name, entity.attributes);
-}
-```
+`suggestionShown`, `suggestionAdopted`, `externalPlannerTrace`, and
+`askFeedback` use generated versioned payload types and idempotency keys. Their
+acknowledgements expose stable receipt/event identity, replay state, and why an
+event is or is not trainable.
 
-Use `entities.pages(...)` when page metadata matters, or `entities.iterate(...)`
-to yield rows directly. Both follow the server cursor and fail if a cursor
-repeats instead of looping forever.
-
-For instrumentation, `onRequest` fires before each attempt and `onResponse`
-fires once for the final response; neither event contains bodies or
-credentials. `rawRequest(...)` additionally reports `attempts`, `retryCount`,
-and `elapsedMs`.
-
-## Methods
-
-| Area | Methods |
-| --- | --- |
-| Write | `graph("main").facts.create` |
-| Managed embeddings | `graph("main").embeddingConfig`, `graph("main").setEmbeddingConfig`, `graph("main").backfillEmbeddings`, `graph("main").promoteEmbedding` |
-| Search | `search.hybrid`, `search.multi`, `search.fullText`, `search.vector` |
-| Context substrate | `context.ask`, `context.suggest`, `context.resolve`, `context.decode`, `context.groundability` |
-| Search feedback (training data) | `search.feedback`, `search.feedbackExport` |
-| Traversal | `traverse`, `semanticTraverse` |
-| Temporal / lineage / shapes | `currentState`, `history`, `why`, `shacl` |
-| Query | `query.sparql`, `query.structured`, `query.analytics`, `query.shacl`, `query.infer`, `query.premises` |
-| Ontology | `ontology.view`, `ontology.conformance`, `ontology.search`, `ontology.resolve`, `ontology.define`, `ontology.evolve`, `ontology.induce` |
-| Index lifecycle | `indexes.run`, `indexes.build`, `indexes.delta`, `indexes.gc`, `compact` |
-| Inspection | `entities.list`, `entities.filterByAttributes`, `status`, `metadata`, `summary` |
-| Schema activation | `schema.view`, `schema.preview`, `schema.publish`, `schema.audit` |
-
-Common request/response shapes have direct imports such as `SearchRequest`,
-`SearchResponse`, `Entity`, `GraphSummary`, `CommitRequest`, `AskResponse`, and
-`SchemaView`. Every generated shape remains available as `Schemas["TypeName"]`;
-the raw `components`, `paths`, and `operations` are exported too.
+For an LLM query planner, call `lbb.context.suggest(...)` to fill grounded
+schema/value prefixes, then `lbb.context.resolve(...)` to snap free-text guesses
+onto real vocabulary. `resolve` uses managed embeddings when configured. Record
+adopted suggestions and accepted/rejected/corrected plans so a smaller planner
+and suggest ranker can be trained on the product's actual workload.
 
-## SPARQL
+The [enterprise-search integration guide](https://docs.littlebigbrain.com/guides/enterprise-search/)
+contains the graph model, migration sequence, and acceptance tests.
 
-`client.sparqlRows(...)` runs a SPARQL 1.1 text query (SELECT or ASK) and
-returns parsed results, so you never have to `JSON.parse` the results string or
-zip `head.vars` with binding values yourself:
+## Main surface
 
 ```ts
-const { vars, rows } = await client.sparqlRows({
-  query: `SELECT ?service ?db WHERE {
-            ?service <https://littlebigbrain.com/r/writes_to> ?db
-          } LIMIT 10`,
-  reason: true, // optional: fold in rule-derived edges
-});
-for (const row of rows) console.log(row.service, "->", row.db);
-
-const exists = (await client.sparqlRows({ query: "ASK { ?s ?p ?o }" })).boolean;
+graph.facts.create(...)
+graph.facts.import(...)
+graph.search.hybrid(...)
+graph.entities.iterate(...)
+graph.context.ask(...)
+graph.ontology.view(...)
+graph.query.sparql(...)
+graph.schema.audit(...)
 ```
 
-For app code that already has relation patterns but just needs typed attribute
-predicates, `client.entities.filterByAttributes(...)` builds the structured
-SPARQL filter body without exposing RDF property IRIs:
+Other focused methods cover managed embeddings, full-text/vector search,
+multi-query fusion, traversal, temporal state/history, SHACL, ontology
+evolution, feedback, indexing, and graph inspection. Request/response types are
+generated from `contracts/openapi.json`; common aliases and the complete
+`Schemas` map are exported from the package.
+
+Use `rawRequest()` when you need response headers, request ID, retry count, or
+elapsed time. `onRequest` and `onResponse` provide body-free instrumentation.
+
+## SPARQL
 
 ```ts
-await client.entities.filterByAttributes({
-  patterns: [{ subject: { var: "service" }, predicate: "WRITES_TO", object: { var: "db" } }],
-  where: [{ field: "slo", op: "ge", value: 0.99 }, { var: "db", field: "tier", value: "prod" }],
-  select: ["service"],
+const { rows } = await lbb.sparqlRows({
+  query: `SELECT ?doc WHERE { ?doc ?p ?o } LIMIT 10`,
 });
 ```
 
-`sparqlRows` returns `{ vars, boolean, bindings, rows }`: `rows` is the bindings
-flattened to `{ variable: lexicalValue }`, `bindings` keeps the raw typed term
-objects, and `boolean` is the ASK answer (or `null` for a SELECT). `client.sparqlText(...)`
-returns the unparsed envelope, and the standalone `parseSparqlResults(response)`
-helper (also exported) parses it. For the structured BGP form use
-`client.sparql(body)` (`SparqlSelectRequest`).
-
-A standalone stack also serves the **native SPARQL 1.1 Protocol** at `/sparql`
-(`GET ?query=`, `POST` form or `application/sparql-query` body,
-`Accept`-negotiated JSON/XML/CSV/TSV) for off-the-shelf SPARQL clients (YASGUI,
-Protégé); `sparqlRows` returns parsed JSON rows for in-process use.
+`sparqlRows` parses SELECT/ASK results. The native SPARQL 1.1 Protocol is also
+available at `/sparql` for standard RDF clients.
 
 ## Develop
 
 ```sh
 npm install
-npm run generate   # regenerate src/schema.ts from ../../contracts/openapi.json
-npm run build      # tsc -> dist/
-npm test           # build + node:test (mocked fetch)
-npm run test:coverage
-npm run pack:check # exact tarball: publint + ATTW
+npm run generate
+npm run typecheck
+npm test
+npm run pack:check
 ```
-
-`runtime`: any environment with a global `fetch` (Node 18+, browsers, edge
-workers), or pass your own via the `fetch` option.

package/dist/client.d.ts

@@ -7,6 +7,15 @@ export { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
 export { ContextNamespace, EntityNamespace, FactsNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
+export interface IndexLineageObservation {
+    metadata: Schemas["GraphMetadataResponse"];
+    lineage: Schemas["IndexLineage"];
+    buildCommit?: string;
+    replica?: string;
+    requestId?: string;
+    attempts: number;
+    elapsedMs: number;
+}
 /**
  * A typed HTTP client for a little big brain graph server. One instance is scoped to a
  * single graph/branch; construct another for a different scope. All methods
@@ -133,10 +142,21 @@ export declare class LbbClient {
     }): Promise<unknown>;
     embeddingConfig(): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
     setEmbeddingConfig(body: Schemas["ManagedEmbeddingConfigRequest"]): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
+    submitEmbeddingBackfill(opts?: {
+        batchSize?: number;
+        limit?: number;
+        full?: boolean;
+        idempotencyKey?: string;
+    }): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
+    embeddingBackfillJob(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
+    cancelEmbeddingBackfill(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
     backfillEmbeddings(opts?: {
         batchSize?: number;
         limit?: number;
         full?: boolean;
+        idempotencyKey?: string;
+        timeoutMs?: number;
+        pollIntervalMs?: number;
     }): Promise<Schemas["ManagedEmbeddingBackfillResponse"]>;
     promoteEmbedding(opts: {
         runId: string;
@@ -224,7 +244,21 @@ export declare class LbbClient {
      * explicit feedback capture. `accepted: false` in the response means
      * signal capture is off on this deployment (the contract is identical).
      */
-    askFeedback(body: Schemas["AskFeedbackRequest"]): Promise<Schemas["AskFeedbackResponse"]>;
+    askFeedback(body: Schemas["AskFeedbackRequest"], opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schemas["AskFeedbackResponse"]>;
+    ingestSignals(body: Schemas["SignalIngestRequest"], opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schemas["SignalIngestResponse"]>;
+    suggestionShown(payload: Schemas["SuggestionShownV1"], opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schemas["SignalIngestResponse"]>;
+    suggestionAdopted(payload: Schemas["SuggestionAdoptedV1"], opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schemas["SignalIngestResponse"]>;
+    externalPlannerTrace(payload: Schemas["ExternalPlannerTraceV1"], opts?: {
+        idempotencyKey?: string;
+    }): Promise<Schemas["SignalIngestResponse"]>;
     /**
      * The planner fine-tune's training feed: accepted/corrected feedback
      * joined to its traces (signals ≤ the split pin), topped up with
@@ -521,6 +555,10 @@ export declare class LbbClient {
     status(): Promise<unknown>;
     /** Graph footprint, WAL tail, and index coverage. */
     metadata(): Promise<Schemas["GraphMetadataResponse"]>;
+    waitForIndexLineage(targetSeq: number, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<IndexLineageObservation>;
     /** Graph counts and type/relation buckets. */
     summary(): Promise<Schemas["GraphSummaryResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */

package/dist/client.js

@@ -395,11 +395,40 @@ export class LbbClient {
     setEmbeddingConfig(body) {
         return this.request("POST", "/v1/graph/embedding", { body });
     }
-    backfillEmbeddings(opts = {}) {
-        return this.request("POST", "/v1/graph/embedding/backfill", {
-            query: { batch_size: opts.batchSize, limit: opts.limit, full: opts.full },
+    submitEmbeddingBackfill(opts = {}) {
+        return this.request("POST", "/v1/graph/embedding/backfill-jobs", {
+            body: {
+                batch_size: opts.batchSize,
+                limit: opts.limit,
+                full: opts.full ?? false,
+            },
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("embedding-backfill"),
+        });
+    }
+    embeddingBackfillJob(jobId) {
+        return this.request("GET", "/v1/graph/embedding/backfill-jobs", {
+            query: { job_id: jobId },
+        });
+    }
+    cancelEmbeddingBackfill(jobId) {
+        return this.request("DELETE", "/v1/graph/embedding/backfill-jobs", {
+            query: { job_id: jobId },
         });
     }
+    async backfillEmbeddings(opts = {}) {
+        let status = await this.submitEmbeddingBackfill(opts);
+        const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
+        while (status.status === "pending" || status.status === "running") {
+            if (Date.now() >= deadline)
+                throw new Error(`embedding backfill ${status.job_id} did not finish before timeout`);
+            await sleep(opts.pollIntervalMs ?? 2_000);
+            status = await this.embeddingBackfillJob(status.job_id);
+        }
+        if (status.status !== "succeeded" || status.result == null)
+            throw new Error(status.terminal_error ??
+                `embedding backfill ${status.job_id} ended ${status.status}`);
+        return status.result;
+    }
     promoteEmbedding(opts) {
         return this.request("POST", "/v1/graph/embedding/promote", {
             query: { run_id: opts.runId, allow_regression: opts.allowRegression },
@@ -506,8 +535,35 @@ export class LbbClient {
      * explicit feedback capture. `accepted: false` in the response means
      * signal capture is off on this deployment (the contract is identical).
      */
-    askFeedback(body) {
-        return this.request("POST", "/v1/ask/feedback", { body });
+    askFeedback(body, opts = {}) {
+        return this.request("POST", "/v1/ask/feedback", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("ask-feedback"),
+        });
+    }
+    ingestSignals(body, opts = {}) {
+        return this.request("POST", "/v1/signals", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("signals"),
+        });
+    }
+    suggestionShown(payload, opts = {}) {
+        return this.ingestSignals({ signals: [{ kind: "suggestion_shown", payload }] }, opts);
+    }
+    suggestionAdopted(payload, opts = {}) {
+        return this.ingestSignals({ signals: [{ kind: "suggestion_adopted", payload }] }, opts);
+    }
+    externalPlannerTrace(payload, opts = {}) {
+        return this.ingestSignals({
+            signals: [
+                {
+                    kind: "external_planner_trace",
+                    request_id: payload.ask_id,
+                    snapshot_token: payload.snapshot_token,
+                    payload,
+                },
+            ],
+        }, opts);
     }
     /**
      * The planner fine-tune's training feed: accepted/corrected feedback
@@ -923,6 +979,37 @@ export class LbbClient {
     metadata() {
         return this.request("GET", "/v1/graph/metadata");
     }
+    async waitForIndexLineage(targetSeq, opts = {}) {
+        const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
+        let last;
+        while (true) {
+            last = await this.rawRequest("GET", "/v1/graph/metadata");
+            const lineage = last.data.index_lineage;
+            if (lineage != null &&
+                lineage.bm25_indexed_commit_seq != null &&
+                lineage.bm25_indexed_commit_seq >= targetSeq &&
+                lineage.ann_indexed_commit_seq != null &&
+                lineage.ann_indexed_commit_seq >= targetSeq &&
+                lineage.adjacency_indexed_commit_seq != null &&
+                lineage.adjacency_indexed_commit_seq >= targetSeq) {
+                return {
+                    metadata: last.data,
+                    lineage,
+                    buildCommit: last.headers?.get("lbb-build-commit") ?? undefined,
+                    replica: last.headers?.get("lbb-replica") ?? undefined,
+                    requestId: last.requestId,
+                    attempts: last.attempts,
+                    elapsedMs: last.elapsedMs,
+                };
+            }
+            if (Date.now() >= deadline) {
+                const build = last.headers?.get("lbb-build-commit") ?? "unknown";
+                const replica = last.headers?.get("lbb-replica") ?? "unknown";
+                throw new Error(`index lineage did not reach ${targetSeq} before timeout (build=${build}, replica=${replica}, last=${JSON.stringify(last.data.index_lineage)})`);
+            }
+            await sleep(opts.pollIntervalMs ?? 250);
+        }
+    }
     /** Graph counts and type/relation buckets. */
     summary() {
         return this.request("GET", "/v1/graph/summary");

package/dist/namespaces.d.ts

@@ -39,7 +39,15 @@ export declare class GraphNamespace {
         batchSize?: number;
         limit?: number;
         full?: boolean;
+        pollIntervalMs?: number;
     }): Promise<Schemas["ManagedEmbeddingBackfillResponse"]>;
+    submitEmbeddingBackfill(options?: CallOptions & {
+        batchSize?: number;
+        limit?: number;
+        full?: boolean;
+    }): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
+    embeddingBackfillJob(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
+    cancelEmbeddingBackfill(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
     promoteEmbedding(options: CallOptions & {
         runId: string;
         allowRegression?: boolean;
@@ -77,6 +85,7 @@ export declare class SearchNamespace {
     multi(body: Schemas["HybridMultiSearchRequest"], opts?: CallOptions): Promise<Schemas["HybridMultiSearchResponse"]>;
     feedback(body: Schemas["SearchFeedbackRequest"], opts?: CallOptions): Promise<Schemas["SearchFeedbackResponse"]>;
     feedbackExport(opts?: CallOptions): Promise<Schemas["SearchFeedbackExportResponse"]>;
+    feedbackSummary(opts?: CallOptions): Promise<Schemas["SearchFeedbackSummaryResponse"]>;
     fullText(body: Schemas["FullTextSearchRequest"], opts?: CallOptions): Promise<Schemas["FullTextSearchResponse"]>;
     vector(body: Schemas["EmbeddingSearchRequest"], opts?: CallOptions): Promise<Schemas["EmbeddingSearchResponse"]>;
 }

package/dist/namespaces.js

@@ -53,12 +53,29 @@ export class GraphNamespace {
         });
     }
     backfillEmbeddings(options = {}) {
-        const { batchSize, limit, full, ...request } = options;
-        return this.client.request("POST", "/v1/graph/embedding/backfill", {
-            ...request,
-            query: { batch_size: batchSize, limit, full },
+        return this.client.backfillEmbeddings({
+            batchSize: options.batchSize,
+            limit: options.limit,
+            full: options.full,
+            idempotencyKey: options.idempotencyKey,
+            timeoutMs: options.timeoutMs,
+            pollIntervalMs: options.pollIntervalMs,
+        });
+    }
+    submitEmbeddingBackfill(options = {}) {
+        return this.client.submitEmbeddingBackfill({
+            batchSize: options.batchSize,
+            limit: options.limit,
+            full: options.full,
+            idempotencyKey: options.idempotencyKey,
         });
     }
+    embeddingBackfillJob(jobId) {
+        return this.client.embeddingBackfillJob(jobId);
+    }
+    cancelEmbeddingBackfill(jobId) {
+        return this.client.cancelEmbeddingBackfill(jobId);
+    }
     promoteEmbedding(options) {
         const { runId, allowRegression, ...request } = options;
         return this.client.request("POST", "/v1/graph/embedding/promote", {
@@ -184,6 +201,9 @@ export class SearchNamespace {
     feedbackExport(opts = {}) {
         return this.client.request("GET", "/v1/search/feedback/export", opts);
     }
+    feedbackSummary(opts = {}) {
+        return this.client.request("GET", "/v1/search/feedback/summary", opts);
+    }
     fullText(body, opts = {}) {
         return this.client.request("POST", "/v1/search/full-text", {
             ...opts,