@littlebigbrain/client 0.6.0 → 0.7.0

package/README.md

@@ -1,106 +1,89 @@
 # @littlebigbrain/client
 
-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`.
+The typed TypeScript client for [Little Big Brain](https://littlebigbrain.com) — write graph facts, build indexes, and run hybrid search over one snapshot. Request and response types are generated from the API contract, so every call is fully typed. Runs anywhere there's a global `fetch`: Node 18+, browsers, and edge workers.
 
 ```sh
 npm install @littlebigbrain/client
 ```
 
-## Five-minute start
+## Quickstart
 
 ```ts
 import { LbbClient } from "@littlebigbrain/client";
 
 const lbb = new LbbClient({
-  baseUrl: "https://db.eu.littlebigbrain.com",
-  apiKey: process.env.LBB_API_KEY,
+  baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com",
+  apiKey: process.env.LBB_API_KEY, // lbb_sk_live_… — keep it server-side
 });
 const graph = lbb.graph("main");
 
-await graph.facts.create({
-  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" });
+// 1. Write a fact.
+await graph.facts.create(
+  {
+    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" },
+);
 
+// 2. Build persisted BM25 + vector + adjacency indexes and wait.
 await graph.indexes.run({ wait: true });
 
+// 3. Hybrid search over the snapshot.
 const results = await graph.search.hybrid(
   "How long are customer records retained?",
   { topK: 10, source: "persisted", consistency: "strong" },
 );
 ```
 
-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.
-
-## Enterprise search integrations
-
-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:
-
-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 hosted use, `baseUrl` is required and must be the exact `endpoint_url`
+shown on the stack's Connect page. Graph and branch remain client scope
+parameters; they are not encoded in the hostname.
 
-`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.
+## Examples
 
-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.
+**Search with filters.** Pass the request body to filter before ranking — here, only facts an ACL principal may see:
 
-The [enterprise-search integration guide](https://docs.littlebigbrain.com/guides/enterprise-search/)
-contains the graph model, migration sequence, and acceptance tests.
+```ts
+const results = await graph.search.hybrid({
+  query: "incident response runbook",
+  targets: ["entities"],
+  search: {
+    filters: {
+      op: "overlaps",
+      field: "acl",
+      values: ["user:rino@example.com", "group:engineering"],
+    },
+  },
+  top_k: 20,
+});
+```
 
-## Main surface
+**Bulk import.** Load an array of records (or an NDJSON string) in one call:
 
 ```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(...)
-
-const build = await graph.indexes.submit({}, { idempotencyKey: "index:head:147" })
-await graph.indexes.job(build.job_id)
-await graph.indexes.cancel(build.job_id)
-
-const gc = await graph.indexes.submitGc({ dry_run: false }, { idempotencyKey: "gc:2026-07-15" })
-await graph.indexes.gcJob(gc.job_id)
-
-await graph.branch("review").deleteBranch({ confirm: "review" })
-await graph.delete({ confirm: "main" }) // whole graph, every branch
+await graph.facts.import(
+  [
+    { source: { type: "DOC", name: "handbook", key: "doc:42" }, relation: "HAS_PASSAGE", target: { type: "PASSAGE", name: "leave-policy", key: "p:42:1" } },
+    // …one record per line
+  ],
+  { idempotencyKey: "handbook-batch-1" },
+);
 ```
 
-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.
+**Time-travel read.** Pin any search to a past instant — results reflect the graph as it was then:
 
-Use `rawRequest()` when you need response headers, request ID, retry count, or
-elapsed time. `onRequest` and `onResponse` provide body-free instrumentation.
+```ts
+const asOf = await graph.search.hybrid("retention policy", { asOf: "2026-01-01T00:00:00Z" });
+```
 
-## SPARQL
+**SPARQL.** `sparqlRows` runs a SPARQL 1.1 SELECT/ASK and returns parsed rows:
 
 ```ts
 const { rows } = await lbb.sparqlRows({
@@ -108,15 +91,21 @@ const { rows } = await lbb.sparqlRows({
 });
 ```
 
-`sparqlRows` parses SELECT/ASK results. The native SPARQL 1.1 Protocol is also
-available at `/sparql` for standard RDF clients.
+## Errors & retries
+
+Methods return parsed JSON and throw `LbbError` (with `status`, `code`, `message`, `param`, `requestId`, `docUrl`) on any non-2xx response. Safe reads and idempotency-keyed writes retry `429`/`5xx` and network failures with full-jitter backoff, bounded by a retry budget (`retryBudgetMs`, default 60s) rather than a fixed count, and honor `Retry-After` — a terminal error the server marks non-retryable surfaces immediately. Use `rawRequest()` for response headers, request id, and retry/timing metadata.
+
+## More
+
+The `graph(...)` scope exposes `facts`, `search`, `entities`, `indexes`, `ontology`, `query`, `schema`, and `context` namespaces — covering managed embeddings, multi-query fusion, traversal, temporal state and history, SHACL, ontology evolution, and durable index jobs. Every generated shape is available as `Schemas["TypeName"]`.
+
+Full reference and guides: [docs.littlebigbrain.com/sdks/typescript](https://docs.littlebigbrain.com/sdks/typescript/).
 
 ## Develop
 
 ```sh
 npm install
-npm run generate
+npm run generate    # regenerate types from contracts/openapi.json
 npm run typecheck
 npm test
-npm run pack:check
 ```

package/dist/client.d.ts

@@ -1,8 +1,8 @@
-import type { ImportLine, LbbClientOptions, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.js";
-import { type RequestOptions } from "./transport.js";
+import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.js";
+import { type CallOptions, type RequestOptions } from "./transport.js";
 import { ContextNamespace, EntityNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
-export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
+export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
 export { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
@@ -115,6 +115,42 @@ export declare class LbbClient {
     }): Promise<Schemas["GraphRetractResponse"]>;
     /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
     createGraph(): Promise<Schemas["CreateGraphResponse"]>;
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts: {
+        src: string;
+        dst: string;
+    }): Promise<Schemas["GraphForkResponse"]>;
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines: ImportLine[] | string, opts: {
+        confirm: string;
+        dryRun?: boolean;
+        strict?: boolean;
+        observedAt?: string;
+        idempotencyKey?: string;
+    }): Promise<Schemas["GraphReloadResponse"]>;
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body: Schemas["GraphBranchCreateRequest"]): Promise<Schemas["GraphBranchCreateResponse"]>;
     /**
@@ -385,7 +421,14 @@ export declare class LbbClient {
         name?: string;
         relations?: string[];
         asOf?: string;
+        /** Require the bounded ranged-adjacency path; returns `index_busy` while unavailable. */
+        indexed?: boolean;
     }): Promise<Schemas["EntityNeighborhoodResponse"]>;
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    entityTypeSample(opts: {
+        type: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
     /** Stored entity object-ref status and index-coverage metadata (no
      * attributes — read those from `entityDetail`'s top-level `attributes`). */
     entityMetadata(opts: {
@@ -581,8 +624,12 @@ export declare class LbbClient {
     }): Promise<Schemas["WalCompactResponse"]>;
     /** Server, graph, and persisted-index status. */
     status(): Promise<unknown>;
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata(): Promise<Schemas["GraphMetadataResponse"]>;
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts?: {
+        includeObjects?: boolean;
+        includeIndexes?: boolean;
+        includeTemporalCoverage?: boolean;
+    }): Promise<Schemas["GraphMetadataResponse"]>;
     waitForIndexLineage(targetSeq: number, opts?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
@@ -591,6 +638,4 @@ export declare class LbbClient {
     summary(): Promise<Schemas["GraphSummaryResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs(): Promise<Schemas["GraphListResponse"]>;
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window?: LbbStackActivityWindow): Promise<LbbStackActivityResponse>;
 }

package/dist/client.js

@@ -32,7 +32,11 @@ export class LbbClient {
     ontology;
     query;
     constructor(options) {
-        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        const baseUrl = options.baseUrl?.trim();
+        if (!baseUrl) {
+            throw new Error("baseUrl is required; copy endpoint_url from the stack's Connect page for hosted use");
+        }
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.apiKey = options.apiKey;
         this.graphName = options.graph;
         this.branchName = options.branch;
@@ -396,6 +400,53 @@ export class LbbClient {
     createGraph() {
         return this.request("POST", "/v1/graph/create");
     }
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts) {
+        return this.request("POST", "/v1/graph/fork", {
+            query: { src: opts.src, dst: opts.dst, confirm: opts.dst },
+            retry: true,
+        });
+    }
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines, opts) {
+        const ndjson = typeof lines === "string"
+            ? lines
+            : lines.map((line) => JSON.stringify(line)).join("\n");
+        return this.request("POST", "/v1/graph/reload", {
+            rawBody: ndjson,
+            contentType: "application/x-ndjson",
+            query: {
+                confirm: opts.confirm,
+                dry_run: opts.dryRun,
+                strict: opts.strict,
+                observed_at: opts.observedAt,
+            },
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("reload"),
+        });
+    }
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body) {
         return this.request("POST", "/v1/graph/branch", { body });
@@ -779,9 +830,18 @@ export class LbbClient {
                 name: opts.name,
                 relations: opts.relations?.join(","),
                 as_of: opts.asOf,
+                indexed: opts.indexed,
             },
         });
     }
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    entityTypeSample(opts) {
+        const { type, limit, ...request } = opts;
+        return this.request("GET", "/v1/graph/entities/sample", {
+            ...request,
+            query: { type, limit },
+        });
+    }
     /** Stored entity object-ref status and index-coverage metadata (no
      * attributes — read those from `entityDetail`'s top-level `attributes`). */
     entityMetadata(opts) {
@@ -1074,9 +1134,15 @@ export class LbbClient {
     status() {
         return this.request("GET", "/v1/status");
     }
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata() {
-        return this.request("GET", "/v1/graph/metadata");
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts = {}) {
+        return this.request("GET", "/v1/graph/metadata", {
+            query: {
+                include_objects: opts.includeObjects,
+                include_indexes: opts.includeIndexes,
+                include_temporal_coverage: opts.includeTemporalCoverage,
+            },
+        });
     }
     async waitForIndexLineage(targetSeq, opts = {}) {
         const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
@@ -1117,9 +1183,4 @@ export class LbbClient {
     listGraphs() {
         return this.request("GET", "/v1/graphs");
     }
-    // --- stack activity ---
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window = "24h") {
-        return this.request("GET", "/v1/stack/activity", { query: { window } });
-    }
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { LbbClient, LbbError, parseSparqlResults } from "./client.js";
-export type { LbbClientOptions, CallOptions, RequestOptions, EntityListOptions, HybridSearchOptions, LbbRequestEvent, LbbResponseEvent, LbbStackActivityResponse, LbbStackActivityWindow, FetchLike, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./client.js";
+export type { LbbClientOptions, CallOptions, RequestOptions, EntityListOptions, HybridSearchOptions, LbbRequestEvent, LbbResponseEvent, FetchLike, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./client.js";
 export type { components, paths, operations } from "./schema.js";

package/dist/namespaces.d.ts

@@ -143,6 +143,15 @@ export declare class IndexNamespace {
 export declare class EntityNamespace {
     private readonly client;
     constructor(client: LbbClient);
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts: {
+        type: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —

package/dist/namespaces.js

@@ -344,6 +344,14 @@ export class EntityNamespace {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts) {
+        return this.client.entityTypeSample(opts);
+    }
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —