@dudousxd/nestjs-agent-rag 0.13.1 → 0.14.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler, RerankOptions, ModelProvider, AiToolCtx } from '@dudousxd/nestjs-agent-core';
+import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler, AiToolCtx, RerankOptions, ModelProvider } from '@dudousxd/nestjs-agent-core';
 
 interface ChunkOptions {
     /** Target max characters per chunk. Default 800. */
@@ -89,7 +89,10 @@ interface VectorRecord {
 }
 interface VectorSearchOptions {
     topK: number;
-    /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */
+    /**
+     * Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`.
+     * An empty array or an `undefined` value matches nothing.
+     */
     filter?: Record<string, unknown>;
 }
 /**
@@ -235,6 +238,8 @@ interface VectorStore {
      *   got built wrong (a dropped key, an `undefined` scope) than a deliberate request to delete
      *   everything. Deliberate mass deletion stays available and stays explicit:
      *   `removeMany(await store.listDocumentIds())`, or the backend's own drop.
+     * - **A key with an `undefined` value throws** {@link UnsafeRemovalError} too, for the same reason:
+     *   `removeWhere({ tenantId: actor.tenantRef })` with no tenant is a bug, not a request.
      *
      * What it removes is exactly what a {@link VectorStore.search} carrying the same filter could
      * reach — no more (it cannot escape the filter) and no less.
@@ -273,6 +278,17 @@ interface LexicalVectorStore extends VectorStore {
      */
     searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
 }
+/**
+ * An **optional** capability: swap all of a document's chunks safely under concurrent calls, so two
+ * writers can't leave a mix of versions behind. Postgres also makes the swap atomic for searches and
+ * crashes; Redis can't, and only guarantees the end state. {@link replaceDocumentChunks} falls back to
+ * `remove` plus `upsert` for the others.
+ */
+interface AtomicReplaceVectorStore extends VectorStore {
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
+}
+/** Replaces a document's chunks through the store's safe swap, where it has one. */
+declare function replaceDocumentChunks(store: VectorStore, documentId: string, records: VectorRecord[]): Promise<void>;
 /**
  * Does this store carry the optional {@link LexicalVectorStore} capability? Lets a consumer pick the
  * store-backed lexical leg when available and fall back to `KeywordRetriever` (or to dense-only)
@@ -287,10 +303,10 @@ declare function isLexicalVectorStore(store: VectorStore): store is LexicalVecto
  */
 declare class UnsafeRemovalError extends Error {
     /** Why the removal was refused. */
-    readonly reason: 'empty-filter' | 'unindexed-field';
+    readonly reason: 'empty-filter' | 'unindexed-field' | 'undefined-value';
     constructor(
     /** Why the removal was refused. */
-    reason: 'empty-filter' | 'unindexed-field', message: string);
+    reason: 'empty-filter' | 'unindexed-field' | 'undefined-value', message: string);
 }
 /** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */
 interface IndexedDocument {
@@ -562,6 +578,13 @@ interface PgVectorStoreOptions {
      * the chunk metadata) when two models share a width.
      */
     dimensions?: number | readonly number[];
+    /**
+     * The pgvector column type. `halfvec` stores each dimension in 2 bytes instead of 4, and its HNSW
+     * index accepts up to 4000 dimensions where `vector` stops at 2000 (so `text-embedding-3-large`'s
+     * 3072 needs it). Needs a single width, not a list. Only affects the DDL for a new table and the
+     * casts in statements: converting an existing table is a migration of yours. Default `vector`.
+     */
+    vectorType?: 'vector' | 'halfvec';
     /**
      * Allow chunks with no embedding (`embedding: []` on upsert is stored as `NULL`): index text first
      * and embed later, or keep full-text-only chunks when there is no embedding model at all. The
@@ -617,13 +640,14 @@ interface PgVectorStoreOptions {
  * Subclassing: every statement filters through {@link PgVectorStore.whereConditions}, so a subclass
  * can map an opaque filter onto its own columns (a tenant id, an ACL) in one place.
  */
-declare class PgVectorStore implements VectorStore {
+declare class PgVectorStore implements AtomicReplaceVectorStore {
     protected readonly client: PgClient;
     protected readonly table: string;
     /** The single width (fixed-dimension table), or `undefined` for a mixed-dimension table. */
     private readonly dimensions;
     /** The widths with a partial HNSW index, for a mixed-dimension table. */
     private readonly indexedDimensions;
+    private readonly vectorType;
     private readonly nullableEmbeddings;
     private readonly iterativeScan;
     private readonly efSearch;
@@ -645,6 +669,16 @@ declare class PgVectorStore implements VectorStore {
      * {@link PgVectorStoreOptions.nullableEmbeddings}).
      */
     upsert(records: VectorRecord[]): Promise<void>;
+    /**
+     * Swaps a document's chunks in one transaction, so a crash can't lose it and a search sees the old
+     * version or the new one. A client without `transaction` falls back to two statements.
+     *
+     * Concurrent swaps of one document take turns on an advisory lock. Without it the second `DELETE`
+     * can't see the rows the first just committed, so the first's tail survives next to the second's
+     * chunks, and overlapping writes can deadlock.
+     */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
+    private upsertWith;
     remove(documentId: string): Promise<void>;
     /**
      * Rewrite a document's metadata without re-embedding it. See {@link VectorStore.updateMetadata}
@@ -741,12 +775,6 @@ declare class PgLexicalVectorStore extends PgVectorStore implements LexicalVecto
     private tsvector;
 }
 
-/**
- * The minimal Redis surface {@link RedisVectorStore} needs: send a raw command and get the reply.
- * Both `node-redis` (`client.sendCommand(args)`) and `ioredis` (wrap `redis.call`) satisfy it — so
- * this package pulls in NO Redis driver (bring your own, like the other adapters). Requires the
- * RediSearch module (Redis Stack / Redis 8+).
- */
 interface RedisSearchClient {
     sendCommand(args: (string | Buffer)[]): Promise<unknown>;
 }
@@ -808,7 +836,7 @@ interface RedisVectorStoreOptions {
  * {@link LexicalVectorStore}: {@link RedisVectorStore.searchText} is BM25 over that same index —
  * the lexical half of hybrid search with no second index to build, feed, or invalidate.
  */
-declare class RedisVectorStore implements LexicalVectorStore {
+declare class RedisVectorStore implements LexicalVectorStore, AtomicReplaceVectorStore {
     private readonly client;
     private readonly index;
     private readonly prefix;
@@ -850,6 +878,18 @@ declare class RedisVectorStore implements LexicalVectorStore {
     private reconcileSchema;
     private createIndex;
     upsert(records: VectorRecord[]): Promise<void>;
+    /**
+     * Replaces a document's chunks, one writer at a time per document. Redis can't swap them in one step
+     * without scanning the keyspace inside a script, so a search may briefly see old and new chunks
+     * together, but concurrent calls can't leave them mixed. The new chunks go in before the old ones
+     * come out, so a crash leaves the document searchable and the next call repairs it.
+     */
+    replaceDocument(documentId: string, records: VectorRecord[]): Promise<void>;
+    /**
+     * A lease, so a crashed writer can't block the document forever. It is renewed while the work runs,
+     * which keeps a large document from outliving it.
+     */
+    private withDocumentLock;
     /**
      * Single-document deletion, by `SCAN … MATCH`.
      *
@@ -1394,6 +1434,11 @@ interface RetrievalToolOptions {
     description?: string;
     /** Passages per search. Default lets the retriever decide (typically 5). */
     topK?: number;
+    /**
+     * The access filter for this call, from the tool context — e.g.
+     * `(ctx) => ({ tenant: ctx.actor.tenantRef })`. Without it, every actor searches the same corpus.
+     */
+    filter?: (ctx: AiToolCtx) => Record<string, unknown> | undefined;
     /**
      * Retrieval telemetry (`aviary:rag:retrieval` — duration, chunk count, score distribution, store
      * and collection). **On by default**, because this tool is the once-per-retrieval seam in agentic
@@ -1427,6 +1472,23 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
+/** What one embedding call consumed: the whole batch, not per text. */
+interface EmbeddingUsage {
+    inputTokens: number;
+    /** The model the provider reported, needed to estimate a cost. */
+    modelId?: string;
+}
+interface EmbeddingResult {
+    vectors: number[][];
+    usage?: EmbeddingUsage;
+}
+/** An {@link EmbeddingProvider} that can also say what a call cost. `openAiEmbeddings` is one. */
+interface UsageReportingEmbeddingProvider extends EmbeddingProvider {
+    embedWithUsage(texts: string[]): Promise<EmbeddingResult>;
+}
+/** Calls `embedWithUsage` when the provider has it, otherwise `embed` with no usage. */
+declare function embedCountingUsage(provider: EmbeddingProvider, texts: string[]): Promise<EmbeddingResult>;
+
 /** A non-2xx answer (or a malformed one) from an embeddings or rerank endpoint. */
 declare class HttpModelError extends Error {
     /** HTTP status; `502` when the endpoint answered 2xx with a body that doesn't fit the contract. */
@@ -1497,7 +1559,7 @@ declare function isBatchTooLarge(error: unknown): boolean;
  * const local = openAiEmbeddings({ baseUrl: 'http://tei:8080/v1', model: 'BAAI/bge-m3' });
  * ```
  */
-declare function openAiEmbeddings(options: OpenAiEmbeddingsOptions): EmbeddingProvider;
+declare function openAiEmbeddings(options: OpenAiEmbeddingsOptions): UsageReportingEmbeddingProvider;
 
 interface HttpRerankerOptions {
     /**
@@ -1543,6 +1605,137 @@ declare class HttpReranker implements Reranker {
     rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
 }
 
+/** The metadata key separating models that share one store. Reserved: it always wins over yours. */
+declare const RAG_ENTITY_KEY = "ragEntity";
+/** What a scope value can be. Compared as strings, so `7` and `'7'` are the same scope everywhere. */
+type RagScopeValue = string | number;
+/** Maps a scope key to the function reading it from a row. `{}` declares a global corpus. */
+type RagScopeDefinition<Row> = Record<string, (row: Row) => RagScopeValue>;
+/** A required scope value was missing or malformed. Thrown before any embedding is paid for. */
+declare class RagScopeRequiredError extends Error {
+    readonly model: string;
+    readonly key: string;
+    constructor(model: string, key: string);
+}
+declare const ANY_OF: unique symbol;
+/** See {@link anyOf}. */
+interface RagAnyOf<Value> {
+    readonly [ANY_OF]: readonly Value[];
+}
+/**
+ * Search several scope values at once. An empty list matches nothing. It is a wrapper rather than a
+ * plain array so that an array arriving from a request can't widen a search by accident.
+ */
+declare function anyOf<Value extends RagScopeValue>(values: readonly Value[]): RagAnyOf<Value>;
+/** The scope a search must carry: every key of the definition, with the type its function returns. */
+type RagScopeOf<Scope> = {
+    [Key in keyof Scope]: Scope[Key] extends (row: never) => infer Value ? Value | RagAnyOf<Value> : never;
+};
+/** A `scope` is required unless the definition declared none. A `filter` can't name a scope key. */
+type RagSearchOptions<Scope> = {
+    topK?: number;
+    filter?: Record<string, unknown> & {
+        [Key in keyof Scope]?: never;
+    };
+} & (keyof Scope extends never ? {
+    scope?: undefined;
+} : {
+    scope: RagScopeOf<Scope>;
+});
+interface RagIndexDefinition<Row, Scope extends RagScopeDefinition<Row>> {
+    /** Namespaces document ids (`<name>:<id>`) and the {@link RAG_ENTITY_KEY} metadata. */
+    name: string;
+    id: (row: Row) => RagScopeValue;
+    /** The text to index. Blank removes the row's chunks. */
+    text: (row: Row) => string | null | undefined;
+    /** Required on purpose: a global corpus has to say `scope: {}`. */
+    scope: Scope;
+    /** Citation-facing origin of each chunk. */
+    source?: (row: Row) => string | null | undefined;
+    /** Extra chunk metadata. Can't override the scope. */
+    metadata?: (row: Row) => Record<string, unknown>;
+    chunk?: ChunkOptions;
+    /** Keep only the first N chunks: an upper bound on what one huge document can cost. */
+    maxChunks?: number;
+    minScore?: EmbeddingRetrieverOptions['minScore'];
+}
+interface RagIndexDeps {
+    store: VectorStore;
+    embedder: EmbeddingProvider;
+    /**
+     * Replaces the default dense retriever (hybrid, reranked). It must honour `options.filter`, which
+     * carries the scope. Embedding spend it does on its own doesn't reach `onUsage`.
+     */
+    retriever?: Retriever;
+    /** Embedding spend, indexing and searching alike. This package can't know who pays for it. */
+    onUsage?: (usage: EmbeddingUsage) => void | Promise<void>;
+}
+interface RagReconcileOptions<Scope> {
+    /** Compare only this part of the corpus. `liveIds` then only has to cover that part. */
+    scope?: Partial<{
+        [Key in keyof Scope]: Scope[Key] extends (row: never) => infer V ? V : never;
+    }>;
+    /** Report without removing anything. */
+    dryRun?: boolean;
+}
+interface RagReconcileResult {
+    /** Indexed document ids with no live row. Removed, unless `dryRun`. */
+    orphans: string[];
+    /** Live document ids with no chunks: never indexed, or blank. Nothing is embedded for them here. */
+    missing: string[];
+}
+interface RagToolOptions<Scope> {
+    name: string;
+    description?: string;
+    topK?: number;
+    /** From the tool context, never from the model's input. */
+    scope: (ctx: AiToolCtx) => RagScopeOf<Scope>;
+}
+/**
+ * The framework-free core behind `RagRepository`: one model's chunks in a shared store, with a scope
+ * that a search can't omit or override. It only composes what this package already has; cost, quota
+ * and access control stay in the app.
+ *
+ * Saving a row doesn't index it, because embedding is a slow, paid call. Call {@link RagIndex.index}
+ * from a job, or wherever the text is known to have changed.
+ */
+declare class RagIndex<Row, Scope extends RagScopeDefinition<Row>> {
+    private readonly definition;
+    private readonly deps;
+    private readonly embedder;
+    constructor(definition: RagIndexDefinition<Row, Scope>, deps: RagIndexDeps);
+    /** The id this row's chunks are stored under: `<name>:<id>`. */
+    documentId(id: RagScopeValue): string;
+    /** A `Retriever` locked to this scope, for `HybridRetriever`, `createRetrievalTool` and so on. */
+    scoped(scope: RagScopeOf<Scope>): Retriever;
+    search(query: string, options: RagSearchOptions<Scope>): Promise<Passage[]>;
+    /**
+     * Replaces the row's chunks and returns how many were written. Embeddings come first: if the
+     * provider fails, the previous chunks are still there. The swap is one transaction on Postgres. Redis
+     * adds the new chunks before dropping the old, so a search can briefly see both. On a store without
+     * `replaceDocument`, a crash mid-swap loses the document until the next `index`.
+     */
+    index(row: Row): Promise<number>;
+    /** Takes the id itself once the row is gone. */
+    remove(rowOrId: Row | RagScopeValue): Promise<void>;
+    /**
+     * Diffs the index against the ids that exist, and removes what no hook could: `ON DELETE CASCADE`,
+     * raw SQL, a crash after a commit. `liveIds` must be complete for the part being compared, because
+     * anything left out is removed. Use `dryRun` to look first.
+     */
+    reconcile(liveIds: Iterable<RagScopeValue> | AsyncIterable<RagScopeValue>, options?: RagReconcileOptions<Scope>): Promise<RagReconcileResult>;
+    /** A `search_*` tool whose scope comes from the context. Pass it to `provideAgentTool`. */
+    tool(options: RagToolOptions<Scope>): RetrievalTool;
+    private baseRetriever;
+    /** The filter a scope compiles to. Throws on anything but a usable value, before any paid call. */
+    private scopeFilter;
+}
+/**
+ * The fields a `RedisVectorStore` must declare in `filterableFields` to serve these scopes:
+ * RediSearch can only filter on a key declared up front.
+ */
+declare function ragFilterableFields(...scopeKeys: string[]): string[];
+
 /**
  * The data model of tree navigation retrieval: a hierarchical table of contents per long document
  * (PageIndex-style: sections with page ranges and summaries), built once at ingestion and read by an
@@ -2327,4 +2520,4 @@ interface NavigateDocumentTool {
  */
 declare function createNavigateDocumentTool(navigator: TreeNavigationRetriever, options?: NavigateDocumentToolOptions): NavigateDocumentTool;
 
-export { type BuildDocumentTreeOptions, type BuiltDocumentTree, type ChunkOptions, type ChunkRecord, DEFAULT_STOP_WORDS, type DescribesRetrieval, type DetectedHeading, type DocumentNavigation, type DocumentTree, type DocumentTreeHeader, type DocumentTreeInput, type DocumentTreeNode, type DocumentTreeStore, type DrizzleLike, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HttpModelError, HttpReranker, type HttpRerankerOptions, HybridRetriever, type HybridRetrieverOptions, type IndexDocumentTreeOptions, type IndexDocumentTreeResult, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryDocumentTreeStore, MemoryVectorStore, type MetadataPatch, type NavigateDocumentInput, type NavigateDocumentOutput, type NavigateDocumentTool, type NavigateDocumentToolOptions, type NavigateOptions, type NavigatedNode, type NavigationResult, type NavigationStep, type NodePgQueryable, type OpenAiChatTreeLlmOptions, type OpenAiEmbeddingsOptions, type PgClient, type PgClientSource, PgDocumentTreeStore, type PgDocumentTreeStoreOptions, type PgFullTextOptions, PgLexicalVectorStore, PgVectorStore, type PgVectorStoreOptions, type PostgresJsSql, RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_CHANNEL, RAG_RETRIEVAL_EVENT, type RagRetrievalEvent, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalDescriptor, type RetrievalTool, type RetrievalToolOptions, type RetrieverKind, type StoredChunk, type TreeBudget, TreeBudgetExceededError, type TreeBuildStats, type TreeHeading, type TreeLlm, type TreeLlmCache, type TreeLlmCandidate, type TreeLlmRequest, type TreeLlmResponse, type TreeLlmTask, TreeNavigationRetriever, type TreeNavigationRetrieverOptions, type TreeSection, type TreeStructureSource, type TreeSummarySource, type TreeUnit, TwoStageRetriever, type TwoStageRetrieverOptions, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, anyTermTsquery, applyMetadataPatch, buildDocumentTree, cachedTreeLlm, chunkDocuments, chunkIndexOf, chunkText, createNavigateDocumentTool, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, detectHeadings, documentIdOf, emitRagRetrieval, estimateTokens, hasSearchSyntax, indexDocumentTree, indexTree, ingestChunks, ingestDocuments, instrumentRetriever, isBatchTooLarge, isLexicalVectorStore, keywordTerms, keywordTreeLlm, openAiChatTreeLlm, openAiEmbeddings, parseJsonReply, spanText, stableHash, toPgClient, treeLlmFromModelProvider, walkTree };
+export { type AtomicReplaceVectorStore, type BuildDocumentTreeOptions, type BuiltDocumentTree, type ChunkOptions, type ChunkRecord, DEFAULT_STOP_WORDS, type DescribesRetrieval, type DetectedHeading, type DocumentNavigation, type DocumentTree, type DocumentTreeHeader, type DocumentTreeInput, type DocumentTreeNode, type DocumentTreeStore, type DrizzleLike, type EmbeddingResult, EmbeddingRetriever, type EmbeddingRetrieverOptions, type EmbeddingUsage, FilteredRetriever, HttpModelError, HttpReranker, type HttpRerankerOptions, HybridRetriever, type HybridRetrieverOptions, type IndexDocumentTreeOptions, type IndexDocumentTreeResult, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryDocumentTreeStore, MemoryVectorStore, type MetadataPatch, type NavigateDocumentInput, type NavigateDocumentOutput, type NavigateDocumentTool, type NavigateDocumentToolOptions, type NavigateOptions, type NavigatedNode, type NavigationResult, type NavigationStep, type NodePgQueryable, type OpenAiChatTreeLlmOptions, type OpenAiEmbeddingsOptions, type PgClient, type PgClientSource, PgDocumentTreeStore, type PgDocumentTreeStoreOptions, type PgFullTextOptions, PgLexicalVectorStore, PgVectorStore, type PgVectorStoreOptions, type PostgresJsSql, RAG_DIAGNOSTIC_LIB, RAG_ENTITY_KEY, RAG_RETRIEVAL_CHANNEL, RAG_RETRIEVAL_EVENT, type RagAnyOf, RagIndex, type RagIndexDefinition, type RagIndexDeps, type RagReconcileOptions, type RagReconcileResult, type RagRetrievalEvent, type RagScopeDefinition, type RagScopeOf, RagScopeRequiredError, type RagScopeValue, type RagSearchOptions, type RagToolOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalDescriptor, type RetrievalTool, type RetrievalToolOptions, type RetrieverKind, type StoredChunk, type TreeBudget, TreeBudgetExceededError, type TreeBuildStats, type TreeHeading, type TreeLlm, type TreeLlmCache, type TreeLlmCandidate, type TreeLlmRequest, type TreeLlmResponse, type TreeLlmTask, TreeNavigationRetriever, type TreeNavigationRetrieverOptions, type TreeSection, type TreeStructureSource, type TreeSummarySource, type TreeUnit, TwoStageRetriever, type TwoStageRetrieverOptions, UnsafeRemovalError, type UsageReportingEmbeddingProvider, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, anyOf, anyTermTsquery, applyMetadataPatch, buildDocumentTree, cachedTreeLlm, chunkDocuments, chunkIndexOf, chunkText, createNavigateDocumentTool, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, detectHeadings, documentIdOf, embedCountingUsage, emitRagRetrieval, estimateTokens, hasSearchSyntax, indexDocumentTree, indexTree, ingestChunks, ingestDocuments, instrumentRetriever, isBatchTooLarge, isLexicalVectorStore, keywordTerms, keywordTreeLlm, openAiChatTreeLlm, openAiEmbeddings, parseJsonReply, ragFilterableFields, replaceDocumentChunks, spanText, stableHash, toPgClient, treeLlmFromModelProvider, walkTree };