@littlebigbrain/client 0.5.0 → 0.5.2

package/dist/schema.d.ts

@@ -2213,7 +2213,18 @@ export interface components {
         };
         /** @enum {string} */
         AskPlanExecutionModeV2: "entity_search" | "path_search" | "hybrid";
+        AskPlanFailure: {
+            code: components["schemas"]["AskPlanFailureCode"];
+            /** @description True when retrying after the planner recovers can produce a plan. */
+            retryable: boolean;
+            stage: components["schemas"]["AskPlanFailureStage"];
+        };
+        /** @enum {string} */
+        AskPlanFailureCode: "planner_disabled" | "planner_unavailable" | "no_class_candidates" | "generation_failed" | "validation_failed";
+        /** @enum {string} */
+        AskPlanFailureStage: "configuration" | "target_type" | "relation" | "anchor";
         AskQuery: {
+            plan_failure?: null | components["schemas"]["AskPlanFailure"];
             /** @description The retrieval query text that was executed. */
             query: string;
             structured?: null | components["schemas"]["AskStructuredQuery"];
@@ -2828,9 +2839,24 @@ export interface components {
             reranked_candidates?: number;
             source: components["schemas"]["EmbeddingIndexSource"];
             spaces_searched: number;
+            temporal_coverage?: null | components["schemas"]["SearchTemporalCoverage"];
             unindexed_tail_commits: number;
         };
         EmbeddingSearchRequest: {
+            /**
+             * Format: int64
+             * @description Snapshot pin (transaction-time ceiling): results hide every event
+             *     committed after this sequence, reproducing that past snapshot. The ANN
+             *     run is selected as the newest run at or below the pin and the pin bounds
+             *     the forward overlay; candidate generation is never the correctness layer.
+             *     Omitted means the current head.
+             */
+            as_of_commit_seq?: number | null;
+            /**
+             * @description Valid-time cursor (RFC 3339): results reflect facts true at this
+             *     instant. Omitted means the latest valid time.
+             */
+            as_of_valid_time?: string | null;
             consistency?: null | components["schemas"]["SearchConsistency"];
             /** Format: int32 */
             dim?: number | null;
@@ -3121,6 +3147,12 @@ export interface components {
             type: string;
         };
         EvidenceInput: string | {
+            /**
+             * @description Stable observation id used by full-fidelity export/import. Ordinary
+             *     callers omit it and receive the existing deterministic request id.
+             */
+            observation_id?: string | null;
+            region?: null | components["schemas"]["RegionAnchorInput"];
             source_id?: string | null;
             text?: string | null;
         };
@@ -3291,10 +3323,25 @@ export interface components {
             overlay_candidates: number;
             ranged?: null | components["schemas"]["RangedReadStats"];
             source: components["schemas"]["FullTextIndexSource"];
+            temporal_coverage?: null | components["schemas"]["SearchTemporalCoverage"];
             term_count: number;
             unindexed_tail_commits: number;
         };
         FullTextSearchRequest: {
+            /**
+             * Format: int64
+             * @description Snapshot pin (transaction-time ceiling): results hide every event
+             *     committed after this sequence, reproducing that past snapshot. The BM25
+             *     run is selected as the newest run at or below the pin and the pin bounds
+             *     the forward overlay; candidate generation is never the correctness layer.
+             *     Omitted means the current head.
+             */
+            as_of_commit_seq?: number | null;
+            /**
+             * @description Valid-time cursor (RFC 3339): results reflect facts true at this
+             *     instant. Omitted means the latest valid time.
+             */
+            as_of_valid_time?: string | null;
             consistency?: null | components["schemas"]["SearchConsistency"];
             explain: boolean;
             facets?: components["schemas"]["FacetRequest"][] | null;
@@ -3705,6 +3752,8 @@ export interface components {
              *     exact receipt and the original terminal commit sequence.
              */
             mutation_receipt_id: string;
+            /** @description Exact observation records imported from a full-fidelity export. */
+            observations?: number;
             properties: number;
             triplets: number;
         };
@@ -4198,6 +4247,8 @@ export interface components {
             message: string;
             param?: string | null;
             request_id: string | null;
+            retry_after_seconds?: number;
+            retryable?: boolean;
             /** @example invalid_request_error */
             type: string;
         };
@@ -5430,6 +5481,32 @@ export interface components {
             total_triples: number;
             truncated: boolean;
         };
+        /**
+         * @description A page-region provenance anchor on a fact's evidence (region provenance
+         *     §4.1/§6.4(b) BYO import): where the evidence appears in the source
+         *     document. Coordinates are **normalized to the page box** (`[0, 1]`, origin
+         *     top-left, y down) with `x0 <= x1` and `y0 <= y1`; `confidence` is the
+         *     extraction confidence in `[0, 1]`. The commit path validates and quantizes
+         *     (`round(v * 65535)` coords, `round(c * 255)` confidence) into the canonical
+         *     stored anchor; out-of-range, non-finite, or inverted boxes are rejected.
+         */
+        RegionAnchorInput: {
+            /** Format: double */
+            confidence: number;
+            /**
+             * Format: int32
+             * @description 0-based page index within the source document.
+             */
+            page: number;
+            /** Format: double */
+            x0: number;
+            /** Format: double */
+            x1: number;
+            /** Format: double */
+            y0: number;
+            /** Format: double */
+            y1: number;
+        };
         RelationSearchResult: {
             name: string;
             relation_id: components["schemas"]["RelationTypeId"];
@@ -5584,6 +5661,12 @@ export interface components {
             terms: components["schemas"]["ResolutionResult"][];
         };
         ResolvedTerm: {
+            /**
+             * @description Ontology description/definition when the resolved schema term carries
+             *     one. Candidate-free class resolution preserves tenant-authored class
+             *     documentation instead of returning only a bare label.
+             */
+            description?: string | null;
             kind: components["schemas"]["SuggestKind"];
             provenance?: null | components["schemas"]["VocabularyProvenance"];
             /**
@@ -5592,6 +5675,7 @@ export interface components {
              */
             score: number;
             text: string;
+            type_signature?: null | components["schemas"]["VocabularyTypeSignature"];
         };
         /** @description One edge to retract, identified the same way it was asserted. */
         RetractEdgeInput: {
@@ -6518,6 +6602,25 @@ export interface components {
             signature_forced?: boolean;
             text: string;
         };
+        /**
+         * @description How a temporally-pinned (or head) search resolved run selection: the
+         *     effective `as_of` ceiling, the base snapshot of the selected persisted
+         *     run(s), and the highest commit each leg's run+segments actually covered
+         *     (the forward WAL overlay covers `(covered_through, ceiling]`). Distinct from
+         *     the ontology-inspect `TemporalCoverage` type. Per-leg fields are `None` when
+         *     that leg served from an ephemeral rebuild (no persisted run at the ceiling).
+         */
+        SearchTemporalCoverage: {
+            bm25_covered_through?: null | components["schemas"]["CommitSeq"];
+            bm25_run_snapshot_commit_seq?: null | components["schemas"]["CommitSeq"];
+            /**
+             * @description Resolved transaction-time ceiling: the `as_of_commit_seq` pin, or the
+             *     head commit_seq when the query was unpinned.
+             */
+            ceiling_commit_seq: components["schemas"]["CommitSeq"];
+            vector_covered_through?: null | components["schemas"]["CommitSeq"];
+            vector_run_snapshot_commit_seq?: null | components["schemas"]["CommitSeq"];
+        };
         SemanticGraphSearchRequest: {
             /**
              * Format: int64
@@ -6637,6 +6740,7 @@ export interface components {
              *     candidate generation.
              */
             target_prep_ms?: number;
+            temporal_coverage?: null | components["schemas"]["SearchTemporalCoverage"];
             /** Format: int64 */
             total_ms?: number;
             /**
@@ -6692,6 +6796,13 @@ export interface components {
             as_of_valid_time?: string | null;
             direction: components["schemas"]["ExpansionDirection"];
             explain: boolean;
+            /**
+             * @description Entity properties to project for every returned seed and path node.
+             *     Projections are reduced from the same snapshot used for authorization
+             *     and traversal. Requesting fields routes the operation through the exact
+             *     snapshot path rather than ranged adjacency.
+             */
+            fields?: string[];
             /**
              * Format: int64
              * @description Decoded adjacency-block working-set byte budget for persisted-vector
@@ -6717,6 +6828,15 @@ export interface components {
         SemanticTraverseResponse: {
             explain?: null | components["schemas"]["SemanticTraverseExplain"];
             paths: components["schemas"]["PathResult"][];
+            /**
+             * @description Requested properties keyed by entity id for every returned seed and
+             *     path node. Empty when `fields` was omitted.
+             */
+            projected_nodes?: {
+                [key: string]: {
+                    [key: string]: unknown;
+                };
+            };
             ranged?: null | components["schemas"]["RangedTraverseStats"];
             seeds: components["schemas"]["ScoredEntityView"][];
             snapshot: components["schemas"]["SnapshotView"];
@@ -7062,6 +7182,13 @@ export interface components {
         ShadowEvalResponse: {
             challenger: components["schemas"]["ShadowArmResult"];
             champion: components["schemas"]["ShadowArmResult"];
+            /**
+             * @description Fail-closed promotion verdict over the same labeled queries and pinned
+             *     snapshot. Requires quality non-regression plus p50/p95/p99 latency
+             *     ratios within the configured ceiling; this endpoint still never
+             *     performs the promotion itself.
+             */
+            gate: components["schemas"]["TrainGateReport"];
             /** @description Labeled queries (those with `expected`) the hit rates are over. */
             labeled: number;
             /** Format: float */
@@ -7778,7 +7905,8 @@ export interface components {
         TrainGateReport: {
             /**
              * Format: float
-             * @description Challenger − champion hit-rate on the held-out eval slice.
+             * @description Challenger − champion primary quality metric on the held-out eval
+             *     slice (nDCG for fusion and retrieval-profile comparisons).
              */
             effect: number;
             /** Format: float */
@@ -7787,7 +7915,18 @@ export interface components {
             labeled: number;
             /**
              * Format: double
-             * @description Challenger / champion mean-latency ratio on the eval slice.
+             * @description Challenger / champion latency ratios at each reported percentile.
+             */
+            latency_p50_ratio?: number | null;
+            /** Format: double */
+            latency_p95_ratio?: number | null;
+            /** Format: double */
+            latency_p99_ratio?: number | null;
+            /**
+             * Format: double
+             * @description Legacy decision latency ratio. For configuration shadow evaluation this
+             *     is the worst of p50/p95/p99; older trainer kinds may use their primary
+             *     latency statistic.
              */
             latency_ratio: number;
             /**
@@ -7820,7 +7959,8 @@ export interface components {
             reason: string;
             /**
              * Format: float
-             * @description Fusion-only paired held-out deltas. All must be non-negative.
+             * @description Paired held-out retrieval deltas. When present, all must be
+             *     non-negative.
              */
             recall_delta?: number | null;
         };
@@ -8125,6 +8265,11 @@ export interface components {
         };
         /** @enum {string} */
         VocabularyOrigin: "builtin" | "tenant" | "imported";
+        VocabularyPropertySignature: {
+            name: string;
+            required: boolean;
+            value_type: string;
+        };
         VocabularyProvenance: {
             candidate_id: string;
             namespace: string;
@@ -8133,6 +8278,15 @@ export interface components {
             origin: components["schemas"]["VocabularyOrigin"];
             source_reference: string;
         };
+        VocabularyTypeSignature: {
+            properties?: components["schemas"]["VocabularyPropertySignature"][];
+            source_types?: string[];
+            /** @description Frozen normalized schema identity. */
+            stable_id: string;
+            super_types?: string[];
+            target_types?: string[];
+            value_type?: string | null;
+        };
         WalCompactRequest: {
             /**
              * @description When appending the new segment would leave the manifest with more

package/dist/transport.d.ts

@@ -30,6 +30,8 @@ export declare class LbbError extends Error {
     readonly param?: string | null;
     readonly requestId?: string | null;
     readonly docUrl?: string | null;
+    readonly retryable?: boolean;
+    readonly retryAfterSeconds?: number;
     constructor(status: number, body: string, error?: LbbErrorPayload | undefined);
 }
 export type QueryValue = string | number | boolean | undefined;

package/dist/transport.js

@@ -8,6 +8,8 @@ export class LbbError extends Error {
     param;
     requestId;
     docUrl;
+    retryable;
+    retryAfterSeconds;
     constructor(status, body, error) {
         super(error?.message ?? `Little Big Brain ${status}: ${body}`);
         this.status = status;
@@ -19,6 +21,8 @@ export class LbbError extends Error {
         this.param = error?.param;
         this.requestId = error?.request_id;
         this.docUrl = error?.doc_url;
+        this.retryable = error?.retryable;
+        this.retryAfterSeconds = error?.retry_after_seconds;
     }
 }
 export function sleep(ms) {

package/dist/types.d.ts

@@ -281,6 +281,8 @@ export interface LbbErrorPayload {
     param?: string | null;
     request_id?: string | null;
     doc_url?: string | null;
+    retryable?: boolean;
+    retry_after_seconds?: number;
 }
 export interface RawLbbResponse<T> {
     data: T;

package/package.json

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