@dudousxd/nestjs-agent-rag 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -54,6 +54,37 @@ interface VectorStore {
      */
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
 }
+/**
+ * An **optional** capability a {@link VectorStore} may also implement: full-text (lexical) search
+ * over the chunk text it already stores, using the backing engine's own keyword index — RediSearch's
+ * BM25 over the `TEXT` field, say. Its point is the multi-process deployment: when ingestion runs on
+ * a worker and search runs on an API pod, the API process never sees the chunks, so the in-process
+ * {@link import('./keyword-retriever.js').KeywordRetriever} has nothing to index. A store that
+ * implements this needs no second index, no corpus in JS heap, and no refresh window — a chunk is
+ * lexically findable the moment it is upserted.
+ *
+ * Wrap it as a core `Retriever` with {@link import('./lexical-retriever.js').LexicalRetriever}.
+ *
+ * Implementations MUST apply `options.filter` with exactly the same semantics as
+ * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is
+ * routinely an access-control boundary, not a hint.
+ */
+interface LexicalVectorStore extends VectorStore {
+    /**
+     * Rank stored chunks against a natural-language `query` by keyword relevance. `options.filter`
+     * narrows exactly as in {@link VectorStore.search}. The returned `score` is the engine's own
+     * relevance score (BM25), which shares no scale with `search`'s cosine similarity — fuse the two
+     * with {@link import('./hybrid-retriever.js').HybridRetriever}, whose RRF is rank-based and so
+     * needs no common scale.
+     */
+    searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
+}
+/**
+ * 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)
+ * when it is not, without knowing which adapter it was handed.
+ */
+declare function isLexicalVectorStore(store: VectorStore): store is LexicalVectorStore;
 /** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */
 interface IndexedDocument {
     id: string;
@@ -93,6 +124,24 @@ interface PgVectorStoreOptions {
  * 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.
+ *
+ * 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:
+ *
+ * - it is new DDL in `ensureSchema`, and `CREATE INDEX` (non-concurrently, as this method 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.
  */
 declare class PgVectorStore implements VectorStore {
     private readonly client;
@@ -116,6 +165,35 @@ declare class PgVectorStore implements VectorStore {
 interface RedisSearchClient {
     sendCommand(args: (string | Buffer)[]): Promise<unknown>;
 }
+/**
+ * The index that already exists in Redis contradicts this store's configuration in a way that cannot
+ * be repaired in place. Thrown by {@link RedisVectorStore.ensureSchema} — which would otherwise have
+ * returned happily and left every subsequent query quietly wrong.
+ *
+ * The canonical case is a changed embedding width (a model swap, 1024 → 1536): RediSearch fixes a
+ * vector field's `DIM` at `FT.CREATE`, and every vector already stored was produced by the OLD model,
+ * so there is no in-place fix — the index has to be dropped and the corpus re-embedded. That is
+ * destructive and belongs to the host, never to a boot-time `ensureSchema`.
+ */
+declare class RedisVectorSchemaMismatchError extends Error {
+    /** The RediSearch index that was inspected. */
+    readonly index: string;
+    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */
+    readonly field: string;
+    /** What this store is configured for. */
+    readonly expected: string;
+    /** What `FT.INFO` reports the live index has. */
+    readonly actual: string;
+    constructor(
+    /** The RediSearch index that was inspected. */
+    index: string, 
+    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */
+    field: string, 
+    /** What this store is configured for. */
+    expected: string, 
+    /** What `FT.INFO` reports the live index has. */
+    actual: string, remedy: string);
+}
 interface RedisVectorStoreOptions {
     /** RediSearch index name. Default `agent_rag_idx`. */
     index?: string;
@@ -128,26 +206,74 @@ interface RedisVectorStoreOptions {
      * front, so only keys listed here can be passed in `search`'s `filter`. Default none.
      */
     filterableFields?: string[];
+    /**
+     * RediSearch scorer used by {@link RedisVectorStore.searchText}. Default `BM25` — the standard
+     * lexical ranking, and the same family the in-process `KeywordRetriever` implements. Override for
+     * a server that names it differently (`BM25STD` on newer builds) or to pick `TFIDF`/`DISMAX`.
+     */
+    lexicalScorer?: string;
 }
 /**
  * A RediSearch-backed {@link VectorStore} — HNSW + cosine over Redis, the ecosystem-native option
  * for anyone already running Redis (see `-transport-redis`). Chunks are hashes under `prefix`, the
  * embedding a FLOAT32 vector field; `search` is a KNN query. Call {@link RedisVectorStore.ensureSchema}
  * once at boot to create the index.
+ *
+ * The chunk text is declared as a RediSearch `TEXT` field, so this store also satisfies
+ * {@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 VectorStore {
+declare class RedisVectorStore implements LexicalVectorStore {
     private readonly client;
     private readonly index;
     private readonly prefix;
     private readonly dimensions;
     private readonly filterableFields;
+    private readonly lexicalScorer;
     constructor(client: RedisSearchClient, options?: RedisVectorStoreOptions);
-    /** Idempotent: create the HNSW/cosine index if `FT.INFO` says it doesn't exist yet. */
+    /**
+     * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —
+     * and if it DOES exist, compare what's there against this store's configuration instead of
+     * assuming they agree. An index that outlives a config change is the normal case (schemas live in
+     * Redis, config lives in a redeployed process), and the two failure modes it produces are both
+     * invisible at runtime: a `filterableFields` entry added later has no `meta_*` TAG, so every search
+     * filtering on it matches *nothing*; a changed `dimensions` leaves the index on the old width, so
+     * writes are rejected or KNN ranks garbage. Neither raises anything on its own.
+     *
+     * The two are repaired differently, because only one of them CAN be repaired:
+     *
+     * - **A missing filterable TAG is additive** → `FT.ALTER … SCHEMA ADD`. Nothing that already works
+     *   changes, so doing it automatically is safe. Note the chunks written *before* the alter carry no
+     *   `meta_*` hash field at all (`upsert` only writes the fields configured at the time), so they
+     *   only become filterable on that key once they're re-ingested — the schema is repaired here, the
+     *   backfill is the host's call.
+     * - **A dimension (or field-type) change is not repairable** → {@link RedisVectorSchemaMismatchError}.
+     *   It needs a drop + full reindex, which would destroy the host's corpus; failing loudly at boot is
+     *   the only honest option.
+     *
+     * If `FT.INFO` comes back in a shape this parser doesn't recognise, no drift is inferred — an
+     * unreadable reply must not be turned into a false alarm that blocks a boot.
+     */
     ensureSchema(): Promise<void>;
+    /** Repair what can be repaired in place; throw on what can't. */
+    private reconcileSchema;
+    private createIndex;
     upsert(records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
     search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+    /**
+     * Lexical (BM25) search over the same index `search` uses — the {@link LexicalVectorStore} half of
+     * hybrid retrieval, served by RediSearch's own keyword index rather than an in-process copy of the
+     * corpus. `options.filter` is ANDed onto the text clause with the identical TAG semantics as
+     * `search` (array = OR, empty array = deny), so a lexical hit can never escape a filter a vector
+     * hit would have respected.
+     *
+     * A query with no searchable terms — empty, whitespace, or pure punctuation — returns `[]`. That is
+     * deliberate: RediSearch's `*` would match the entire corpus, which is the opposite of what a
+     * relevance query with nothing to be relevant to should do.
+     */
+    searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
 }
 
 /**
@@ -205,6 +331,11 @@ interface KeywordRetrieverOptions {
  * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
  * line up and `HybridRetriever` can fuse the two rankings. Full BM25: idf, term-frequency saturation
  * (`k1`), and document-length normalization (`b`).
+ *
+ * Because it holds its OWN copy of each chunk's text, it needs the same delete-sync as the vector
+ * store: whenever you call {@link import('./vector-store.js').VectorStore.remove}, call
+ * {@link KeywordRetriever.remove} with the same document id. Skipping it leaves the document
+ * lexically retrievable — `retrieve` would keep returning the removed passage's full text.
  */
 declare class KeywordRetriever implements Retriever {
     private readonly docs;
@@ -213,9 +344,51 @@ declare class KeywordRetriever implements Retriever {
     private readonly k1;
     private readonly b;
     constructor(options?: KeywordRetrieverOptions);
+    /** How many chunks are currently indexed. */
+    get size(): number;
     /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
     add(records: ChunkRecord[]): void;
-    private remove;
+    /**
+     * Forget a source document — every chunk whose id is `${documentId}` or `${documentId}#<n>`, the
+     * same id scheme (and the same {@link documentIdOf} collapse) the vector stores use for their
+     * `remove`. The keyword half of a hybrid index keeps its own copy of the chunk text, so a document
+     * dropped from the vector store stays fully retrievable here until this is called. Unknown ids are
+     * a no-op.
+     */
+    remove(documentId: string): void;
+    /** Drop every indexed chunk, resetting the corpus statistics with it. */
+    clear(): void;
+    /** Drop ONE chunk by its exact id, decrementing the corpus statistics it contributed. */
+    private removeChunk;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+
+/**
+ * The keyword half of hybrid search, served by the store's own full-text index — the mirror of
+ * {@link import('./embedding-retriever.js').EmbeddingRetriever}, which serves the dense half. It
+ * holds no state: every query goes to the store, so any process that can reach the store can run
+ * lexical search, whether or not it did the ingestion.
+ *
+ * Compose it exactly like the dense leg:
+ *
+ * ```ts
+ * const retriever = new HybridRetriever([
+ *   new EmbeddingRetriever(embedder, store),
+ *   new LexicalRetriever(store),
+ * ]);
+ * ```
+ *
+ * Both legs read the same chunks from the same index, so their ids line up by construction and
+ * `HybridRetriever`'s RRF fuses them without either side needing a score on a common scale.
+ *
+ * Prefer this over {@link import('./keyword-retriever.js').KeywordRetriever} whenever the store
+ * supports it (see {@link import('./vector-store.js').isLexicalVectorStore}) and ingestion and
+ * search can run in different processes; `KeywordRetriever` remains the answer for `MemoryVectorStore`
+ * and single-process deployments.
+ */
+declare class LexicalRetriever implements Retriever {
+    private readonly store;
+    constructor(store: LexicalVectorStore);
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -297,4 +470,4 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, MemoryVectorStore, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type VectorRecord, type VectorSearchOptions, type VectorStore, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments };
+export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, MemoryVectorStore, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type VectorRecord, type VectorSearchOptions, type VectorStore, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };

package/dist/index.d.ts

@@ -54,6 +54,37 @@ interface VectorStore {
      */
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
 }
+/**
+ * An **optional** capability a {@link VectorStore} may also implement: full-text (lexical) search
+ * over the chunk text it already stores, using the backing engine's own keyword index — RediSearch's
+ * BM25 over the `TEXT` field, say. Its point is the multi-process deployment: when ingestion runs on
+ * a worker and search runs on an API pod, the API process never sees the chunks, so the in-process
+ * {@link import('./keyword-retriever.js').KeywordRetriever} has nothing to index. A store that
+ * implements this needs no second index, no corpus in JS heap, and no refresh window — a chunk is
+ * lexically findable the moment it is upserted.
+ *
+ * Wrap it as a core `Retriever` with {@link import('./lexical-retriever.js').LexicalRetriever}.
+ *
+ * Implementations MUST apply `options.filter` with exactly the same semantics as
+ * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is
+ * routinely an access-control boundary, not a hint.
+ */
+interface LexicalVectorStore extends VectorStore {
+    /**
+     * Rank stored chunks against a natural-language `query` by keyword relevance. `options.filter`
+     * narrows exactly as in {@link VectorStore.search}. The returned `score` is the engine's own
+     * relevance score (BM25), which shares no scale with `search`'s cosine similarity — fuse the two
+     * with {@link import('./hybrid-retriever.js').HybridRetriever}, whose RRF is rank-based and so
+     * needs no common scale.
+     */
+    searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
+}
+/**
+ * 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)
+ * when it is not, without knowing which adapter it was handed.
+ */
+declare function isLexicalVectorStore(store: VectorStore): store is LexicalVectorStore;
 /** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */
 interface IndexedDocument {
     id: string;
@@ -93,6 +124,24 @@ interface PgVectorStoreOptions {
  * 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.
+ *
+ * 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:
+ *
+ * - it is new DDL in `ensureSchema`, and `CREATE INDEX` (non-concurrently, as this method 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.
  */
 declare class PgVectorStore implements VectorStore {
     private readonly client;
@@ -116,6 +165,35 @@ declare class PgVectorStore implements VectorStore {
 interface RedisSearchClient {
     sendCommand(args: (string | Buffer)[]): Promise<unknown>;
 }
+/**
+ * The index that already exists in Redis contradicts this store's configuration in a way that cannot
+ * be repaired in place. Thrown by {@link RedisVectorStore.ensureSchema} — which would otherwise have
+ * returned happily and left every subsequent query quietly wrong.
+ *
+ * The canonical case is a changed embedding width (a model swap, 1024 → 1536): RediSearch fixes a
+ * vector field's `DIM` at `FT.CREATE`, and every vector already stored was produced by the OLD model,
+ * so there is no in-place fix — the index has to be dropped and the corpus re-embedded. That is
+ * destructive and belongs to the host, never to a boot-time `ensureSchema`.
+ */
+declare class RedisVectorSchemaMismatchError extends Error {
+    /** The RediSearch index that was inspected. */
+    readonly index: string;
+    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */
+    readonly field: string;
+    /** What this store is configured for. */
+    readonly expected: string;
+    /** What `FT.INFO` reports the live index has. */
+    readonly actual: string;
+    constructor(
+    /** The RediSearch index that was inspected. */
+    index: string, 
+    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */
+    field: string, 
+    /** What this store is configured for. */
+    expected: string, 
+    /** What `FT.INFO` reports the live index has. */
+    actual: string, remedy: string);
+}
 interface RedisVectorStoreOptions {
     /** RediSearch index name. Default `agent_rag_idx`. */
     index?: string;
@@ -128,26 +206,74 @@ interface RedisVectorStoreOptions {
      * front, so only keys listed here can be passed in `search`'s `filter`. Default none.
      */
     filterableFields?: string[];
+    /**
+     * RediSearch scorer used by {@link RedisVectorStore.searchText}. Default `BM25` — the standard
+     * lexical ranking, and the same family the in-process `KeywordRetriever` implements. Override for
+     * a server that names it differently (`BM25STD` on newer builds) or to pick `TFIDF`/`DISMAX`.
+     */
+    lexicalScorer?: string;
 }
 /**
  * A RediSearch-backed {@link VectorStore} — HNSW + cosine over Redis, the ecosystem-native option
  * for anyone already running Redis (see `-transport-redis`). Chunks are hashes under `prefix`, the
  * embedding a FLOAT32 vector field; `search` is a KNN query. Call {@link RedisVectorStore.ensureSchema}
  * once at boot to create the index.
+ *
+ * The chunk text is declared as a RediSearch `TEXT` field, so this store also satisfies
+ * {@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 VectorStore {
+declare class RedisVectorStore implements LexicalVectorStore {
     private readonly client;
     private readonly index;
     private readonly prefix;
     private readonly dimensions;
     private readonly filterableFields;
+    private readonly lexicalScorer;
     constructor(client: RedisSearchClient, options?: RedisVectorStoreOptions);
-    /** Idempotent: create the HNSW/cosine index if `FT.INFO` says it doesn't exist yet. */
+    /**
+     * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —
+     * and if it DOES exist, compare what's there against this store's configuration instead of
+     * assuming they agree. An index that outlives a config change is the normal case (schemas live in
+     * Redis, config lives in a redeployed process), and the two failure modes it produces are both
+     * invisible at runtime: a `filterableFields` entry added later has no `meta_*` TAG, so every search
+     * filtering on it matches *nothing*; a changed `dimensions` leaves the index on the old width, so
+     * writes are rejected or KNN ranks garbage. Neither raises anything on its own.
+     *
+     * The two are repaired differently, because only one of them CAN be repaired:
+     *
+     * - **A missing filterable TAG is additive** → `FT.ALTER … SCHEMA ADD`. Nothing that already works
+     *   changes, so doing it automatically is safe. Note the chunks written *before* the alter carry no
+     *   `meta_*` hash field at all (`upsert` only writes the fields configured at the time), so they
+     *   only become filterable on that key once they're re-ingested — the schema is repaired here, the
+     *   backfill is the host's call.
+     * - **A dimension (or field-type) change is not repairable** → {@link RedisVectorSchemaMismatchError}.
+     *   It needs a drop + full reindex, which would destroy the host's corpus; failing loudly at boot is
+     *   the only honest option.
+     *
+     * If `FT.INFO` comes back in a shape this parser doesn't recognise, no drift is inferred — an
+     * unreadable reply must not be turned into a false alarm that blocks a boot.
+     */
     ensureSchema(): Promise<void>;
+    /** Repair what can be repaired in place; throw on what can't. */
+    private reconcileSchema;
+    private createIndex;
     upsert(records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
     search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+    /**
+     * Lexical (BM25) search over the same index `search` uses — the {@link LexicalVectorStore} half of
+     * hybrid retrieval, served by RediSearch's own keyword index rather than an in-process copy of the
+     * corpus. `options.filter` is ANDed onto the text clause with the identical TAG semantics as
+     * `search` (array = OR, empty array = deny), so a lexical hit can never escape a filter a vector
+     * hit would have respected.
+     *
+     * A query with no searchable terms — empty, whitespace, or pure punctuation — returns `[]`. That is
+     * deliberate: RediSearch's `*` would match the entire corpus, which is the opposite of what a
+     * relevance query with nothing to be relevant to should do.
+     */
+    searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;
 }
 
 /**
@@ -205,6 +331,11 @@ interface KeywordRetrieverOptions {
  * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
  * line up and `HybridRetriever` can fuse the two rankings. Full BM25: idf, term-frequency saturation
  * (`k1`), and document-length normalization (`b`).
+ *
+ * Because it holds its OWN copy of each chunk's text, it needs the same delete-sync as the vector
+ * store: whenever you call {@link import('./vector-store.js').VectorStore.remove}, call
+ * {@link KeywordRetriever.remove} with the same document id. Skipping it leaves the document
+ * lexically retrievable — `retrieve` would keep returning the removed passage's full text.
  */
 declare class KeywordRetriever implements Retriever {
     private readonly docs;
@@ -213,9 +344,51 @@ declare class KeywordRetriever implements Retriever {
     private readonly k1;
     private readonly b;
     constructor(options?: KeywordRetrieverOptions);
+    /** How many chunks are currently indexed. */
+    get size(): number;
     /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
     add(records: ChunkRecord[]): void;
-    private remove;
+    /**
+     * Forget a source document — every chunk whose id is `${documentId}` or `${documentId}#<n>`, the
+     * same id scheme (and the same {@link documentIdOf} collapse) the vector stores use for their
+     * `remove`. The keyword half of a hybrid index keeps its own copy of the chunk text, so a document
+     * dropped from the vector store stays fully retrievable here until this is called. Unknown ids are
+     * a no-op.
+     */
+    remove(documentId: string): void;
+    /** Drop every indexed chunk, resetting the corpus statistics with it. */
+    clear(): void;
+    /** Drop ONE chunk by its exact id, decrementing the corpus statistics it contributed. */
+    private removeChunk;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+
+/**
+ * The keyword half of hybrid search, served by the store's own full-text index — the mirror of
+ * {@link import('./embedding-retriever.js').EmbeddingRetriever}, which serves the dense half. It
+ * holds no state: every query goes to the store, so any process that can reach the store can run
+ * lexical search, whether or not it did the ingestion.
+ *
+ * Compose it exactly like the dense leg:
+ *
+ * ```ts
+ * const retriever = new HybridRetriever([
+ *   new EmbeddingRetriever(embedder, store),
+ *   new LexicalRetriever(store),
+ * ]);
+ * ```
+ *
+ * Both legs read the same chunks from the same index, so their ids line up by construction and
+ * `HybridRetriever`'s RRF fuses them without either side needing a score on a common scale.
+ *
+ * Prefer this over {@link import('./keyword-retriever.js').KeywordRetriever} whenever the store
+ * supports it (see {@link import('./vector-store.js').isLexicalVectorStore}) and ingestion and
+ * search can run in different processes; `KeywordRetriever` remains the answer for `MemoryVectorStore`
+ * and single-process deployments.
+ */
+declare class LexicalRetriever implements Retriever {
+    private readonly store;
+    constructor(store: LexicalVectorStore);
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -297,4 +470,4 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, MemoryVectorStore, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type VectorRecord, type VectorSearchOptions, type VectorStore, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments };
+export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, MemoryVectorStore, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type VectorRecord, type VectorSearchOptions, type VectorStore, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };