@littlebigbrain/client 0.4.2 → 0.4.3

package/README.md

@@ -1,169 +1,101 @@
 # @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.
+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.
 
-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.
+## Enterprise search integrations
 
-## Preferred surface
+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:
 
-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.
+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.
 
-```ts
-const graph = lbb.graph("main", { branch: "review" });
+The [enterprise-search integration guide](https://docs.littlebigbrain.com/guides/enterprise-search/)
+contains the graph model, migration sequence, and acceptance tests.
 
-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 }" });
+## Main surface
 
-for await (const entity of graph.entities.iterate({ fields: ["owner", "status"] })) {
-  console.log(entity.name, entity.attributes);
-}
+```ts
+graph.facts.create(...)
+graph.facts.import(...)
+graph.search.hybrid(...)
+graph.entities.iterate(...)
+graph.context.ask(...)
+graph.ontology.view(...)
+graph.query.sparql(...)
+graph.schema.audit(...)
 ```
 
-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.
-
-## SPARQL
+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.
 
-`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:
+Use `rawRequest()` when you need response headers, request ID, retry count, or
+elapsed time. `onRequest` and `onResponse` provide body-free instrumentation.
 
-```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;
-```
-
-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:
+## 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/namespaces.d.ts

@@ -77,6 +77,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

@@ -184,6 +184,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,

package/dist/schema.d.ts

@@ -5904,6 +5904,10 @@ export interface components {
              *     idempotent replays do not advance it and retractions do.
              */
             latest_label_sequence: number;
+            /**
+             * @description Label objects fetched for this request. Zero on a materialized-cache hit;
+             *     a rebuild reports the bounded source objects it read.
+             */
             objects_scanned: number;
             promoted_models: components["schemas"]["SearchFeedbackPromotedModel"][];
             raw_events: number;
@@ -6757,7 +6761,28 @@ export interface components {
              */
             hit_rate_at_k: number;
             /** Format: double */
+            latency_p50_ms?: number;
+            /** Format: double */
+            latency_p95_ms?: number;
+            /** Format: double */
+            latency_p99_ms?: number;
+            /** Format: double */
             mean_latency_ms: number;
+            /**
+             * Format: float
+             * @description Mean reciprocal rank of the first expected target in top-k.
+             */
+            mrr_at_k?: number;
+            /**
+             * Format: float
+             * @description Mean binary-relevance nDCG over top-k.
+             */
+            ndcg_at_k?: number;
+            /**
+             * Format: float
+             * @description Mean fraction of each query's expected targets recovered in top-k.
+             */
+            recall_at_k?: number;
         };
         /**
          * @description `POST /v1/models/shadow-eval` — champion vs challenger retrieval over the
@@ -7496,6 +7521,32 @@ export interface components {
             /** @description Human-readable one-liner for the console status surface. */
             reason: string;
         };
+        /** @description Bounded in-flight work counters for a durable trainer job. */
+        TrainModelJobProgress: {
+            completed_candidates: number;
+            /** @description Completed expensive probe replays, not merely distinct input probes. */
+            completed_probes: number;
+            /**
+             * Format: int64
+             * @description Linear estimate from work completed so far. Absent before the first
+             *     measured probe or for trainers without fine-grained progress.
+             */
+            estimated_duration_ms?: number | null;
+            /**
+             * Format: int64
+             * @description Worker heartbeat attached to this progress snapshot.
+             */
+            heartbeat_micros: number;
+            /**
+             * Format: float
+             * @description Monotonic completion percentage in `[0, 100]`.
+             */
+            percentage: number;
+            /** @description `preparing` | `candidate_search` | `held_out_gate` | kind-specific stage. */
+            phase: string;
+            total_candidates: number;
+            total_probes: number;
+        };
         /**
          * @description Durable background trainer status. The terminal `result` carries the full
          *     snapshot lineage, held-out gate evidence, and recorded run number.
@@ -7508,6 +7559,7 @@ export interface components {
             graph: components["schemas"]["GraphKey"];
             job_id: string;
             kind: string;
+            progress?: null | components["schemas"]["TrainModelJobProgress"];
             result?: null | components["schemas"]["TrainModelResponse"];
             stage?: string | null;
             /** @description `pending` | `running` | `succeeded` | `failed`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {