@adonis-agora/agent 0.7.1 → 0.9.0

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

@@ -0,0 +1,43 @@
+/**
+ * Fuses several retrievers with Reciprocal Rank Fusion — the robust way to combine, say, dense vector
+ * search with lexical BM25. RRF scores each passage by `Σ weight / (k + rank)` across the lists it
+ * appears in, so it needs no score normalization between incompatible scales (cosine vs BM25).
+ * Deduplicates by passage id, so aligned chunk ids from the two retrievers reinforce. Itself a
+ * {@link Retriever}. Mirrors the reference `HybridRetriever` exactly.
+ */
+export class HybridRetriever {
+    retrievers;
+    options;
+    constructor(retrievers, options = {}) {
+        this.retrievers = retrievers;
+        this.options = options;
+    }
+    async retrieve(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, {
+            topK: fetchTopK,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        })));
+        const fused = new Map();
+        lists.forEach((list, listIndex) => {
+            const weight = weights?.[listIndex] ?? 1;
+            list.forEach((passage, rank) => {
+                const contribution = weight / (k + rank + 1);
+                const existing = fused.get(passage.id);
+                if (existing !== undefined) {
+                    existing.score += contribution;
+                }
+                else {
+                    fused.set(passage.id, { passage, score: contribution });
+                }
+            });
+        });
+        return [...fused.values()]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, options.topK ?? 5)
+            .map((entry) => ({ ...entry.passage, score: entry.score }));
+    }
+}
+//# sourceMappingURL=hybrid-retriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-retriever.js","sourceRoot":"","sources":["../../../src/rag/hybrid-retriever.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAEP;IACA;IAFnB,YACmB,UAAuB,EACvB,UAAkC,EAAE;QADpC,eAAU,GAAV,UAAU,CAAa;QACvB,YAAO,GAAP,OAAO,CAA6B;IACpD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,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"}

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

@@ -3,6 +3,9 @@ export { documentIdOf, type IndexedDocument, type VectorRecord, type VectorSearc
 export { matchesFilter } from './filter.js';
 export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
+export { RerankingRetriever, type RerankingRetrieverOptions, } from './reranking-retriever.js';
+export { KeywordRetriever, type KeywordRetrieverOptions } from './keyword-retriever.js';
+export { HybridRetriever, type HybridRetrieverOptions } from './hybrid-retriever.js';
 export { PgVectorStore, PgVectorRetriever, toVectorLiteral, type PgVectorMetric, type PgVectorColumns, type PgVectorStoreOptions, } from './pg-vector-store.js';
 export { chunkDocuments, ingestChunks, ingestDocuments, type ChunkRecord, type IngestChunksOptions, type IngestDocument, type IngestOptions, } from './ingest.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,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/src/rag/index.js

@@ -3,6 +3,9 @@ export { documentIdOf, } from './vector-store.js';
 export { matchesFilter } from './filter.js';
 export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';
+export { RerankingRetriever, } from './reranking-retriever.js';
+export { KeywordRetriever } from './keyword-retriever.js';
+export { HybridRetriever } from './hybrid-retriever.js';
 export { PgVectorStore, PgVectorRetriever, toVectorLiteral, } from './pg-vector-store.js';
 export { chunkDocuments, ingestChunks, ingestDocuments, } from './ingest.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,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,GAIhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,GAKhB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAgC,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,GAIhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,GAKhB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+import type { ChunkRecord } from './ingest.js';
+export interface KeywordRetrieverOptions {
+    /** BM25 term-frequency saturation. Default 1.5. */
+    k1?: number;
+    /** BM25 length normalization, 0 (off) … 1 (full). Default 0.75. */
+    b?: number;
+}
+/**
+ * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME
+ * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
+ * line up and {@link import('./hybrid-retriever.js').HybridRetriever} can fuse the two rankings. Full
+ * BM25: idf, term-frequency saturation (`k1`), and document-length normalization (`b`). Honors the
+ * same array-OR metadata {@link matchesFilter} as the vector store. Mirrors the reference exactly.
+ */
+export declare class KeywordRetriever implements Retriever {
+    private readonly docs;
+    private readonly documentFrequency;
+    private totalLength;
+    private readonly k1;
+    private readonly b;
+    constructor(options?: KeywordRetrieverOptions);
+    /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
+    add(records: ChunkRecord[]): void;
+    private remove;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=keyword-retriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/keyword-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AASD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAS;gBAEf,OAAO,GAAE,uBAA4B;IAKjD,oGAAoG;IACpG,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI;IAgBjC,OAAO,CAAC,MAAM;IAiBR,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAoCjF"}

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

@@ -0,0 +1,91 @@
+import { matchesFilter } from './filter.js';
+/**
+ * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME
+ * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids
+ * line up and {@link import('./hybrid-retriever.js').HybridRetriever} can fuse the two rankings. Full
+ * BM25: idf, term-frequency saturation (`k1`), and document-length normalization (`b`). Honors the
+ * same array-OR metadata {@link matchesFilter} as the vector store. Mirrors the reference exactly.
+ */
+export class KeywordRetriever {
+    docs = new Map();
+    documentFrequency = new Map();
+    totalLength = 0;
+    k1;
+    b;
+    constructor(options = {}) {
+        this.k1 = options.k1 ?? 1.5;
+        this.b = options.b ?? 0.75;
+    }
+    /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
+    add(records) {
+        for (const record of records) {
+            this.remove(record.id);
+            const tokens = tokenize(record.text);
+            const frequencies = new Map();
+            for (const token of tokens) {
+                frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+            }
+            for (const term of frequencies.keys()) {
+                this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+            }
+            this.docs.set(record.id, { record, frequencies, length: tokens.length });
+            this.totalLength += tokens.length;
+        }
+    }
+    remove(id) {
+        const existing = this.docs.get(id);
+        if (existing === undefined) {
+            return;
+        }
+        for (const term of existing.frequencies.keys()) {
+            const next = (this.documentFrequency.get(term) ?? 1) - 1;
+            if (next <= 0) {
+                this.documentFrequency.delete(term);
+            }
+            else {
+                this.documentFrequency.set(term, next);
+            }
+        }
+        this.totalLength -= existing.length;
+        this.docs.delete(id);
+    }
+    async retrieve(query, options = {}) {
+        const total = this.docs.size;
+        if (total === 0) {
+            return [];
+        }
+        const averageLength = this.totalLength / total;
+        const queryTerms = new Set(tokenize(query));
+        const scored = [];
+        for (const { record, frequencies, length } of this.docs.values()) {
+            if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {
+                continue;
+            }
+            let score = 0;
+            for (const term of queryTerms) {
+                const termFrequency = frequencies.get(term);
+                if (termFrequency === undefined) {
+                    continue;
+                }
+                const df = this.documentFrequency.get(term) ?? 0;
+                const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));
+                const denominator = termFrequency + this.k1 * (1 - this.b + (this.b * length) / averageLength);
+                score += idf * ((termFrequency * (this.k1 + 1)) / denominator);
+            }
+            if (score > 0) {
+                scored.push({
+                    id: record.id,
+                    text: record.text,
+                    score,
+                    ...(record.source !== undefined ? { source: record.source } : {}),
+                    ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),
+                });
+            }
+        }
+        return scored.sort((a, b) => b.score - a.score).slice(0, options.topK ?? 5);
+    }
+}
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+//# sourceMappingURL=keyword-retriever.js.map

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

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

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

@@ -45,8 +45,9 @@ export declare function toVectorLiteral(embedding: number[]): string;
  * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
  * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
  * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
- * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
- * table/column identifiers are ever spliced into a statement.
+ * (NEVER string-interpolated). Scalar metadata filters are an `@> ?::jsonb` containment binding; an
+ * array filter value is set-membership (`jsonb_exists_any`, the `?|` function form) — the capability-token
+ * ACL primitive. Only the (validated) table/column identifiers are ever spliced into a statement.
  *
  * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
  * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is

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

@@ -1 +1 @@
-{"version":3,"file":"pg-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAsDD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAuCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,WAAW;IAQ7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,EAAE,EAAE,iBAAiB,EACtC,OAAO,GAAE,oBAAyB;IAgBpC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC,uGAAuG;IACvG,gBAAgB,IAAI,MAAM,EAAE;IAgBtB,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAmCpF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;gBAE3C,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa;CAG9D"}
+{"version":3,"file":"pg-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAsDD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAyFD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,WAAW;IAQ7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,EAAE,EAAE,iBAAiB,EACtC,OAAO,GAAE,oBAAyB;IAgBpC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC,uGAAuG;IACvG,gBAAgB,IAAI,MAAM,EAAE;IAgBtB,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CA6BpF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;gBAE3C,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa;CAG9D"}

package/dist/src/rag/pg-vector-store.js

@@ -36,6 +36,51 @@ function assertIdentifier(name, role) {
 export function toVectorLiteral(embedding) {
     return `[${embedding.join(',')}]`;
 }
+/**
+ * Build the metadata `WHERE` fragment for a filter, using Lucid/Knex positional `?` bindings (never
+ * string interpolation). Two predicate kinds:
+ *
+ * - **scalar** filter values collapse into a single jsonb-containment check (`metadata @> ?::jsonb`) —
+ *   exact-match, byte-for-byte the previous behavior so scalar filters stay backward compatible.
+ * - an **array** filter value is a **match-any** (OR / set membership) check: the record matches when
+ *   its value for that key — scalar or array — shares an element with the filter array. An empty array
+ *   can never match (the `false` deny primitive).
+ *
+ * Set membership uses `jsonb_exists_any(jsonb, text[])` — the function form of the `?|` operator, chosen
+ * because bare `?|` collides with Knex's `?` binding placeholder. The metadata KEY is itself a `?`
+ * binding (`metadata->?`), so a caller-supplied key can never inject SQL; only the (already validated)
+ * table/column identifiers are ever spliced in. Returns `{ sql: '', bindings: [] }` when there is no
+ * filter, preserving the previous unfiltered query shape.
+ */
+function buildMetadataWhere(filter, metadataColumn) {
+    if (filter === undefined || Object.keys(filter).length === 0) {
+        return { sql: '', bindings: [] };
+    }
+    const clauses = [];
+    const bindings = [];
+    const scalar = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                clauses.push('false');
+                continue;
+            }
+            // Coerce the record's value to an array (a scalar becomes a one-element array) so `?|` set
+            // membership works uniformly, then test overlap with the caller's tokens.
+            clauses.push(`jsonb_exists_any(CASE WHEN jsonb_typeof(${metadataColumn}->?) = 'array' ` +
+                `THEN ${metadataColumn}->? ELSE jsonb_build_array(${metadataColumn}->?) END, ?::text[])`);
+            bindings.push(key, key, key, value.map(String));
+        }
+        else {
+            scalar[key] = value;
+        }
+    }
+    if (Object.keys(scalar).length > 0) {
+        clauses.push(`${metadataColumn} @> ?::jsonb`);
+        bindings.push(JSON.stringify(scalar));
+    }
+    return { sql: `WHERE ${clauses.join(' AND ')}`, bindings };
+}
 /** Normalize whatever a Lucid `rawQuery` returns (PG `{rows}`, SQLite array, MySQL `[rows,fields]`). */
 function normalizeRows(raw) {
     if (Array.isArray(raw)) {
@@ -79,8 +124,9 @@ function documentIdExpr(col) {
  * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
  * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
  * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
- * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
- * table/column identifiers are ever spliced into a statement.
+ * (NEVER string-interpolated). Scalar metadata filters are an `@> ?::jsonb` containment binding; an
+ * array filter value is set-membership (`jsonb_exists_any`, the `?|` function form) — the capability-token
+ * ACL primitive. Only the (validated) table/column identifiers are ever spliced into a statement.
  *
  * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
  * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is
@@ -160,11 +206,11 @@ export class PgVectorStore {
     async listDocuments(filter) {
         const c = this.col;
         const docExpr = documentIdExpr(c.id);
-        const hasFilter = filter !== undefined && Object.keys(filter).length > 0;
+        const where = buildMetadataWhere(filter, c.metadata);
         const raw = await this.db.rawQuery(`SELECT DISTINCT ON (${docExpr}) ${docExpr} AS doc_id, ${c.metadata} AS metadata
        FROM ${this.table}
-       ${hasFilter ? `WHERE ${c.metadata} @> ?::jsonb` : ''}
-       ORDER BY ${docExpr}`, hasFilter ? [JSON.stringify(filter)] : []);
+       ${where.sql}
+       ORDER BY ${docExpr}`, where.bindings);
         return normalizeRows(raw).map((row) => {
             const metadata = parseMetadata(row.metadata);
             return {
@@ -176,21 +222,15 @@ export class PgVectorStore {
     async search(embedding, options) {
         const c = this.col;
         const vector = toVectorLiteral(embedding);
-        const hasFilter = options.filter !== undefined && Object.keys(options.filter).length > 0;
+        const where = buildMetadataWhere(options.filter, c.metadata);
         // Bindings are consumed positionally, in the exact order the `?`s appear: score expr (embedding),
-        // then the optional filter, then the ORDER BY embedding, then the LIMIT. The embedding is bound
-        // TWICE — once per `?::vector` — because a positional `?` cannot be reused like a numbered `$1`.
-        const bindings = [vector];
-        let where = '';
-        if (hasFilter) {
-            where = `WHERE ${c.metadata} @> ?::jsonb`;
-            bindings.push(JSON.stringify(options.filter));
-        }
-        bindings.push(vector, options.topK);
+        // then the optional filter clause(s), then the ORDER BY embedding, then the LIMIT. The embedding is
+        // bound TWICE — once per `?::vector` — because a positional `?` cannot be reused like a numbered `$1`.
+        const bindings = [vector, ...where.bindings, vector, options.topK];
         const raw = await this.db.rawQuery(`SELECT ${c.id} AS id, ${c.text} AS text, ${c.source} AS source, ${c.metadata} AS metadata,
               ${this.metric.score(c.embedding)} AS score
        FROM ${this.table}
-       ${where}
+       ${where.sql}
        ORDER BY ${c.embedding} ${this.metric.operator} ?::vector
        LIMIT ?`, bindings);
         return normalizeRows(raw).map((row) => {

package/dist/src/rag/pg-vector-store.js.map

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

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

@@ -0,0 +1,21 @@
+import type { Reranker } from '../spi/reranker.js';
+import type { Passage, RetrieveOptions, Retriever } from '../spi/retriever.js';
+export interface RerankingRetrieverOptions {
+    /** How many candidates to pull from the base retriever before reranking. Default 20. */
+    fetchTopK?: number;
+}
+/**
+ * Two-stage retrieval: over-fetch cheap candidates from a base {@link Retriever}, then reorder them with
+ * a stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage
+ * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,
+ * hybrid, keyword), and is itself a `Retriever` so it drops straight into the config's `retriever` slot.
+ * Mirrors the reference `RerankingRetriever` exactly.
+ */
+export declare class RerankingRetriever implements Retriever {
+    private readonly base;
+    private readonly reranker;
+    private readonly options;
+    constructor(base: Retriever, reranker: Reranker, options?: RerankingRetrieverOptions);
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=reranking-retriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reranking-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/reranking-retriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAEhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,yBAA8B;IAGpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAOjF"}

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

@@ -0,0 +1,25 @@
+/**
+ * Two-stage retrieval: over-fetch cheap candidates from a base {@link Retriever}, then reorder them with
+ * a stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage
+ * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,
+ * hybrid, keyword), and is itself a `Retriever` so it drops straight into the config's `retriever` slot.
+ * Mirrors the reference `RerankingRetriever` exactly.
+ */
+export class RerankingRetriever {
+    base;
+    reranker;
+    options;
+    constructor(base, reranker, options = {}) {
+        this.base = base;
+        this.reranker = reranker;
+        this.options = options;
+    }
+    async retrieve(query, options = {}) {
+        const candidates = await this.base.retrieve(query, {
+            topK: this.options.fetchTopK ?? 20,
+            ...(options.filter !== undefined ? { filter: options.filter } : {}),
+        });
+        return this.reranker.rerank(query, candidates, { topK: options.topK ?? 5 });
+    }
+}
+//# sourceMappingURL=reranking-retriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reranking-retriever.js","sourceRoot":"","sources":["../../../src/rag/reranking-retriever.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IACA;IAHnB,YACmB,IAAe,EACf,QAAkB,EAClB,UAAqC,EAAE;QAFvC,SAAI,GAAJ,IAAI,CAAW;QACf,aAAQ,GAAR,QAAQ,CAAU;QAClB,YAAO,GAAP,OAAO,CAAgC;IACvD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,UAA2B,EAAE;QACzD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;YACjD,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE;YAClC,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;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF"}

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

@@ -10,7 +10,11 @@ export interface VectorRecord {
 }
 export interface VectorSearchOptions {
     topK: number;
-    /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */
+    /**
+     * Metadata filter, passed through from `RetrieveOptions.filter`. A scalar value is exact-match; an
+     * array value is match-any (OR / set membership), with an empty array denying everything — the
+     * capability-token ACL primitive. See {@link import('./filter.js').matchesFilter}.
+     */
     filter?: Record<string, unknown>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7E;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7E;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/src/rag/vector-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAiDA,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAqDA,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/src/spi/reranker.d.ts

@@ -7,8 +7,10 @@ export interface RerankOptions {
  * Re-scores retrieved passages against the query with a stronger (usually cross-encoder) model than
  * the first-stage retriever — the standard precision boost for RAG. It's a black box like
  * {@link import('./retriever.js').Retriever}: bring a Cohere/Voyage rerank endpoint or a local
- * cross-encoder. Provider implementations are deferred this round (SPI only); the testing kit ships a
- * trivial identity reranker. Mirrors the reference `Reranker` contract exactly.
+ * cross-encoder. Compose one over a base retriever with
+ * {@link import('../rag/reranking-retriever.js').RerankingRetriever}. Provider implementations are
+ * deferred this round (SPI only); the testing kit ships a deterministic lexical-overlap reranker.
+ * Mirrors the reference `Reranker` contract exactly.
  */
 export interface Reranker {
     /** Re-order `passages` by relevance to `query`, rewriting their `score`; may drop to `topK`. */

package/dist/src/spi/reranker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzF"}
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzF"}

package/dist/src/spi/tool.d.ts

@@ -14,8 +14,12 @@ export interface AiToolCtx {
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
 }
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-export interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+/**
+ * A tool implementation. `I` is the parsed (Zod-validated) input; `O` is what `execute` returns
+ * (serialized back to the model). `O` defaults to `unknown` — so `ToolHandler<I>` keeps working —
+ * but typing it lets the compiler check the return against what the tool promises.
+ */
+export interface ToolHandler<I = unknown, O = unknown> {
+    execute(input: I, ctx: AiToolCtx): Promise<O> | O;
 }
 //# sourceMappingURL=tool.d.ts.map

package/dist/src/spi/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/spi/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/spi/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACnD,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACnD"}

package/dist/src/testing/fake-embedding-provider.d.ts

@@ -17,11 +17,14 @@ export declare class FakeEmbeddingProvider implements EmbeddingProvider {
     private embedOne;
 }
 /**
- * A trivial identity {@link Reranker} for tests: keeps the retriever's order, only truncating to
- * `topK`. Stands in for a real cross-encoder rerank endpoint (provider impls deferred this round).
+ * A deterministic, offline {@link Reranker} for tests: re-scores each passage by how many distinct
+ * query terms it contains (lexical overlap), then sorts descending and truncates to `topK`. No model,
+ * no randomness — enough to prove {@link import('../rag/reranking-retriever.js').RerankingRetriever}
+ * genuinely RE-ORDERS candidates (not just truncates) against a known-relevant passage. Stands in for a
+ * real cross-encoder rerank endpoint (provider impls deferred this round). Mirrors the reference fake.
  */
 export declare class FakeReranker implements Reranker {
-    rerank(_query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
+    rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
 }
 /**
  * Build a ready-to-use in-memory {@link EmbeddingRetriever} for tests: a {@link MemoryVectorStore} fed

package/dist/src/testing/fake-embedding-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAAK;IAEtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,OAAO,CAAC,QAAQ;CAWjB;AAYD;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACrC,MAAM,CACV,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;CAGtB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAY9B"}
+{"version":3,"file":"fake-embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAAK;IAEtC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,OAAO,CAAC,QAAQ;CAWjB;AAYD;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,QAAQ;IACrC,MAAM,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;CAetB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAY9B"}

package/dist/src/testing/fake-embedding-provider.js

@@ -38,12 +38,27 @@ function hashToken(token, dimensions) {
     return (hash >>> 0) % dimensions;
 }
 /**
- * A trivial identity {@link Reranker} for tests: keeps the retriever's order, only truncating to
- * `topK`. Stands in for a real cross-encoder rerank endpoint (provider impls deferred this round).
+ * A deterministic, offline {@link Reranker} for tests: re-scores each passage by how many distinct
+ * query terms it contains (lexical overlap), then sorts descending and truncates to `topK`. No model,
+ * no randomness — enough to prove {@link import('../rag/reranking-retriever.js').RerankingRetriever}
+ * genuinely RE-ORDERS candidates (not just truncates) against a known-relevant passage. Stands in for a
+ * real cross-encoder rerank endpoint (provider impls deferred this round). Mirrors the reference fake.
  */
 export class FakeReranker {
-    async rerank(_query, passages, options = {}) {
-        return options.topK !== undefined ? passages.slice(0, options.topK) : passages;
+    async rerank(query, passages, options = {}) {
+        const terms = new Set(query.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+        const scored = passages.map((passage) => {
+            const words = new Set(passage.text.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+            let overlap = 0;
+            for (const term of terms) {
+                if (words.has(term)) {
+                    overlap += 1;
+                }
+            }
+            return { ...passage, score: overlap };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return options.topK !== undefined ? scored.slice(0, options.topK) : scored;
     }
 }
 /**

package/dist/src/testing/fake-embedding-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"fake-embedding-provider.js","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fake-embedding-provider.js","sourceRoot":"","sources":["../../../src/testing/fake-embedding-provider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {