@dudousxd/nestjs-agent-rag 0.10.3 → 0.11.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler } from '@dudousxd/nestjs-agent-core';
+import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler, RerankOptions } from '@dudousxd/nestjs-agent-core';
 
 interface ChunkOptions {
     /** Target max characters per chunk. Default 800. */
@@ -433,56 +433,178 @@ declare class MemoryVectorStore implements VectorStore {
 }
 
 /**
- * The minimal Postgres surface {@link PgVectorStore} needs — adapt your own `pg` / `postgres.js`
- * client to it, so this package pulls in NO driver (bring your own, like the store adapters take an
- * ORM handle and the Redis transport takes a client). `query` runs parameterized SQL (`$1,$2,…`) and
- * resolves the result rows.
+ * The minimal Postgres surface {@link import('./pg-vector-store.js').PgVectorStore} needs — adapt your
+ * own `pg` / `postgres.js` client to it, so this package pulls in NO driver (bring your own, like the
+ * store adapters take an ORM handle and the Redis transport takes a client). `query` runs
+ * parameterized SQL (`$1,$2,…`) and resolves the result rows.
+ *
+ * `transaction` is optional. When present, the store uses it for the few reads that must share one
+ * connection with a `SET LOCAL` (pgvector's iterative index scan); without it those settings are
+ * simply not applied. You rarely write either by hand: pass a `pg` `Pool`, a Drizzle database or a
+ * `postgres.js` `sql` and {@link toPgClient} builds both.
  */
 interface PgClient {
     query<Row = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<Row[]>;
+    /** Run `work` inside one transaction on one connection; commit on success, roll back on throw. */
+    transaction?<T>(work: (tx: PgClient) => Promise<T>): Promise<T>;
+}
+/**
+ * A node-postgres `Pool`, `PoolClient` or `Client` — anything whose `query(text, values)` resolves a
+ * result with `rows`. Typed structurally so this package needs no `pg` import.
+ */
+interface NodePgQueryable {
+    query(text: string, values?: any[]): Promise<unknown>;
+}
+/** A `postgres.js` `sql` instance (or a transaction handle from `sql.begin`). */
+interface PostgresJsSql {
+    unsafe(query: string, params?: any[]): PromiseLike<unknown>;
+    begin?(...args: any[]): PromiseLike<unknown>;
+}
+/**
+ * A Drizzle database — `drizzle(pool)` for node-postgres or `drizzle(sql)` for postgres.js. Drizzle
+ * exposes the driver it wraps as `$client`, which is what the store talks to; this saves the
+ * `(db as unknown as { $client: Pool }).$client` cast at every call site.
+ */
+interface DrizzleLike {
+    $client: NodePgQueryable | PostgresJsSql;
+}
+/** Everything {@link toPgClient} (and so the `PgVectorStore` constructor) accepts. */
+type PgClientSource = PgClient | NodePgQueryable | PostgresJsSql | DrizzleLike;
+/**
+ * Normalize a Postgres handle into a {@link PgClient}:
+ *
+ * - a Drizzle database → its `$client`, then one of the below;
+ * - a `postgres.js` `sql` → `sql.unsafe(text, params)`, transactions via `sql.begin`;
+ * - a node-postgres `Pool` → `pool.query(...).rows`, transactions on a checked-out client
+ *   (`BEGIN`/`COMMIT`/`ROLLBACK`, then `release()`); a single `Client`/`PoolClient` runs its
+ *   transaction in place;
+ * - a hand-written {@link PgClient} (`query` resolving the rows array) passes through unchanged.
+ *
+ * Detection is structural and happens per call result for `query` (an array is taken as the rows, an
+ * object's `rows` otherwise), so a hand-written adapter keeps working exactly as before.
+ */
+declare function toPgClient(source: PgClientSource): PgClient;
+
+/** Where the lexical leg of a {@link PgLexicalVectorStore} reads its `tsvector` from. */
+interface PgFullTextOptions {
+    /**
+     * Text-search configuration (`simple`, `english`, `portuguese`, …). Default `simple` — no stemming
+     * or stop words, so it works for any language and matches exact terms, which is what the lexical
+     * leg of a hybrid search is for. Must be the same configuration the index was built with, or
+     * Postgres cannot use the index and scans the table (still correct, just slow).
+     */
+    config?: string;
+    /**
+     * A `tsvector` column you maintain yourself (typically `GENERATED ALWAYS AS (…) STORED` in a
+     * migration, e.g. weighting a title above the body), with its own GIN index. When omitted the
+     * store searches the expression `to_tsvector(config, text)`, and `ensureSchema` creates a GIN
+     * expression index over exactly that.
+     */
+    column?: string;
+    /**
+     * When the question matches nothing as a whole (`websearch_to_tsquery`: every word must appear),
+     * retry with any word (`w1 | w2 | …`, at most 24 distinct words) so a long natural-language
+     * question still finds the chunks sharing its rare terms. Default `true`.
+     */
+    anyTermFallback?: boolean;
 }
 interface PgVectorStoreOptions {
     /** Table name. Default `agent_rag_chunks`. */
     table?: string;
-    /** Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536. */
-    dimensions?: number;
+    /**
+     * Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536.
+     *
+     * Pass a **list** to let several models' vectors share one table (mixed dimensions, e.g. while
+     * migrating from a 768-wide local model to a 1536-wide hosted one): the column becomes an untyped
+     * `vector`, `ensureSchema` creates one *partial* HNSW index per listed width
+     * (`((embedding::vector(n))) … WHERE vector_dims(embedding) = n`), and `search` only compares the
+     * query against vectors of its own width, through that width's index. A query whose width is not
+     * listed is still answered — exactly, by a sequential scan. Filter on the model as well (put it in
+     * the chunk metadata) when two models share a width.
+     */
+    dimensions?: number | readonly number[];
+    /**
+     * 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
+     * vector leg skips them; the lexical leg of {@link PgLexicalVectorStore} still finds them. Default
+     * `false` — the column stays `NOT NULL`. Only affects the DDL `ensureSchema` emits for a new table.
+     */
+    nullableEmbeddings?: boolean;
+    /**
+     * pgvector ≥ 0.8 iterative index scans for `search`: keep walking the HNSW graph until enough rows
+     * pass the metadata filter, instead of returning fewer than `topK` when a selective filter (one
+     * tenant of many) rejects most of the candidates the index produced. Applied with `SET LOCAL`, so
+     * it needs a client with a `transaction` (a `pg` Pool, Drizzle or postgres.js all have one); it is
+     * silently skipped on an older pgvector or a client without transactions. Default off.
+     */
+    iterativeScan?: 'strict_order' | 'relaxed_order';
+    /** `hnsw.ef_search` for `search` (candidate list size; pgvector's default is 40). Needs a `transaction`. */
+    efSearch?: number;
+    /**
+     * Rows per multi-row `INSERT … ON CONFLICT` statement in `upsert`. Default 100. Duplicate ids in
+     * one `upsert` call collapse to the last occurrence (as the old row-by-row loop left them).
+     */
+    upsertBatchSize?: number;
 }
 /**
  * A pgvector-backed {@link VectorStore} — the production reference adapter. Cosine distance via the
  * `<=>` operator over an HNSW index; metadata in a `jsonb` column filtered with `@>`. Call
- * {@link PgVectorStore.ensureSchema} once at boot to create the extension, table, and index.
+ * {@link PgVectorStore.ensureSchema} once at boot to create the extension, table, and index — or copy
+ * {@link PgVectorStore.schemaStatements} into a migration.
+ *
+ * The constructor takes a `pg` `Pool`, a Drizzle database, a `postgres.js` `sql`, or a hand-written
+ * {@link PgClient} (see {@link toPgClient}).
  *
- * This store does **not** implement the optional
- * {@link import('./vector-store.js').LexicalVectorStore} capability, unlike
- * {@link import('./redis-vector-store.js').RedisVectorStore}. That is a deliberate omission, not an
- * oversight: RediSearch already indexes the chunk text (the schema declares it `TEXT`), so BM25 is
- * free there, whereas the table below indexes nothing lexically — `text` is a plain column with no
- * `tsvector` and no GIN index. Adding one is not a transparent upgrade:
+ * This class does **not** implement the optional
+ * {@link import('./vector-store.js').LexicalVectorStore} capability; {@link PgLexicalVectorStore}
+ * (below) does. The split is deliberate: lexical search over Postgres needs a GIN index, and a
+ * store that silently gained `searchText` on upgrade would be picked up by every
+ * `isLexicalVectorStore(store)` check and start sequentially scanning an unindexed chunks table:
  *
- * - it is new DDL in `ensureSchema`, and `CREATE INDEX` (non-concurrently, as this method must, since
+ * - it is new DDL, and `CREATE INDEX` (non-concurrently, as `ensureSchema` must, since
  *   `CONCURRENTLY` cannot run in a transaction) takes a write lock on an already-populated chunks
  *   table — a boot-time stall proportional to corpus size for every existing deployment;
  * - it forces a text-search-configuration choice (`english` vs `simple` vs …) that must match between
  *   the index expression and every query, or Postgres silently ignores the index and sequentially
  *   scans the corpus — a failure mode that stays *correct* while quietly getting slower with scale.
  *
- * Both want a migration a consumer runs and observes, not a side effect of upgrading the library. The
- * capability interface is open, so a `PgLexicalVectorStore` (or an option here, gated on an
- * explicitly-created index) can be added later without changing anything else.
+ * So lexical search is something you opt into by constructing the subclass, with the index created
+ * by a migration you run and watch (or by `ensureSchema`, on a table small enough not to care).
  *
  * The enumeration and bulk-deletion methods {@link VectorStore} requires need nothing new here,
  * unlike the lexical capability above: enumeration and bulk deletion are `DISTINCT`, `= ANY($1)`, `DELETE … WHERE`
  * and `count(*)` over the table and index that already exist. No DDL, no boot-time lock, no migration.
+ *
+ * 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 {
-    private readonly client;
-    private readonly table;
+    protected readonly client: PgClient;
+    protected readonly table: string;
+    /** The single width (fixed-dimension table), or `undefined` for a mixed-dimension table. */
     private readonly dimensions;
-    constructor(client: PgClient, options?: PgVectorStoreOptions);
+    /** The widths with a partial HNSW index, for a mixed-dimension table. */
+    private readonly indexedDimensions;
+    private readonly nullableEmbeddings;
+    private readonly iterativeScan;
+    private readonly efSearch;
+    private readonly upsertBatchSize;
+    private iterativeScanSupport;
+    constructor(client: PgClientSource, options?: PgVectorStoreOptions);
     /** Telemetry self-description — the table is the namespace a retrieval was served from. */
     describeRetrieval(): RetrievalDescriptor;
-    /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */
+    /**
+     * The idempotent DDL {@link PgVectorStore.ensureSchema} runs, in order — for a migration instead
+     * of a boot-time side effect. On a populated table, run the index statements `CONCURRENTLY` there.
+     */
+    schemaStatements(): string[];
+    /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index(es). */
     ensureSchema(): Promise<void>;
+    /**
+     * Multi-row `INSERT … ON CONFLICT (id) DO UPDATE`, {@link PgVectorStoreOptions.upsertBatchSize}
+     * rows per statement. An empty `embedding` is written as `NULL` (see
+     * {@link PgVectorStoreOptions.nullableEmbeddings}).
+     */
     upsert(records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     /**
@@ -523,7 +645,51 @@ declare class PgVectorStore implements VectorStore {
      */
     removeWhere(filter: Record<string, unknown>): Promise<number>;
     countChunks(filter?: Record<string, unknown>): Promise<number>;
+    /**
+     * Cosine similarity, nearest first. On a mixed-dimension table only vectors as wide as the query
+     * are compared (through that width's partial index when it has one); chunks without an embedding
+     * are never returned.
+     */
     search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+    /**
+     * The SQL conditions (ANDed) a metadata `filter` compiles to, appending their bindings to `params`
+     * (placeholders are numbered after what `params` already holds). Every statement that takes a
+     * filter goes through here, so a subclass that maps the filter onto its own columns — a tenant id,
+     * an access list — overrides this one method. Return `['false']` to deny.
+     */
+    protected whereConditions(filter: Record<string, unknown> | undefined, params: unknown[]): string[];
+    private where;
+    /** Run a read with the configured HNSW settings `SET LOCAL` in one transaction, when possible. */
+    private withSearchSettings;
+    /** `hnsw.iterative_scan` exists from pgvector 0.8.0; setting it on an older one is an error. */
+    private supportsIterativeScan;
+}
+/**
+ * {@link PgVectorStore} plus Postgres full-text search: a {@link LexicalVectorStore}, so
+ * `LexicalRetriever` and `HybridRetriever` work on Postgres exactly as on RediSearch — the dense leg
+ * over pgvector, the lexical leg over a `tsvector`, both on the same rows and ids.
+ *
+ * Ranking is `ts_rank_cd` (cover density). The query is parsed with `websearch_to_tsquery` (quoted
+ * phrases, `-exclusions`, `or`), which requires every word; when that matches nothing it retries
+ * with any word (see {@link PgFullTextOptions.anyTermFallback}).
+ *
+ * The `tsvector` is either a column you own ({@link PgFullTextOptions.column}) or the expression
+ * `to_tsvector(config, text)`, for which {@link PgVectorStore.schemaStatements} adds a GIN
+ * expression index. See {@link PgVectorStore} for why that index belongs in a migration on a
+ * populated table.
+ */
+declare class PgLexicalVectorStore extends PgVectorStore implements LexicalVectorStore {
+    private readonly tsConfig;
+    private readonly tsColumn;
+    private readonly anyTermFallback;
+    constructor(client: PgClientSource, options?: PgVectorStoreOptions & {
+        fullText?: PgFullTextOptions;
+    });
+    schemaStatements(): string[];
+    searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
+    private runTextSearch;
+    /** Must be character-for-character the index expression, or the planner won't use the index. */
+    private tsvector;
 }
 
 /**
@@ -1212,4 +1378,102 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, type DescribesRetrieval, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, 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, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, documentIdOf, emitRagRetrieval, ingestChunks, ingestDocuments, instrumentRetriever, isLexicalVectorStore };
+/** 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. */
+    readonly status: number;
+    constructor(
+    /** HTTP status; `502` when the endpoint answered 2xx with a body that doesn't fit the contract. */
+    status: number, message: string);
+}
+interface OpenAiEmbeddingsOptions {
+    /** The embedding model id, sent as `model`. */
+    model: string;
+    /**
+     * Base URL up to and including `/v1` — the client posts to `<baseUrl>/embeddings`. Default
+     * `https://api.openai.com/v1`. Point it at any OpenAI-compatible server: Azure/OpenRouter/an LLM
+     * gateway, Ollama (`http://localhost:11434/v1`), Hugging Face TEI, vLLM, LocalAI, LM Studio…
+     */
+    baseUrl?: string;
+    /** Sent as `Authorization: Bearer <apiKey>` when set. Local servers usually need none. */
+    apiKey?: string;
+    /** Output width for models that support shortening (`text-embedding-3-*`), sent as `dimensions`. */
+    dimensions?: number;
+    /** Inputs per request. Default 64. */
+    batchSize?: number;
+    /**
+     * Inputs longer than this many characters are truncated before sending, so one oversized chunk
+     * doesn't fail a whole batch on the model's context limit. Default 24 000 (≈ 6–8k tokens); set
+     * `Infinity` to send inputs as they are.
+     */
+    maxInputChars?: number;
+    /** Extra request headers (an org/project id, a gateway's attribution header). */
+    headers?: Record<string, string>;
+    /** Per-request timeout. Default 120 000 ms. */
+    timeoutMs?: number;
+    /** Called with the provider-reported token count of every request — for cost accounting. */
+    onUsage?: (tokens: number) => void;
+    /** `fetch` to use. Default the global one. */
+    fetch?: typeof fetch;
+}
+/**
+ * An {@link EmbeddingProvider} over any OpenAI-compatible `POST /v1/embeddings` endpoint, with no SDK
+ * dependency: OpenAI itself, or a gateway/local server speaking the same protocol (TEI, Ollama,
+ * vLLM, LocalAI…). For a Vercel AI SDK model use `aiSdkEmbedding` from `-ai-sdk` instead.
+ *
+ * Batches by {@link OpenAiEmbeddingsOptions.batchSize}, restores input order from each item's
+ * `index`, and fails loudly (an {@link HttpModelError}) on a non-2xx answer or a vector count that
+ * doesn't match the inputs. Empty strings are sent as a single space, since OpenAI rejects them.
+ *
+ * ```ts
+ * const embedder = openAiEmbeddings({ model: 'text-embedding-3-small', apiKey: process.env.OPENAI_API_KEY });
+ * const local = openAiEmbeddings({ baseUrl: 'http://tei:8080/v1', model: 'BAAI/bge-m3' });
+ * ```
+ */
+declare function openAiEmbeddings(options: OpenAiEmbeddingsOptions): EmbeddingProvider;
+
+interface HttpRerankerOptions {
+    /**
+     * The full rerank endpoint: `https://api.cohere.com/v2/rerank`, `https://api.jina.ai/v1/rerank`,
+     * `https://api.voyageai.com/v1/rerank`, or a Hugging Face TEI / Infinity / vLLM server's `/rerank`.
+     */
+    url: string;
+    /** Model id, sent as `model` (hosted APIs require it; TEI serves one model and ignores it). */
+    model?: string;
+    /** Sent as `Authorization: Bearer <apiKey>` when set. */
+    apiKey?: string;
+    /**
+     * Request body dialect. `cohere` (Cohere, Jina, Voyage, Infinity, vLLM): `{ query, documents,
+     * top_n }`. `tei`: `{ query, texts }`. Default `auto`, which sends `documents` **and** `texts` so
+     * one config works against both families. Responses are read in every dialect regardless.
+     */
+    format?: 'auto' | 'cohere' | 'tei';
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+    /** Per-request timeout. Default 30 000 ms. */
+    timeoutMs?: number;
+    /** `fetch` to use. Default the global one. */
+    fetch?: typeof fetch;
+}
+/**
+ * A cross-encoder {@link Reranker} behind an HTTP `/rerank` endpoint — the Cohere-style contract
+ * most providers and self-hosted servers share. Compose it with `RerankingRetriever`:
+ *
+ * ```ts
+ * const reranker = new HttpReranker({ url: 'https://api.cohere.com/v2/rerank', model: 'rerank-v3.5', apiKey });
+ * const retriever = new RerankingRetriever(hybrid, reranker, { fetchTopK: 30 });
+ * ```
+ *
+ * Reads `results: [{ index, relevance_score }]` (Cohere, Jina), `data: [{ index, relevance_score }]`
+ * (Voyage) and a bare `[{ index, score }]` (TEI). Each passage keeps its fields and takes the new
+ * score; the list is re-sorted and cut to `topK`. Indices the server invents are ignored.
+ */
+declare class HttpReranker implements Reranker {
+    private readonly options;
+    private readonly format;
+    private readonly doFetch;
+    constructor(options: HttpRerankerOptions);
+    rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
+}
+
+export { type ChunkOptions, type ChunkRecord, type DescribesRetrieval, type DrizzleLike, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HttpModelError, HttpReranker, type HttpRerankerOptions, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type NodePgQueryable, type OpenAiEmbeddingsOptions, type PgClient, type PgClientSource, 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, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, documentIdOf, emitRagRetrieval, ingestChunks, ingestDocuments, instrumentRetriever, isLexicalVectorStore, openAiEmbeddings, toPgClient };