@adonis-agora/agent 0.34.1 → 0.35.0

package/dist/src/rag/http-reranker.js

@@ -0,0 +1,83 @@
+import { errorMessageOf, HttpModelError } from './openai-embeddings.js';
+/**
+ * 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.
+ */
+export class HttpReranker {
+    options;
+    format;
+    doFetch;
+    constructor(options) {
+        this.options = options;
+        this.format = options.format ?? 'auto';
+        this.doFetch = options.fetch ?? fetch;
+    }
+    async rerank(query, passages, options = {}) {
+        if (passages.length === 0) {
+            return [];
+        }
+        const topK = options.topK ?? passages.length;
+        const documents = passages.map((passage) => passage.text);
+        const response = await this.doFetch(this.options.url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(this.options.apiKey ? { authorization: `Bearer ${this.options.apiKey}` } : {}),
+                ...this.options.headers,
+            },
+            body: JSON.stringify({
+                ...(this.options.model !== undefined ? { model: this.options.model } : {}),
+                query,
+                ...(this.format !== 'tei' ? { documents, top_n: topK } : {}),
+                ...(this.format !== 'cohere' ? { texts: documents } : {}),
+            }),
+            signal: AbortSignal.timeout(this.options.timeoutMs ?? 30_000),
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            throw new HttpModelError(response.status, `Rerank request failed (${response.status}): ${errorMessageOf(body)}`);
+        }
+        const items = itemsOf(body);
+        if (items === undefined) {
+            throw new HttpModelError(502, 'Rerank response has no results');
+        }
+        const seen = new Set();
+        const reranked = [];
+        for (const item of items) {
+            const index = item.index;
+            const passage = typeof index === 'number' ? passages[index] : undefined;
+            if (passage === undefined || seen.has(index)) {
+                continue;
+            }
+            seen.add(index);
+            reranked.push({ ...passage, score: Number(item.relevance_score ?? item.score ?? 0) });
+        }
+        reranked.sort((a, b) => b.score - a.score);
+        return reranked.slice(0, topK);
+    }
+}
+function itemsOf(body) {
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (Array.isArray(json)) {
+        return json;
+    }
+    const wrapped = json;
+    const items = wrapped?.results ?? wrapped?.data;
+    return Array.isArray(items) ? items : undefined;
+}
+//# sourceMappingURL=http-reranker.js.map

package/dist/src/rag/http-reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-reranker.js","sourceRoot":"","sources":["../../../src/rag/http-reranker.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/hybrid-retriever.d.ts

@@ -1,4 +1,4 @@
-import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+import type { Passage, RetrievalResult, RetrieveOptions, Retriever } from '../spi/retriever.js';
 export interface HybridRetrieverOptions {
     /** RRF constant — larger flattens the rank weighting. Default 60 (the value from the original paper). */
     k?: number;
@@ -19,5 +19,10 @@ export declare class HybridRetriever implements Retriever {
     private readonly options;
     constructor(retrievers: Retriever[], options?: HybridRetrieverOptions);
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+    /**
+     * {@link HybridRetriever.retrieve} plus the embedding usage of every leg that reports one (summed), so
+     * a hybrid over an embedding leg still reaches the ledger and the quota.
+     */
+    retrieveWithUsage(query: string, options?: RetrieveOptions): Promise<RetrievalResult>;
 }
 //# sourceMappingURL=hybrid-retriever.d.ts.map

package/dist/src/rag/hybrid-retriever.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAE7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF1B,YACmB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE,sBAA2B,EACnD;IAEE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA+B/E;CACF"}
+{"version":3,"file":"hybrid-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhG,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAE7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF1B,YACmB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE,sBAA2B,EACnD;IAEE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAE/E;IAED;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsC9F;CACF"}

package/dist/src/rag/hybrid-retriever.js

@@ -13,13 +13,25 @@ export class HybridRetriever {
         this.options = options;
     }
     async retrieve(query, options = {}) {
+        return (await this.retrieveWithUsage(query, options)).passages;
+    }
+    /**
+     * {@link HybridRetriever.retrieve} plus the embedding usage of every leg that reports one (summed), so
+     * a hybrid over an embedding leg still reaches the ledger and the quota.
+     */
+    async retrieveWithUsage(query, options = {}) {
         const k = this.options.k ?? 60;
         const fetchTopK = this.options.fetchTopK ?? 20;
         const weights = this.options.weights;
-        const lists = await Promise.all(this.retrievers.map((retriever) => retriever.retrieve(query, {
+        const legOptions = {
             topK: fetchTopK,
             ...(options.filter !== undefined ? { filter: options.filter } : {}),
-        })));
+        };
+        const results = await Promise.all(this.retrievers.map(async (retriever) => typeof retriever.retrieveWithUsage === 'function'
+            ? retriever.retrieveWithUsage(query, legOptions)
+            : { passages: await retriever.retrieve(query, legOptions) }));
+        const lists = results.map((result) => result.passages);
+        const usage = sumUsage(results.map((result) => result.usage));
         const fused = new Map();
         lists.forEach((list, listIndex) => {
             const weight = weights?.[listIndex] ?? 1;
@@ -34,10 +46,22 @@ export class HybridRetriever {
                 }
             });
         });
-        return [...fused.values()]
+        const passages = [...fused.values()]
             .sort((a, b) => b.score - a.score)
             .slice(0, options.topK ?? 5)
             .map((entry) => ({ ...entry.passage, score: entry.score }));
+        return { passages, ...(usage !== undefined ? { usage } : {}) };
+    }
+}
+function sumUsage(usages) {
+    const reported = usages.filter((usage) => usage !== undefined);
+    if (reported.length === 0) {
+        return undefined;
     }
+    const modelId = reported.find((usage) => usage.modelId !== undefined)?.modelId;
+    return {
+        inputTokens: reported.reduce((total, usage) => total + usage.inputTokens, 0),
+        ...(modelId !== undefined ? { modelId } : {}),
+    };
 }
 //# sourceMappingURL=hybrid-retriever.js.map

package/dist/src/rag/hybrid-retriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-retriever.js","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAEP,UAAU;IACV,OAAO;IAF1B,YACmB,UAAuB,EACvB,OAAO,GAA2B,EAAE;0BADpC,UAAU;uBACV,OAAO;IACvB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAAO,GAAoB,EAAE;QACzD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QACrC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAChC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE;YACxB,IAAI,EAAE,SAAS;YACf,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CACH,CACF,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+C,CAAC;QACrE,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE;YAChC,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE;gBAC7B,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;gBAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,QAAQ,CAAC,KAAK,IAAI,YAAY,CAAC;gBACjC,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;aACvB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,CAAC;CACF"}
+{"version":3,"file":"hybrid-retriever.js","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/index.d.ts

@@ -1,11 +1,14 @@
 export { type ChunkOptions, chunkText } from './chunk.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
 export { matchesFilter } from './filter.js';
+export { HttpReranker, type HttpRerankerOptions } from './http-reranker.js';
 export { HybridRetriever, type HybridRetrieverOptions } from './hybrid-retriever.js';
 export { type ChunkRecord, chunkDocuments, type IngestChunksOptions, type IngestDocument, type IngestOptions, ingestChunks, ingestDocuments, } from './ingest.js';
 export { KeywordRetriever, type KeywordRetrieverOptions } from './keyword-retriever.js';
+export { LexicalRetriever } from './lexical-retriever.js';
 export { cosineSimilarity, MemoryVectorStore } from './memory-vector-store.js';
-export { type PgVectorColumns, type PgVectorMetric, PgVectorRetriever, PgVectorStore, type PgVectorStoreOptions, stripNulBytes, toVectorLiteral, } from './pg-vector-store.js';
+export { HttpModelError, type OpenAiEmbeddingsOptions, openAiEmbeddings, } from './openai-embeddings.js';
+export { type PgFullTextOptions, PgLexicalVectorStore, type PgVectorColumns, type PgVectorMetric, PgVectorRetriever, PgVectorStore, type PgVectorStoreOptions, stripNulBytes, toVectorLiteral, } from './pg-vector-store.js';
 export { RerankingRetriever, type RerankingRetrieverOptions, } from './reranking-retriever.js';
-export { applyMetadataPatch, assertRemovalFilter, documentIdOf, effectivePatchKeys, filterDeniesAll, type IndexedDocument, type MetadataPatch, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, } from './vector-store.js';
+export { applyMetadataPatch, assertRemovalFilter, documentIdOf, effectivePatchKeys, filterDeniesAll, type IndexedDocument, isLexicalVectorStore, type LexicalVectorStore, type MetadataPatch, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, } from './vector-store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,KAAK,WAAW,EAChB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,aAAa,EACb,KAAK,oBAAoB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,KAAK,WAAW,EAChB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,cAAc,EACd,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,iBAAiB,EACtB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,aAAa,EACb,KAAK,oBAAoB,EACzB,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,KAAK,eAAe,EACpB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/src/rag/index.js

@@ -1,11 +1,14 @@
 export { chunkText } from './chunk.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
 export { matchesFilter } from './filter.js';
+export { HttpReranker } from './http-reranker.js';
 export { HybridRetriever } from './hybrid-retriever.js';
 export { chunkDocuments, ingestChunks, ingestDocuments, } from './ingest.js';
 export { KeywordRetriever } from './keyword-retriever.js';
+export { LexicalRetriever } from './lexical-retriever.js';
 export { cosineSimilarity, MemoryVectorStore } from './memory-vector-store.js';
-export { PgVectorRetriever, PgVectorStore, stripNulBytes, toVectorLiteral, } from './pg-vector-store.js';
+export { HttpModelError, openAiEmbeddings, } from './openai-embeddings.js';
+export { PgLexicalVectorStore, PgVectorRetriever, PgVectorStore, stripNulBytes, toVectorLiteral, } from './pg-vector-store.js';
 export { RerankingRetriever, } from './reranking-retriever.js';
-export { applyMetadataPatch, assertRemovalFilter, documentIdOf, effectivePatchKeys, filterDeniesAll, UnsafeRemovalError, } from './vector-store.js';
+export { applyMetadataPatch, assertRemovalFilter, documentIdOf, effectivePatchKeys, filterDeniesAll, isLexicalVectorStore, UnsafeRemovalError, } from './vector-store.js';
 //# sourceMappingURL=index.js.map

package/dist/src/rag/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAEL,cAAc,EAId,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAgC,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAGL,iBAAiB,EACjB,aAAa,EAEb,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAGf,kBAAkB,GAInB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAEL,cAAc,EAId,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAgC,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EACL,cAAc,EAEd,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,oBAAoB,EAGpB,iBAAiB,EACjB,aAAa,EAEb,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAEf,oBAAoB,EAGpB,kBAAkB,GAInB,MAAM,mBAAmB,CAAC"}

package/dist/src/rag/lexical-retriever.d.ts

@@ -0,0 +1,23 @@
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+import type { LexicalVectorStore } from './vector-store.js';
+/**
+ * A {@link Retriever} over a store's own full-text index — the lexical half of a hybrid search, next to
+ * an {@link import('./embedding-retriever.js').EmbeddingRetriever} over the same store:
+ *
+ * ```ts
+ * const store = new PgLexicalVectorStore(db, { dimension: 1536 })
+ * const retriever = new HybridRetriever([
+ *   new EmbeddingRetriever(embedder, store),
+ *   new LexicalRetriever(store),
+ * ])
+ * ```
+ *
+ * Embeds nothing, so it reports no usage. `minScore` is not forwarded: a text rank is not a similarity,
+ * and a floor tuned for cosine would mean nothing on it.
+ */
+export declare class LexicalRetriever implements Retriever {
+    private readonly store;
+    constructor(store: LexicalVectorStore);
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=lexical-retriever.d.ts.map

package/dist/src/rag/lexical-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/lexical-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAlC,YAA6B,KAAK,EAAE,kBAAkB,EAAI;IAEpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAK/E;CACF"}

package/dist/src/rag/lexical-retriever.js

@@ -0,0 +1,28 @@
+/**
+ * A {@link Retriever} over a store's own full-text index — the lexical half of a hybrid search, next to
+ * an {@link import('./embedding-retriever.js').EmbeddingRetriever} over the same store:
+ *
+ * ```ts
+ * const store = new PgLexicalVectorStore(db, { dimension: 1536 })
+ * const retriever = new HybridRetriever([
+ *   new EmbeddingRetriever(embedder, store),
+ *   new LexicalRetriever(store),
+ * ])
+ * ```
+ *
+ * Embeds nothing, so it reports no usage. `minScore` is not forwarded: a text rank is not a similarity,
+ * and a floor tuned for cosine would mean nothing on it.
+ */
+export class LexicalRetriever {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async retrieve(query, options = {}) {
+        return this.store.searchText(query, {
+            topK: options.topK ?? 5,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        });
+    }
+}
+//# sourceMappingURL=lexical-retriever.js.map

package/dist/src/rag/lexical-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-retriever.js","sourceRoot":"","sources":["../../../src/rag/lexical-retriever.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,gBAAgB;IACE,KAAK;IAAlC,YAA6B,KAAyB;qBAAzB,KAAK;IAAuB,CAAC;IAE1D,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAAO,GAAoB,EAAE;QACzD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC;YACvB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/rag/openai-embeddings.d.ts

@@ -0,0 +1,62 @@
+import type { EmbeddingProvider } from '../spi/embedding-provider.js';
+/** A non-2xx answer (or a malformed one) from an embeddings or rerank endpoint. */
+export 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);
+}
+export 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. The same counts also reach the
+     * ledger and quota through `embedWithUsage`; this is for your own metering on top.
+     */
+    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.
+ * Implements `embedWithUsage` with the provider-reported tokens (summed over the batches) and model, so
+ * embedding spend reaches the ledger and the quota.
+ *
+ * ```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' });
+ * ```
+ */
+export declare function openAiEmbeddings(options: OpenAiEmbeddingsOptions): EmbeddingProvider;
+/** The human part of an error body: OpenAI's `error.message`, a bare `message`/`error`, or the text. */
+export declare function errorMessageOf(body: string): string;
+//# sourceMappingURL=openai-embeddings.d.ts.map

package/dist/src/rag/openai-embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-embeddings.d.ts","sourceRoot":"","sources":["../../../src/rag/openai-embeddings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,8BAA8B,CAAC;AAEvF,mFAAmF;AACnF,qBAAa,cAAe,SAAQ,KAAK;IAErC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB;IACE,mGAAmG;IAC1F,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,iBAAiB,CA6EpF;AAUD,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUnD"}

package/dist/src/rag/openai-embeddings.js

@@ -0,0 +1,106 @@
+/** A non-2xx answer (or a malformed one) from an embeddings or rerank endpoint. */
+export class HttpModelError extends Error {
+    status;
+    constructor(
+    /** HTTP status; `502` when the endpoint answered 2xx with a body that doesn't fit the contract. */
+    status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpModelError';
+    }
+}
+/**
+ * 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.
+ * Implements `embedWithUsage` with the provider-reported tokens (summed over the batches) and model, so
+ * embedding spend reaches the ledger and the quota.
+ *
+ * ```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' });
+ * ```
+ */
+export function openAiEmbeddings(options) {
+    const url = `${(options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/+$/, '')}/embeddings`;
+    const batchSize = Math.max(1, Math.floor(options.batchSize ?? 64));
+    const maxInputChars = options.maxInputChars ?? 24_000;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const doFetch = options.fetch ?? fetch;
+    const provider = {
+        async embed(texts) {
+            return (await provider.embedWithUsage(texts)).vectors;
+        },
+        async embedWithUsage(texts) {
+            const vectors = [];
+            let inputTokens;
+            let modelId;
+            for (let start = 0; start < texts.length; start += batchSize) {
+                const input = texts
+                    .slice(start, start + batchSize)
+                    .map((text) => (text.length > maxInputChars ? text.slice(0, maxInputChars) : text) || ' ');
+                const response = await doFetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
+                        ...options.headers,
+                    },
+                    body: JSON.stringify({
+                        model: options.model,
+                        input,
+                        ...(options.dimensions !== undefined ? { dimensions: options.dimensions } : {}),
+                    }),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                const body = await response.text();
+                if (!response.ok) {
+                    throw new HttpModelError(response.status, `Embeddings request failed (${response.status}): ${errorMessageOf(body)}`);
+                }
+                const json = parseJson(body);
+                const items = [...(json?.data ?? [])].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+                if (items.length !== input.length ||
+                    !items.every((item) => Array.isArray(item.embedding))) {
+                    throw new HttpModelError(502, `Embeddings returned ${items.length} vectors for ${input.length} inputs`);
+                }
+                for (const item of items) {
+                    vectors.push(item.embedding);
+                }
+                const tokens = json?.usage?.total_tokens ?? json?.usage?.prompt_tokens;
+                if (typeof tokens === 'number' && Number.isFinite(tokens)) {
+                    inputTokens = (inputTokens ?? 0) + tokens;
+                    options.onUsage?.(tokens);
+                }
+                modelId ??= typeof json?.model === 'string' ? json.model : undefined;
+            }
+            return {
+                vectors,
+                ...(inputTokens !== undefined
+                    ? { usage: { inputTokens, modelId: modelId ?? options.model } }
+                    : {}),
+            };
+        },
+    };
+    return provider;
+}
+function parseJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+}
+/** The human part of an error body: OpenAI's `error.message`, a bare `message`/`error`, or the text. */
+export function errorMessageOf(body) {
+    const json = parseJson(body);
+    const message = typeof json?.error === 'string'
+        ? json.error
+        : (json?.error?.message ?? json?.message ?? undefined);
+    return typeof message === 'string' ? message : body.slice(0, 300);
+}
+//# sourceMappingURL=openai-embeddings.js.map

package/dist/src/rag/openai-embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-embeddings.js","sourceRoot":"","sources":["../../../src/rag/openai-embeddings.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/pg-vector-store.d.ts

@@ -2,7 +2,7 @@ import type { EmbeddingProvider } from '../spi/embedding-provider.js';
 import type { Passage } from '../spi/retriever.js';
 import type { LucidRawRunner } from '../stores/lucid.js';
 import { EmbeddingRetriever } from './embedding-retriever.js';
-import type { IndexedDocument, MetadataPatch, VectorRecord, VectorSearchOptions, VectorStore } from './vector-store.js';
+import type { IndexedDocument, LexicalVectorStore, MetadataPatch, VectorRecord, VectorSearchOptions, VectorStore } from './vector-store.js';
 /**
  * The similarity metric — which pgvector distance operator ranks results (and which index opclass the
  * migration should build). `cosine` (the default) is scale-invariant and the right choice for most
@@ -30,8 +30,40 @@ export interface PgVectorColumns {
 export interface PgVectorStoreOptions {
     /** Table name. Default `agent_rag_chunks`. Validated against the identifier regex. */
     table?: string;
-    /** Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536. */
-    dimension?: 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 — say, while
+     * migrating from a 768-wide local model to a 1536-wide hosted one): the column becomes an untyped
+     * `vector`, the schema gets 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 width that is not listed is
+     * still answered — exactly, by a sequential scan. Put the model in the chunk metadata and filter on
+     * it when two models share a width.
+     */
+    dimension?: 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. `search` skips them; the lexical leg of
+     * {@link PgLexicalVectorStore} still finds them. Default `false` — the column stays `NOT NULL`. Only
+     * changes the DDL for a table that does not exist yet.
+     */
+    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 what the index produced. Applied with `SET LOCAL` inside a
+     * transaction, so it needs a handle with `transaction` (Lucid's `db` has one); silently skipped on an
+     * older pgvector or a runner without transactions. Default off.
+     */
+    iterativeScan?: 'strict_order' | 'relaxed_order';
+    /** `hnsw.ef_search` for `search` (candidate list size; pgvector's default is 40). Needs `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;
     /** Similarity metric / distance operator. Default `cosine`. */
     metric?: PgVectorMetric;
     /** Override the physical column names (each validated). */
@@ -78,12 +110,20 @@ export declare function stripNulBytes<T>(value: T): T;
  * `vector` extension, the chunk table, and the metric's index.
  */
 export declare class PgVectorStore implements VectorStore {
-    private readonly db;
-    private readonly table;
+    protected readonly db: LucidRawRunner;
+    protected readonly table: string;
+    /** The single width (fixed-dimension table), or `undefined` for a mixed-dimension table. */
     private readonly dimension;
+    /** 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;
     private readonly metric;
     private readonly metricName;
-    private readonly col;
+    protected readonly col: Required<PgVectorColumns>;
     constructor(db: LucidRawRunner, options?: PgVectorStoreOptions);
     /**
      * Idempotent DDL — the `vector` extension, the chunk table, and the metric's index. Handy for tests
@@ -98,6 +138,9 @@ export declare class PgVectorStore implements VectorStore {
      * (`0x00`) in `text`/`jsonb` outright, while upstream sources (PDF extraction, Qdrant) happily carry
      * it, so an unstripped chunk would otherwise fail this INSERT with `invalid byte sequence for encoding
      * "UTF8": 0x00`. The embedding is untouched — it is never text/jsonb.
+     *
+     * Written as multi-row `INSERT … ON CONFLICT` statements of {@link PgVectorStoreOptions.upsertBatchSize}
+     * rows each (one round trip per batch instead of per chunk). An empty `embedding` is written as `NULL`.
      */
     upsert(records: VectorRecord[]): Promise<void>;
     /**
@@ -144,7 +187,69 @@ export declare class PgVectorStore implements VectorStore {
      * clause here as it does there, and a scalar the same `@> ?::jsonb` containment.
      */
     removeWhere(filter: Record<string, unknown>): Promise<number>;
+    /**
+     * Nearest first by the configured metric. On a mixed-dimension table only vectors as wide as the
+     * query are compared (through that width's partial index when it has one); a chunk without an
+     * embedding is never returned.
+     */
     search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+    /** 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;
+}
+/** Where the lexical leg of a {@link PgLexicalVectorStore} reads its `tsvector` from. */
+export 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. Must be the configuration
+     * the index was built with, or Postgres cannot use the index and scans the table.
+     */
+    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 `to_tsvector(config, text)`, and {@link PgVectorStore.schemaStatements} adds a GIN
+     * expression index over exactly that.
+     */
+    column?: string;
+    /**
+     * When the query 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;
+}
+/**
+ * {@link PgVectorStore} plus Postgres full-text search: a {@link LexicalVectorStore}, so a
+ * {@link import('./lexical-retriever.js').LexicalRetriever} and a
+ * {@link import('./hybrid-retriever.js').HybridRetriever} can fuse the dense and lexical legs over the
+ * same rows and ids. `retrievers.pgvector({ fullText: {} })` wires exactly that.
+ *
+ * Ranking is `ts_rank_cd` (cover density); the query goes through `websearch_to_tsquery` (quoted
+ * phrases, `-exclusions`, `or`), falling back to any word (see {@link PgFullTextOptions.anyTermFallback}).
+ *
+ * A separate class rather than a method on {@link PgVectorStore} on purpose: full-text search needs a
+ * GIN index, which on a populated table belongs in a migration you run and watch (`CREATE INDEX` in
+ * `ensureSchema` takes a write lock at boot), and a store that silently grew `searchText` on upgrade
+ * would be picked up by every `isLexicalVectorStore` check and scan an unindexed table.
+ */
+export declare class PgLexicalVectorStore extends PgVectorStore implements LexicalVectorStore {
+    private readonly tsConfig;
+    private readonly tsColumn;
+    private readonly anyTermFallback;
+    constructor(db: LucidRawRunner, options?: PgVectorStoreOptions & {
+        fullText?: PgFullTextOptions;
+    });
+    schemaStatements(): string[];
+    /**
+     * Full-text search over the chunk text. `score` is a `ts_rank_cd` rank — not a similarity, and not on
+     * the vector leg's scale — so `minScore` is deliberately not applied here.
+     */
+    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;
 }
 /**
  * A {@link import('../spi/retriever.js').Retriever} over a {@link PgVectorStore}: embed the query, then