@littlebigbrain/client 0.5.2 → 0.6.0

package/README.md

@@ -79,6 +79,16 @@ 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
 ```
 
 Other focused methods cover managed embeddings, full-text/vector search,

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import type { ImportLine, LbbClientOptions, LbbStackActivityResponse, LbbStackAc
 import { 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, 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, 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 { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
@@ -31,9 +31,11 @@ export declare class LbbClient {
     private readonly apiVersion;
     private readonly maxRetries;
     private readonly retryDelayMs;
+    private readonly retryBudgetMs;
     private readonly timeoutMs;
     private readonly onRequest?;
     private readonly onResponse?;
+    private readonly onRetry?;
     readonly context: ContextNamespace;
     readonly search: SearchNamespace;
     readonly indexes: IndexNamespace;
@@ -132,15 +134,25 @@ export declare class LbbClient {
     observe(body: Schemas["ObserveRequest"], opts?: {
         idempotencyKey?: string;
     }): Promise<Schemas["ObserveResponse"]>;
-    /**
-     * Delete every object under the scoped graph/branch — a destructive reset.
-     * `confirm` must equal the scoped graph id; the next commit re-initializes the
-     * graph. Branch-scoped: sibling branches are untouched.
-     */
+    /** Delete the scoped graph, including every branch, feedback, and active graph-scoped job. */
     deleteGraph(opts: {
         confirm: string;
-    }): Promise<unknown>;
+    }): Promise<Schemas["GraphDeleteResponse"]>;
+    /** Delete only the scoped branch. The server refuses to delete a graph's final live branch. */
+    deleteBranch(opts: {
+        confirm: string;
+    }): Promise<Schemas["GraphBranchDeleteResponse"]>;
     embeddingConfig(): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
+    /** List the embedding models available on this deployment. */
+    embeddingModels(): Promise<Schemas["ManagedEmbeddingModelsResponse"]>;
+    /**
+     * Choose the model used automatically for writes and vector queries.
+     * Provider credentials and native dimension discovery stay server-side.
+     */
+    setEmbeddingModel(modelId: string, opts?: {
+        autoEmbedQuery?: boolean;
+    }): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
+    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
     setEmbeddingConfig(body: Schemas["ManagedEmbeddingConfigRequest"]): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
     submitEmbeddingBackfill(opts?: {
         batchSize?: number;
@@ -539,6 +551,14 @@ export declare class LbbClient {
     indexRun(opts?: {
         background?: boolean;
     }): Promise<unknown>;
+    /** Submit a durable full-index build. Requires a reconnect-safe idempotency key. */
+    indexSubmit(body: Partial<Schemas["IndexBuildOptions"]> | undefined, opts: {
+        idempotencyKey: string;
+    }): Promise<Schemas["SearchIndexJobStatusResponse"]>;
+    /** Poll a durable full-index build. */
+    indexJob(jobId: string): Promise<Schemas["SearchIndexJobStatusResponse"]>;
+    /** Cancel a durable full-index build. Repeated cancellation returns its current terminal status. */
+    cancelIndexJob(jobId: string): Promise<Schemas["SearchIndexJobStatusResponse"]>;
     /** Append a BM25 delta segment for the unindexed WAL tail. */
     indexDelta(): Promise<Schemas["IndexDeltaResponse"]>;
     /** Preview or delete superseded persisted index runs. */
@@ -546,6 +566,14 @@ export declare class LbbClient {
         keepRuns?: number;
         dryRun?: boolean;
     }): Promise<Schemas["IndexGcResponse"]>;
+    /** Submit durable, cancellable index garbage collection. */
+    indexGcSubmit(body: Schemas["IndexGcRequest"] | undefined, opts: {
+        idempotencyKey: string;
+    }): Promise<Schemas["IndexGcJobStatusResponse"]>;
+    /** Poll exact planning/deletion progress for durable index garbage collection. */
+    indexGcJob(jobId: string): Promise<Schemas["IndexGcJobStatusResponse"]>;
+    /** Cancel durable index garbage collection. */
+    cancelIndexGcJob(jobId: string): Promise<Schemas["IndexGcJobStatusResponse"]>;
     /** Fold the WAL tail into snapshot segments. */
     compact(opts?: {
         minTailCommits?: number;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { parseSparqlResults } from "./types.js";
-import { parseLbbError, parseResponseJson, retryAllowed, retryDelayForAttempt, retryableStatus, sleep, } from "./transport.js";
+import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
 import { ContextNamespace, EntityNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export { LbbError } from "./transport.js";
@@ -19,9 +19,11 @@ export class LbbClient {
     apiVersion;
     maxRetries;
     retryDelayMs;
+    retryBudgetMs;
     timeoutMs;
     onRequest;
     onResponse;
+    onRetry;
     context;
     search;
     indexes;
@@ -36,17 +38,22 @@ export class LbbClient {
         this.branchName = options.branch;
         this.stack = options.stack;
         this.apiVersion = options.apiVersion ?? "2026-06-22";
-        this.maxRetries = options.maxRetries ?? 2;
+        this.maxRetries = options.maxRetries ?? 6;
         this.retryDelayMs = options.retryDelayMs ?? 100;
+        this.retryBudgetMs = options.retryBudgetMs ?? 60_000;
         this.timeoutMs = options.timeoutMs ?? 120_000;
         this.onRequest = options.onRequest;
         this.onResponse = options.onResponse;
+        this.onRetry = options.onRetry;
         if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0) {
             throw new RangeError("maxRetries must be a non-negative integer");
         }
         if (!Number.isFinite(this.retryDelayMs) || this.retryDelayMs < 0) {
             throw new RangeError("retryDelayMs must be a non-negative number");
         }
+        if (!Number.isFinite(this.retryBudgetMs) || this.retryBudgetMs < 0) {
+            throw new RangeError("retryBudgetMs must be a non-negative number");
+        }
         if (!Number.isFinite(this.timeoutMs) || this.timeoutMs < 0) {
             throw new RangeError("timeoutMs must be a non-negative number");
         }
@@ -87,9 +94,11 @@ export class LbbClient {
             apiVersion: this.apiVersion,
             maxRetries: this.maxRetries,
             retryDelayMs: this.retryDelayMs,
+            retryBudgetMs: this.retryBudgetMs,
             timeoutMs: this.timeoutMs,
             onRequest: this.onRequest,
             onResponse: this.onResponse,
+            onRetry: this.onRetry,
         });
     }
     buildUrl(path, query) {
@@ -135,6 +144,8 @@ export class LbbClient {
             throw new RangeError("maxRetries must be a non-negative integer");
         }
         const startedAt = Date.now();
+        // Deadline is the binding limit; `maxRetries` is a secondary safety cap.
+        const deadline = startedAt + Math.max(0, opts.retryBudgetMs ?? this.retryBudgetMs);
         const url = this.buildUrl(path, opts.query);
         let attempts = 0;
         let response;
@@ -175,8 +186,19 @@ export class LbbClient {
                     }), { name: "TimeoutError" })
                     : error;
                 if (!callerAborted && canRetry && attempt < maxRetries) {
-                    await sleep(this.retryDelayMs * (attempt + 1));
-                    continue;
+                    const delayMs = fullJitterBackoffMs(this.retryDelayMs, attempt);
+                    if (Date.now() + delayMs <= deadline) {
+                        this.onRetry?.({
+                            method: method.toUpperCase(),
+                            url,
+                            attempt: attempts,
+                            status: undefined,
+                            delayMs,
+                            elapsedMs: Math.max(0, Date.now() - startedAt),
+                        });
+                        await sleep(delayMs);
+                        continue;
+                    }
                 }
                 throw requestError;
             }
@@ -193,7 +215,29 @@ export class LbbClient {
             if (!canRetry) {
                 break;
             }
-            await sleep(retryDelayForAttempt(this.retryDelayMs, attempt, response.headers?.get("retry-after")));
+            // Honor the server's typed body verdict: a terminal error
+            // (`retryable: false`, e.g. an exhausted quota) is surfaced at once
+            // rather than retried to the budget.
+            if (bodyMarksTerminal(text)) {
+                break;
+            }
+            const delayMs = retryDelayMs(this.retryDelayMs, attempt, {
+                retryAfterHeader: response.headers?.get("retry-after"),
+                body: text,
+            });
+            if (Date.now() + delayMs > deadline) {
+                break;
+            }
+            this.onRetry?.({
+                method: method.toUpperCase(),
+                url,
+                attempt: attempts,
+                status: response.status,
+                errorCode: errorCodeFromBody(text),
+                delayMs,
+                elapsedMs: Math.max(0, Date.now() - startedAt),
+            });
+            await sleep(delayMs);
         }
         if (response === undefined)
             throw new Error("request did not produce a response");
@@ -379,19 +423,38 @@ export class LbbClient {
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("observe"),
         });
     }
-    /**
-     * Delete every object under the scoped graph/branch — a destructive reset.
-     * `confirm` must equal the scoped graph id; the next commit re-initializes the
-     * graph. Branch-scoped: sibling branches are untouched.
-     */
+    /** Delete the scoped graph, including every branch, feedback, and active graph-scoped job. */
     deleteGraph(opts) {
         return this.request("POST", "/v1/graph/delete", {
             query: { confirm: opts.confirm },
+            retry: true,
+        });
+    }
+    /** Delete only the scoped branch. The server refuses to delete a graph's final live branch. */
+    deleteBranch(opts) {
+        return this.request("DELETE", "/v1/graph/branch", {
+            query: { confirm: opts.confirm },
         });
     }
     embeddingConfig() {
         return this.request("GET", "/v1/graph/embedding");
     }
+    /** List the embedding models available on this deployment. */
+    embeddingModels() {
+        return this.request("GET", "/v1/graph/embedding/models");
+    }
+    /**
+     * Choose the model used automatically for writes and vector queries.
+     * Provider credentials and native dimension discovery stay server-side.
+     */
+    setEmbeddingModel(modelId, opts = {}) {
+        return this.setEmbeddingConfig({
+            model_id: modelId,
+            service: "open_router",
+            auto_embed_query: opts.autoEmbedQuery ?? true,
+        });
+    }
+    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
     setEmbeddingConfig(body) {
         return this.request("POST", "/v1/graph/embedding", { body });
     }
@@ -951,6 +1014,23 @@ export class LbbClient {
             query: { background: opts.background || undefined },
         });
     }
+    /** Submit a durable full-index build. Requires a reconnect-safe idempotency key. */
+    indexSubmit(body = {}, opts) {
+        return this.request("POST", "/v1/index/jobs", {
+            body,
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /** Poll a durable full-index build. */
+    indexJob(jobId) {
+        return this.request("GET", "/v1/index/jobs", { query: { job_id: jobId } });
+    }
+    /** Cancel a durable full-index build. Repeated cancellation returns its current terminal status. */
+    cancelIndexJob(jobId) {
+        return this.request("DELETE", "/v1/index/jobs", {
+            query: { job_id: jobId },
+        });
+    }
     /** Append a BM25 delta segment for the unindexed WAL tail. */
     indexDelta() {
         return this.request("POST", "/v1/index/delta");
@@ -961,6 +1041,25 @@ export class LbbClient {
             query: { keep_runs: opts.keepRuns, dry_run: opts.dryRun },
         });
     }
+    /** Submit durable, cancellable index garbage collection. */
+    indexGcSubmit(body = {}, opts) {
+        return this.request("POST", "/v1/index/gc-jobs", {
+            body,
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /** Poll exact planning/deletion progress for durable index garbage collection. */
+    indexGcJob(jobId) {
+        return this.request("GET", "/v1/index/gc-jobs", {
+            query: { job_id: jobId },
+        });
+    }
+    /** Cancel durable index garbage collection. */
+    cancelIndexGcJob(jobId) {
+        return this.request("DELETE", "/v1/index/gc-jobs", {
+            query: { job_id: jobId },
+        });
+    }
     /** Fold the WAL tail into snapshot segments. */
     compact(opts = {}) {
         return this.request("POST", "/v1/graph/compact", {

package/dist/namespaces.d.ts

@@ -32,8 +32,18 @@ export declare class GraphNamespace {
     create(opts?: CallOptions): Promise<Schemas["CreateGraphResponse"]>;
     delete(opts: {
         confirm: string;
-    } & CallOptions): Promise<unknown>;
+    } & CallOptions): Promise<Schemas["GraphDeleteResponse"]>;
+    deleteBranch(opts: {
+        confirm: string;
+    } & CallOptions): Promise<Schemas["GraphBranchDeleteResponse"]>;
     embeddingConfig(opts?: CallOptions): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
+    /** List the embedding models available on this deployment. */
+    embeddingModels(opts?: CallOptions): Promise<Schemas["ManagedEmbeddingModelsResponse"]>;
+    /** Choose the model used automatically for writes and vector queries. */
+    setEmbeddingModel(modelId: string, options?: CallOptions & {
+        autoEmbedQuery?: boolean;
+    }): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
+    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
     setEmbeddingConfig(body: Schemas["ManagedEmbeddingConfigRequest"], opts?: CallOptions): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
     backfillEmbeddings(options?: CallOptions & {
         batchSize?: number;
@@ -115,10 +125,20 @@ export declare class IndexNamespace {
         background?: boolean;
     } & CallOptions): Promise<unknown>;
     delta(opts?: CallOptions): Promise<Schemas["IndexDeltaResponse"]>;
+    submit(body: Partial<Schemas["IndexBuildOptions"]> | undefined, opts: CallOptions & {
+        idempotencyKey: string;
+    }): Promise<Schemas["SearchIndexJobStatusResponse"]>;
+    job(jobId: string, opts?: CallOptions): Promise<Schemas["SearchIndexJobStatusResponse"]>;
+    cancel(jobId: string, opts?: CallOptions): Promise<Schemas["SearchIndexJobStatusResponse"]>;
     gc(opts?: {
         keepRuns?: number;
         dryRun?: boolean;
     } & CallOptions): Promise<Schemas["IndexGcResponse"]>;
+    submitGc(body: Schemas["IndexGcRequest"] | undefined, opts: CallOptions & {
+        idempotencyKey: string;
+    }): Promise<Schemas["IndexGcJobStatusResponse"]>;
+    gcJob(jobId: string, opts?: CallOptions): Promise<Schemas["IndexGcJobStatusResponse"]>;
+    cancelGc(jobId: string, opts?: CallOptions): Promise<Schemas["IndexGcJobStatusResponse"]>;
 }
 export declare class EntityNamespace {
     private readonly client;

package/dist/namespaces.js

@@ -41,11 +41,36 @@ export class GraphNamespace {
         return this.client.request("POST", "/v1/graph/delete", {
             ...request,
             query: { confirm },
+            retry: request.retry ?? true,
+        });
+    }
+    deleteBranch(opts) {
+        const { confirm, ...request } = opts;
+        return this.client.request("DELETE", "/v1/graph/branch", {
+            ...request,
+            query: { confirm },
         });
     }
     embeddingConfig(opts = {}) {
         return this.client.request("GET", "/v1/graph/embedding", opts);
     }
+    /** List the embedding models available on this deployment. */
+    embeddingModels(opts = {}) {
+        return this.client.request("GET", "/v1/graph/embedding/models", opts);
+    }
+    /** Choose the model used automatically for writes and vector queries. */
+    setEmbeddingModel(modelId, options = {}) {
+        const { autoEmbedQuery, ...request } = options;
+        return this.client.request("POST", "/v1/graph/embedding", {
+            ...request,
+            body: {
+                model_id: modelId,
+                service: "open_router",
+                auto_embed_query: autoEmbedQuery ?? true,
+            },
+        });
+    }
+    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
     setEmbeddingConfig(body, opts = {}) {
         return this.client.request("POST", "/v1/graph/embedding", {
             ...opts,
@@ -276,6 +301,21 @@ export class IndexNamespace {
     delta(opts = {}) {
         return this.client.request("POST", "/v1/index/delta", opts);
     }
+    submit(body = {}, opts) {
+        return this.client.request("POST", "/v1/index/jobs", { ...opts, body });
+    }
+    job(jobId, opts = {}) {
+        return this.client.request("GET", "/v1/index/jobs", {
+            ...opts,
+            query: { job_id: jobId },
+        });
+    }
+    cancel(jobId, opts = {}) {
+        return this.client.request("DELETE", "/v1/index/jobs", {
+            ...opts,
+            query: { job_id: jobId },
+        });
+    }
     gc(opts = {}) {
         const { keepRuns, dryRun, ...request } = opts;
         return this.client.request("POST", "/v1/index/gc", {
@@ -283,6 +323,21 @@ export class IndexNamespace {
             query: { keep_runs: keepRuns, dry_run: dryRun },
         });
     }
+    submitGc(body = {}, opts) {
+        return this.client.request("POST", "/v1/index/gc-jobs", { ...opts, body });
+    }
+    gcJob(jobId, opts = {}) {
+        return this.client.request("GET", "/v1/index/gc-jobs", {
+            ...opts,
+            query: { job_id: jobId },
+        });
+    }
+    cancelGc(jobId, opts = {}) {
+        return this.client.request("DELETE", "/v1/index/gc-jobs", {
+            ...opts,
+            query: { job_id: jobId },
+        });
+    }
 }
 export class EntityNamespace {
     client;