@ariaflowagents/rag 0.7.0 → 0.9.0

package/dist/embedders/AiSdkEmbedder.d.ts

@@ -0,0 +1,24 @@
+import type { EmbeddingModel } from 'ai';
+import type { Embedder } from '../types.js';
+export interface AiSdkEmbedderOptions {
+    /** Any Vercel AI SDK embedding model. */
+    model: EmbeddingModel;
+}
+/**
+ * Embedder implementation backed by the Vercel AI SDK.
+ *
+ * Supports any provider registered with the AI SDK:
+ *   - openai.embedding('text-embedding-3-small')
+ *   - google.embedding('text-embedding-004')
+ *   - cohere.embedding('embed-english-v3.0')
+ *   - mistral.embedding('mistral-embed')
+ */
+export declare class AiSdkEmbedder implements Embedder {
+    private readonly model;
+    private cachedDimension;
+    constructor(options: AiSdkEmbedderOptions);
+    get dimension(): number | undefined;
+    embed(text: string): Promise<readonly number[]>;
+    embedMany(texts: string[]): Promise<readonly (readonly number[])[]>;
+}
+//# sourceMappingURL=AiSdkEmbedder.d.ts.map

package/dist/embedders/AiSdkEmbedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AiSdkEmbedder.d.ts","sourceRoot":"","sources":["../../src/embedders/AiSdkEmbedder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,eAAe,CAAqB;gBAEhC,OAAO,EAAE,oBAAoB;IAIzC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAQ/C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;CAQ1E"}

package/dist/embedders/AiSdkEmbedder.js

@@ -0,0 +1,37 @@
+import { embed, embedMany } from 'ai';
+/**
+ * Embedder implementation backed by the Vercel AI SDK.
+ *
+ * Supports any provider registered with the AI SDK:
+ *   - openai.embedding('text-embedding-3-small')
+ *   - google.embedding('text-embedding-004')
+ *   - cohere.embedding('embed-english-v3.0')
+ *   - mistral.embedding('mistral-embed')
+ */
+export class AiSdkEmbedder {
+    model;
+    cachedDimension;
+    constructor(options) {
+        this.model = options.model;
+    }
+    get dimension() {
+        return this.cachedDimension;
+    }
+    async embed(text) {
+        const result = await embed({ model: this.model, value: text });
+        if (!this.cachedDimension) {
+            this.cachedDimension = result.embedding.length;
+        }
+        return result.embedding;
+    }
+    async embedMany(texts) {
+        if (texts.length === 0)
+            return [];
+        const result = await embedMany({ model: this.model, values: texts });
+        if (!this.cachedDimension && result.embeddings.length > 0) {
+            this.cachedDimension = result.embeddings[0].length;
+        }
+        return result.embeddings;
+    }
+}
+//# sourceMappingURL=AiSdkEmbedder.js.map

package/dist/embedders/AiSdkEmbedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AiSdkEmbedder.js","sourceRoot":"","sources":["../../src/embedders/AiSdkEmbedder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAStC;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IACP,KAAK,CAAiB;IAC/B,eAAe,CAAqB;IAE5C,YAAY,OAA6B;QACvC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACjD,CAAC;QACD,OAAO,MAAM,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAe;QAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACrD,CAAC;QACD,OAAO,MAAM,CAAC,UAAU,CAAC;IAC3B,CAAC;CACF"}

package/dist/embedders/index.d.ts

@@ -0,0 +1,3 @@
+export { AiSdkEmbedder } from './AiSdkEmbedder.js';
+export type { AiSdkEmbedderOptions } from './AiSdkEmbedder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/embedders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/embedders/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/embedders/index.js

@@ -0,0 +1,2 @@
+export { AiSdkEmbedder } from './AiSdkEmbedder.js';
+//# sourceMappingURL=index.js.map

package/dist/embedders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embedders/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.d.ts

@@ -2,4 +2,18 @@ export type { KnowledgeChunk, KnowledgeSource, Chunker, ChunkOptions, RetrievalH
 export { createMarkdownChunker, createRecursiveChunker } from './chunkers.js';
 export { createStaticKnowledgeSource } from './source.js';
 export { createLLMRetriever } from './llmRetriever.js';
+export type { Chunk, Document, DocumentLoader, Embedder, VectorEntry, VectorQueryResult, VectorQueryParams, CreateIndexParams, IndexStats, VectorFilter, VectorFilterCondition, VectorStore, RetrievalResult, RetrievalOptions, Retriever, RerankerOptions, Reranker, } from './types.js';
+export { AiSdkEmbedder } from './embedders/index.js';
+export type { AiSdkEmbedderOptions } from './embedders/index.js';
+export { InMemoryVectorStore } from './vectorStores/index.js';
+export { VectorRetriever } from './retrievers/index.js';
+export type { VectorRetrieverOptions } from './retrievers/index.js';
+export { HybridRetriever } from './retrievers/index.js';
+export type { HybridRetrieverSource, HybridRetrieverOptions } from './retrievers/index.js';
+export { LLMReranker } from './rerankers/index.js';
+export type { LLMRerankerOptions } from './rerankers/index.js';
+export { RagPipeline } from './pipeline/index.js';
+export type { RagPipelineOptions } from './pipeline/index.js';
+export { createVectorRetrievalTool } from './tools/index.js';
+export type { VectorRetrievalToolOptions, VectorRetrievalToolOutput, VectorRetrievalToolInput, FilterableFieldDescriptor, } from './tools/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,eAAe,EACf,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,cAAc,EACd,eAAe,EACf,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAOvD,YAAY,EACV,KAAK,EACL,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,QAAQ,GACT,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,4 +1,20 @@
+// ---------------------------------------------------------------------------
+// CAG (Chunk and Generate) primitives
+// ---------------------------------------------------------------------------
 export { createMarkdownChunker, createRecursiveChunker } from './chunkers.js';
 export { createStaticKnowledgeSource } from './source.js';
 export { createLLMRetriever } from './llmRetriever.js';
+// Embedders
+export { AiSdkEmbedder } from './embedders/index.js';
+// Vector stores
+export { InMemoryVectorStore } from './vectorStores/index.js';
+// Retrievers
+export { VectorRetriever } from './retrievers/index.js';
+export { HybridRetriever } from './retrievers/index.js';
+// Rerankers
+export { LLMReranker } from './rerankers/index.js';
+// Pipeline
+export { RagPipeline } from './pipeline/index.js';
+// Tools
+export { createVectorRetrievalTool } from './tools/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,sCAAsC;AACtC,8EAA8E;AAY9E,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AA2BvD,YAAY;AACZ,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,gBAAgB;AAChB,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,aAAa;AACb,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,QAAQ;AACR,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/pipeline/RagPipeline.d.ts

@@ -0,0 +1,52 @@
+import type { Embedder, VectorStore, Chunker, Reranker, Document, RetrievalResult, RetrievalOptions, Retriever } from '../types.js';
+export interface RagPipelineOptions {
+    /** Embedder for converting text to vectors. */
+    embedder: Embedder;
+    /** Vector store for persistent storage and similarity search. */
+    vectorStore: VectorStore;
+    /** Chunker for splitting documents into chunks. */
+    chunker: Chunker;
+    /** Index name for this pipeline's data. */
+    indexName: string;
+    /** Optional reranker for post-retrieval refinement. */
+    reranker?: Reranker;
+    /** Default topK for retrieval. Default: 10. */
+    topK?: number;
+    /** Distance metric for index creation. Default: 'cosine'. */
+    metric?: 'cosine' | 'euclidean' | 'dotproduct';
+    /** Batch size for embedMany calls. Default: 100. */
+    batchSize?: number;
+}
+/**
+ * Convenience class that wires embedder, vector store, chunker,
+ * and optional reranker into a single ingestion + retrieval pipeline.
+ *
+ * Implements the Retriever interface so it can be passed directly
+ * to createVectorRetrievalTool() or used as an agent retriever.
+ */
+export declare class RagPipeline implements Retriever {
+    private readonly embedder;
+    private readonly vectorStore;
+    private readonly chunker;
+    private readonly indexName;
+    private readonly reranker?;
+    private readonly defaultTopK;
+    private readonly metric;
+    private readonly batchSize;
+    constructor(options: RagPipelineOptions);
+    /**
+     * Ensure the vector index exists, creating it if necessary.
+     * Requires at least one embed() call to determine dimension.
+     */
+    ensureIndex(): Promise<void>;
+    /**
+     * Ingest documents: chunk, embed, and store in the vector store.
+     */
+    ingest(documents: Document[]): Promise<void>;
+    /**
+     * Retrieve relevant chunks for a query.
+     * Implements the Retriever interface.
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+//# sourceMappingURL=RagPipeline.d.ts.map

package/dist/pipeline/RagPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RagPipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/RagPipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,WAAW,EAAE,WAAW,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,YAAY,CAAC;IAC/C,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,kBAAkB;IAWvC;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBlC;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClD;;;OAGG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC;CA4B9B"}

package/dist/pipeline/RagPipeline.js

@@ -0,0 +1,105 @@
+/**
+ * Convenience class that wires embedder, vector store, chunker,
+ * and optional reranker into a single ingestion + retrieval pipeline.
+ *
+ * Implements the Retriever interface so it can be passed directly
+ * to createVectorRetrievalTool() or used as an agent retriever.
+ */
+export class RagPipeline {
+    embedder;
+    vectorStore;
+    chunker;
+    indexName;
+    reranker;
+    defaultTopK;
+    metric;
+    batchSize;
+    constructor(options) {
+        this.embedder = options.embedder;
+        this.vectorStore = options.vectorStore;
+        this.chunker = options.chunker;
+        this.indexName = options.indexName;
+        this.reranker = options.reranker;
+        this.defaultTopK = options.topK ?? 10;
+        this.metric = options.metric ?? 'cosine';
+        this.batchSize = options.batchSize ?? 100;
+    }
+    /**
+     * Ensure the vector index exists, creating it if necessary.
+     * Requires at least one embed() call to determine dimension.
+     */
+    async ensureIndex() {
+        const indexes = await this.vectorStore.listIndexes();
+        if (indexes.includes(this.indexName))
+            return;
+        let dimension = this.embedder.dimension;
+        if (!dimension) {
+            const probe = await this.embedder.embed('dimension probe');
+            dimension = probe.length;
+        }
+        await this.vectorStore.createIndex({
+            indexName: this.indexName,
+            dimension,
+            metric: this.metric,
+        });
+    }
+    /**
+     * Ingest documents: chunk, embed, and store in the vector store.
+     */
+    async ingest(documents) {
+        await this.ensureIndex();
+        for (const doc of documents) {
+            const chunks = this.chunker.chunk(doc.text);
+            if (chunks.length === 0)
+                continue;
+            const texts = chunks.map(c => c.text);
+            // Batch embedding to respect provider limits
+            const allEmbeddings = [];
+            for (let i = 0; i < texts.length; i += this.batchSize) {
+                const batch = texts.slice(i, i + this.batchSize);
+                const embeddings = await this.embedder.embedMany(batch);
+                allEmbeddings.push(...embeddings);
+            }
+            const entries = chunks.map((chunk, i) => ({
+                id: `${doc.id}:${chunk.id}`,
+                vector: allEmbeddings[i],
+                metadata: {
+                    ...(chunk.meta ?? {}),
+                    ...(doc.metadata ?? {}),
+                    sourceDocId: doc.id,
+                    chunkId: chunk.id,
+                },
+                document: chunk.text,
+            }));
+            await this.vectorStore.upsert(this.indexName, entries);
+        }
+    }
+    /**
+     * Retrieve relevant chunks for a query.
+     * Implements the Retriever interface.
+     */
+    async retrieve(query, options) {
+        const topK = options?.topK ?? this.defaultTopK;
+        const queryVector = await this.embedder.embed(query);
+        // Fetch more than topK if reranking, to give the reranker a wider pool
+        const fetchK = this.reranker ? topK * 3 : topK;
+        const results = await this.vectorStore.query(this.indexName, {
+            queryVector,
+            topK: fetchK,
+            filter: options?.filter,
+            includeDocuments: true,
+        });
+        let mapped = results.map(r => ({
+            id: r.id,
+            text: r.document ?? '',
+            score: r.score,
+            metadata: r.metadata,
+            sourceId: this.indexName,
+        }));
+        if (this.reranker) {
+            mapped = await this.reranker.rerank(query, mapped, { topK });
+        }
+        return mapped.slice(0, topK);
+    }
+}
+//# sourceMappingURL=RagPipeline.js.map

package/dist/pipeline/RagPipeline.js.map

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

package/dist/pipeline/index.d.ts

@@ -0,0 +1,3 @@
+export { RagPipeline } from './RagPipeline.js';
+export type { RagPipelineOptions } from './RagPipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/pipeline/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/pipeline/index.js

@@ -0,0 +1,2 @@
+export { RagPipeline } from './RagPipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/pipeline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/rerankers/LLMReranker.d.ts

@@ -0,0 +1,28 @@
+import type { LanguageModel } from 'ai';
+import type { Reranker, RetrievalResult, RerankerOptions } from '../types.js';
+export interface LLMRerankerOptions {
+    /** The language model to use for scoring. */
+    model: LanguageModel;
+    /** Maximum number of results to return after reranking. Default: 5. */
+    topK?: number;
+    /** Whether to include the LLM's reasoning in results. Default: true. */
+    includeReasons?: boolean;
+    /** Maximum characters of document text to include per candidate. Default: 1500. */
+    candidateMaxChars?: number;
+}
+/**
+ * Reranker that uses a language model to judge relevance.
+ *
+ * Each candidate document is presented to the LLM alongside the query.
+ * The LLM scores each candidate on a 0-10 scale and optionally provides
+ * a reason for the score. Results are reordered by LLM-assigned score.
+ */
+export declare class LLMReranker implements Reranker {
+    private readonly model;
+    private readonly defaultTopK;
+    private readonly includeReasons;
+    private readonly candidateMaxChars;
+    constructor(options: LLMRerankerOptions);
+    rerank(query: string, results: RetrievalResult[], options?: RerankerOptions): Promise<RetrievalResult[]>;
+}
+//# sourceMappingURL=LLMReranker.d.ts.map

package/dist/rerankers/LLMReranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMReranker.d.ts","sourceRoot":"","sources":["../../src/rerankers/LLMReranker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,KAAK,EAAE,aAAa,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,OAAO,EAAE,kBAAkB;IAOjC,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC;CAqD9B"}

package/dist/rerankers/LLMReranker.js

@@ -0,0 +1,70 @@
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+const scoringSchema = z.object({
+    scored: z.array(z.object({
+        id: z.string(),
+        score: z.number().min(0).max(10),
+        reason: z.string().optional(),
+    })),
+});
+/**
+ * Reranker that uses a language model to judge relevance.
+ *
+ * Each candidate document is presented to the LLM alongside the query.
+ * The LLM scores each candidate on a 0-10 scale and optionally provides
+ * a reason for the score. Results are reordered by LLM-assigned score.
+ */
+export class LLMReranker {
+    model;
+    defaultTopK;
+    includeReasons;
+    candidateMaxChars;
+    constructor(options) {
+        this.model = options.model;
+        this.defaultTopK = options.topK ?? 5;
+        this.includeReasons = options.includeReasons ?? true;
+        this.candidateMaxChars = options.candidateMaxChars ?? 1500;
+    }
+    async rerank(query, results, options) {
+        const topK = options?.topK ?? this.defaultTopK;
+        if (results.length === 0)
+            return [];
+        const candidateBlock = results
+            .map((r, i) => `[${i}] ID: ${r.id}\n` +
+            `Text: ${r.text.slice(0, this.candidateMaxChars)}`)
+            .join('\n\n');
+        const systemPrompt = 'You are a relevance judge. You will be given a query and a list of ' +
+            'candidate documents. Score each document from 0 (completely irrelevant) ' +
+            'to 10 (perfectly relevant) based on how well it answers the query. ' +
+            'Only use candidate IDs from the provided list. Return ALL candidates scored.';
+        const userPrompt = `Query: ${query}\n\n` +
+            `Candidates:\n${candidateBlock}`;
+        const { experimental_output } = await generateText({
+            model: this.model,
+            system: systemPrompt,
+            prompt: userPrompt,
+            experimental_output: Output.object({ schema: scoringSchema }),
+        });
+        if (!experimental_output)
+            return results.slice(0, topK);
+        const scoreMap = new Map();
+        for (const scored of experimental_output.scored) {
+            scoreMap.set(scored.id, {
+                score: scored.score,
+                reason: scored.reason,
+            });
+        }
+        const reranked = results
+            .map(r => {
+            const llmScore = scoreMap.get(r.id);
+            return {
+                ...r,
+                score: llmScore ? llmScore.score / 10 : 0,
+                reason: this.includeReasons ? llmScore?.reason : undefined,
+            };
+        })
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+        return reranked.slice(0, topK);
+    }
+}
+//# sourceMappingURL=LLMReranker.js.map

package/dist/rerankers/LLMReranker.js.map

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

package/dist/rerankers/index.d.ts

@@ -0,0 +1,3 @@
+export { LLMReranker } from './LLMReranker.js';
+export type { LLMRerankerOptions } from './LLMReranker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rerankers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/rerankers/index.js

@@ -0,0 +1,2 @@
+export { LLMReranker } from './LLMReranker.js';
+//# sourceMappingURL=index.js.map

package/dist/rerankers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rerankers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/retrievers/HybridRetriever.d.ts

@@ -0,0 +1,39 @@
+import type { Retriever, RetrievalResult, RetrievalOptions } from '../types.js';
+export interface HybridRetrieverSource {
+    /** The retriever to include in the hybrid. */
+    retriever: Retriever;
+    /** Relative weight for this retriever in fusion scoring. Default: 1.0. */
+    weight?: number;
+}
+export interface HybridRetrieverOptions {
+    /** The retrievers to combine. */
+    sources: HybridRetrieverSource[];
+    /**
+     * The k parameter for reciprocal rank fusion.
+     * Higher values give more weight to lower-ranked results.
+     * Default: 60 (standard RRF constant).
+     */
+    k?: number;
+    /** Default number of results to return. Default: 10. */
+    topK?: number;
+}
+/**
+ * Retriever that combines multiple retrieval strategies using
+ * reciprocal rank fusion (RRF).
+ *
+ * RRF is a rank-based fusion method that does not require score
+ * normalization across retrievers. It works well when combining
+ * retrievers with incompatible scoring scales (e.g., cosine similarity
+ * from a vector store with BM25 scores from keyword search).
+ *
+ * Reference: Cormack, Clarke, Buettcher. "Reciprocal Rank Fusion
+ * outperforms Condorcet and individual Rank Learning Methods." (2009)
+ */
+export declare class HybridRetriever implements Retriever {
+    private readonly sources;
+    private readonly k;
+    private readonly defaultTopK;
+    constructor(options: HybridRetrieverOptions);
+    retrieve(query: string, options?: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+//# sourceMappingURL=HybridRetriever.d.ts.map

package/dist/retrievers/HybridRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridRetriever.d.ts","sourceRoot":"","sources":["../../src/retrievers/HybridRetriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,SAAS,EAAE,SAAS,CAAC;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC;;;;OAIG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,sBAAsB;IAMrC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC;CA2C9B"}

package/dist/retrievers/HybridRetriever.js

@@ -0,0 +1,56 @@
+/**
+ * Retriever that combines multiple retrieval strategies using
+ * reciprocal rank fusion (RRF).
+ *
+ * RRF is a rank-based fusion method that does not require score
+ * normalization across retrievers. It works well when combining
+ * retrievers with incompatible scoring scales (e.g., cosine similarity
+ * from a vector store with BM25 scores from keyword search).
+ *
+ * Reference: Cormack, Clarke, Buettcher. "Reciprocal Rank Fusion
+ * outperforms Condorcet and individual Rank Learning Methods." (2009)
+ */
+export class HybridRetriever {
+    sources;
+    k;
+    defaultTopK;
+    constructor(options) {
+        this.sources = options.sources;
+        this.k = options.k ?? 60;
+        this.defaultTopK = options.topK ?? 10;
+    }
+    async retrieve(query, options) {
+        const topK = options?.topK ?? this.defaultTopK;
+        // Run all retrievers in parallel
+        const allResults = await Promise.all(this.sources.map(s => s.retriever.retrieve(query, options)));
+        // Reciprocal rank fusion
+        const fusedScores = new Map();
+        const bestResult = new Map();
+        for (let i = 0; i < allResults.length; i++) {
+            const weight = this.sources[i].weight ?? 1.0;
+            const results = allResults[i];
+            for (let rank = 0; rank < results.length; rank++) {
+                const result = results[rank];
+                const rrfScore = weight / (this.k + rank + 1);
+                fusedScores.set(result.id, (fusedScores.get(result.id) ?? 0) + rrfScore);
+                // Keep the result with the highest original score for metadata
+                const existing = bestResult.get(result.id);
+                if (!existing || (result.score ?? 0) > (existing.score ?? 0)) {
+                    bestResult.set(result.id, result);
+                }
+            }
+        }
+        // Sort by fused score, return top K
+        const sorted = Array.from(fusedScores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, topK);
+        return sorted.map(([id, rrfScore]) => {
+            const result = bestResult.get(id);
+            return {
+                ...result,
+                score: rrfScore,
+            };
+        });
+    }
+}
+//# sourceMappingURL=HybridRetriever.js.map

package/dist/retrievers/HybridRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HybridRetriever.js","sourceRoot":"","sources":["../../src/retrievers/HybridRetriever.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,eAAe;IACT,OAAO,CAA0B;IACjC,CAAC,CAAS;IACV,WAAW,CAAS;IAErC,YAAY,OAA+B;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,KAAa,EACb,OAA0B;QAE1B,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;QAE/C,iCAAiC;QACjC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,GAAG,CAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAC5D,CAAC;QAEF,yBAAyB;QACzB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;QAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC;YAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC9B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;gBACjD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC7B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;gBAC9C,WAAW,CAAC,GAAG,CACb,MAAM,CAAC,EAAE,EACT,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,CAC7C,CAAC;gBACF,+DAA+D;gBAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC3C,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;oBAC7D,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;QACH,CAAC;QAED,oCAAoC;QACpC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;aAC7C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;aAC3B,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAElB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE;YACnC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;YACnC,OAAO;gBACL,GAAG,MAAM;gBACT,KAAK,EAAE,QAAQ;aAChB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/retrievers/VectorRetriever.d.ts

@@ -0,0 +1,26 @@
+import type { Retriever, RetrievalResult, RetrievalOptions, VectorStore, Embedder } from '../types.js';
+export interface VectorRetrieverOptions {
+    /** The vector store to query. */
+    vectorStore: VectorStore;
+    /** The embedder to convert query text to vectors. */
+    embedder: Embedder;
+    /** The index name to query. */
+    indexName: string;
+    /** Default number of results to return. Default: 10. */
+    topK?: number;
+}
+/**
+ * Retriever backed by vector similarity search.
+ *
+ * Embeds the query using the provided Embedder, then queries the
+ * VectorStore for the most similar entries.
+ */
+export declare class VectorRetriever implements Retriever {
+    private readonly vectorStore;
+    private readonly embedder;
+    private readonly indexName;
+    private readonly defaultTopK;
+    constructor(options: VectorRetrieverOptions);
+    retrieve(query: string, options?: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+//# sourceMappingURL=VectorRetriever.d.ts.map

package/dist/retrievers/VectorRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorRetriever.d.ts","sourceRoot":"","sources":["../../src/retrievers/VectorRetriever.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACT,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,qDAAqD;IACrD,QAAQ,EAAE,QAAQ,CAAC;IACnB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,sBAAsB;IAOrC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC;CAmB9B"}

package/dist/retrievers/VectorRetriever.js

@@ -0,0 +1,36 @@
+/**
+ * Retriever backed by vector similarity search.
+ *
+ * Embeds the query using the provided Embedder, then queries the
+ * VectorStore for the most similar entries.
+ */
+export class VectorRetriever {
+    vectorStore;
+    embedder;
+    indexName;
+    defaultTopK;
+    constructor(options) {
+        this.vectorStore = options.vectorStore;
+        this.embedder = options.embedder;
+        this.indexName = options.indexName;
+        this.defaultTopK = options.topK ?? 10;
+    }
+    async retrieve(query, options) {
+        const queryVector = await this.embedder.embed(query);
+        const topK = options?.topK ?? this.defaultTopK;
+        const results = await this.vectorStore.query(this.indexName, {
+            queryVector,
+            topK,
+            filter: options?.filter,
+            includeDocuments: true,
+        });
+        return results.map(r => ({
+            id: r.id,
+            text: r.document ?? '',
+            score: r.score,
+            metadata: r.metadata,
+            sourceId: this.indexName,
+        }));
+    }
+}
+//# sourceMappingURL=VectorRetriever.js.map