@littlebigbrain/client 0.4.3 → 0.5.0

package/README.md

@@ -54,6 +54,17 @@ feedback, and model runs in little big brain:
 5. Grade cited results, reconnect to durable trainer jobs, and require a
    held-out quality plus latency gate before promotion.
 
+`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.
+
+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.
+
 The [enterprise-search integration guide](https://docs.littlebigbrain.com/guides/enterprise-search/)
 contains the graph model, migration sequence, and acceptance tests.
 

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;

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", {