@farukada/aws-langgraph-dynamodb-ts 0.9.0 → 1.0.0-rc.2

package/dist/store/internal/vector-index.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Hides the vector backend as a copy of the items' embeddings.
+ *
+ * When a store is given a `VectorBackend`, every item's embedding is kept there
+ * as well as the item in the table, and the table is the truth. When the copy
+ * is written (after the row commits), when an entry is dropped (only once a
+ * fresh read finds the row gone), how a backend's answer is resolved back to
+ * the canonical items and in which direction its scores run, and how the copy
+ * is repaired against the table are decided here, and nothing else calls the
+ * backend.
+ */
+import type { IndexConfig, SearchItem } from '@langchain/langgraph-checkpoint';
+import type { VectorReconcileResult } from '../types';
+import type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection } from '../vector-backend';
+import { type Namespace, type ParsedPut, type ParsedSearch, type StoreAddress } from './parse';
+import type { StoreContext } from './setup';
+/** A store context whose vector copy is configured: an embeddings index and a backend. */
+export type BackendContext = StoreContext & {
+    readonly index: IndexConfig;
+    readonly vectorBackend: VectorBackend;
+};
+/**
+ * Whether the store keeps a vector copy.
+ *
+ * Accepts: `context` — the store's.
+ *
+ * Returns: `true`, narrowing `context`, when both `index` and `vectorBackend`
+ * are configured.
+ *
+ * Throws: nothing.
+ */
+export declare function hasVectorBackend(context: StoreContext): context is BackendContext;
+/**
+ * The one vector a put gives the backend for its item.
+ *
+ * Accepts: `op` — the parsed put. Its `index` is `false` to embed nothing, a
+ * field list to embed those fields, absent to embed the configured ones.
+ *
+ * Returns: the joined embedding, or `undefined` when the store keeps no vector
+ * copy, the put indexes nothing, or the value has no text to embed.
+ *
+ * Throws: `VALIDATION` naming `index.dims` when the model returns a vector of
+ * another length; whatever `embedDocuments` throws.
+ */
+export declare function itemVector(context: StoreContext, op: ParsedPut): Promise<number[] | undefined>;
+/**
+ * Write an item's entry in the vector copy after its row has committed: the
+ * vector when there is one, a delete when there is none. Best-effort sync of
+ * one item's embedding to the vector backend after the canonical DynamoDB
+ * write has already succeeded.
+ *
+ * Accepts: `address` — the item's. `embedding` — from {@link itemVector}:
+ * present upserts it; absent deletes any vector the backend still holds, which
+ * is what a re-put with no indexable text, an `index: false` put and a delete
+ * all mean.
+ *
+ * Returns: nothing, in both the synced and the failed case; without a backend,
+ * nothing is done.
+ *
+ * Throws: nothing. The canonical item is already committed, so failing here
+ * would report a put that in fact succeeded; the drift is logged at `warn` and
+ * `reconcileVectorIndex` repairs it.
+ */
+export declare function syncItemVector(context: StoreContext, address: StoreAddress, embedding: number[] | undefined): Promise<void>;
+/**
+ * Drop the item's vector, but only on a fresh read that finds no row at the
+ * key.
+ *
+ * The question is deliberately **not** "did this call remove the row" — that
+ * one is true in exactly the interleaving that goes wrong. It is "does the key
+ * hold a row *now*", which a racing put that recreated it and a
+ * compare-and-swap that left it alone both answer the same way, and which costs
+ * a point read of this library's own table rather than anything the backend has
+ * to offer. The reconciler asks the same question before pruning a vector, so
+ * the delete path and the reconciler are equally careful.
+ *
+ * A read that itself fails answers "not confirmed" and keeps the vector: a
+ * stale vector for a deleted item, which `reconcileVectorIndex` removes, rather
+ * than a missing one for a live item, which is the defect this exists for.
+ *
+ * Accepts: `address` — the deleted item's; the row read is derived from it.
+ *
+ * Returns: nothing; without a backend, nothing is read or dropped. A row still
+ * at the key keeps its vector and logs one `info`.
+ *
+ * Throws: nothing the backend throws (see {@link syncItemVector}); whatever the
+ * confirmation read throws that `isRowAbsent` does not answer as "not
+ * confirmed".
+ */
+export declare function dropVectorWhenGone(context: StoreContext, address: StoreAddress): Promise<void>;
+/** A canonical item's location plus the embedding recomputed for it. */
+export interface ReconcileTarget {
+    namespace: string[];
+    key: string;
+    embedding: number[] | undefined;
+}
+/**
+ * Enumerate the live (unexpired) items under `prefix` and recompute their
+ * embeddings.
+ *
+ * Accepts: `prefix` — at least one element, since the enumeration is one
+ * partition's Query; reconciling is always scoped. `signal` — aborts between
+ * pages.
+ *
+ * Returns: one target per live item, each with the embedding the item's current
+ * value produces — `undefined` when it yields no indexable text, which is the
+ * evidence that lets {@link pruneOrphans} drop a vector that has gone stale.
+ *
+ * Throws: whatever the reads, the decodes and the embeddings model throw; a
+ * failed embedding rejects the whole reconcile, because a skipped item would
+ * leave the live set and {@link selectOrphans} would prune its still-valid
+ * vector. `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
+ * remain — reconciling from a partial view would prune live vectors.
+ *
+ * Guarantees: rows are decoded in bounded batches, so a namespace of offloaded
+ * items costs neither one round-trip at a time nor every payload in memory at
+ * once.
+ */
+export declare function collectReconcileTargets(context: StoreContext, prefix: Namespace, signal?: AbortSignal): Promise<ReconcileTarget[]>;
+/**
+ * Re-push every live embedding to the backend.
+ *
+ * Accepts: `targets` — a target with no embedding is not pushed; its vector is
+ * {@link pruneOrphans}' business, not an upsert of nothing.
+ *
+ * Returns: how many vectors were upserted.
+ *
+ * Throws: whatever the backend throws. The upserts are issued one at a time on
+ * purpose: this is a bulk repair against a third-party index, and the run has
+ * no latency budget worth a thundering herd.
+ */
+export declare function pushEmbeddings(backend: VectorBackend, targets: ReconcileTarget[]): Promise<number>;
+/**
+ * Refs the backend holds that the live set does not account for.
+ *
+ * Accepts: `backendRefs` — whatever the backend lists under the prefix.
+ * `live` — the snapshot; a target with no embedding does not account for a
+ * vector, since its item no longer produces one.
+ *
+ * Returns: the candidates to prune — candidates, not conclusions: the snapshot
+ * and the backend listing are not one point in time (see {@link pruneOrphans}).
+ *
+ * Throws: nothing.
+ */
+export declare function selectOrphans(backendRefs: VectorRef[], live: ReconcileTarget[]): VectorRef[];
+/**
+ * Delete backend vectors with no canonical item.
+ *
+ * Accepts: `live` — the snapshot {@link collectReconcileTargets} took.
+ * `backend.listKeys` — optional; a backend that cannot enumerate its own keys
+ * cannot be pruned, which is reported rather than silently skipped.
+ *
+ * Returns: how many vectors were deleted.
+ *
+ * Throws: whatever the backend and the confirmation read throw.
+ *
+ * Guarantees: a vector is deleted only on evidence that its item is gone — the
+ * snapshot saw the item and it yields no embedding, or a fresh
+ * strongly-consistent read finds no row at all. An item written between the
+ * snapshot and the listing looks orphaned and is kept, so reconciling never
+ * drops a just-written item out of semantic search.
+ */
+export declare function pruneOrphans(context: StoreContext, backend: VectorBackend, prefix: Namespace, live: ReconcileTarget[]): Promise<number>;
+/**
+ * Repair the vector copy against the items under a prefix: re-push every live
+ * embedding, then prune entries whose item is confirmed gone.
+ *
+ * Accepts: `prefix` — parsed. `signal` — cancels the table read.
+ *
+ * Returns: how many entries were upserted and pruned.
+ *
+ * Throws: whatever the table read, the embeddings model or the backend throws.
+ */
+export declare function reconcileVectors(context: BackendContext, prefix: Namespace, signal?: AbortSignal): Promise<VectorReconcileResult>;
+/**
+ * Rank a search through a configured vector backend.
+ *
+ * Accepts: `context` — the store's, with the backend searched and the index
+ * whose embeddings model embeds the query. `search.query` — non-empty; the
+ * caller checks that before choosing this path. `search.offset`/`search.limit`
+ * — the page, whose end (`offset + limit`) must fit within
+ * `maxSearchCandidates`, since that many matches have to be fetched to fill it.
+ * `search.filter` — applied to the canonical item, not to whatever the backend
+ * stored, so a filter is never answered from a stale vector.
+ *
+ * Returns: the page's items in the backend's order, each carrying the relevance
+ * score for its vector. Fewer than `limit` items means the backend has no more
+ * matches under the prefix, not that the page was cut short.
+ *
+ * Throws: `VALIDATION` naming `index.dims` when the query embeds to a
+ * different width than the index declares, and naming `maxSearchCandidates`
+ * either for a page larger than the cap or when the filter leaves the page short
+ * at the cap — the same answer the in-DynamoDB ranker gives, rather than a
+ * silently short page. Whatever a canonical read throws — a read that did not
+ * happen is not an item that is not there — since a match this store cannot
+ * address is dropped before its read rather than caught after it (see
+ * {@link addressOf}). Whatever the embeddings model and the backend throw.
+ *
+ * Guarantees: DynamoDB stays canonical. A match whose item has since been
+ * deleted or lies outside the prefix is dropped and the search asks the backend
+ * for more, so a stale or over-broad index costs results only in latency. A
+ * match whose read *fails* is not dropped: the page a caller receives is never
+ * shorter than the matches that exist, which is what the in-DynamoDB path
+ * already promises. Items are fetched with the same bounded concurrency as the
+ * in-DynamoDB path, and each distinct match is read once for the whole call
+ * however many rounds it takes (see {@link fetchUnseen}).
+ */
+export declare function searchViaBackend(context: BackendContext, search: ParsedSearch, signal?: AbortSignal): Promise<SearchItem[]>;
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ *
+ * Accepts: `matches` — in any order, including empty. `direction` — only the
+ * exact string `'distance'` converts; every other value, recognised or not,
+ * passes the matches through untouched.
+ *
+ * Returns: matches whose `score` follows the relevance direction upstream
+ * documents, highest first. Converting re-sorts, so a backend that returned its
+ * matches in some other order still ranks correctly.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the conversion is exactly invertible — the original distance is
+ * `-score` — so nothing about the backend's answer is lost.
+ */
+export declare function toRelevanceScores(matches: VectorMatch[], direction: VectorScoreDirection): VectorMatch[];