kagent-ts 0.1.3 → 0.1.5

package/dist/rag/rag-types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * RAG (Retrieval-Augmented Generation) type definitions.
+ *
+ * The RAG module provides document indexing and semantic retrieval,
+ * exposed to the LLM as callable tools (`search_knowledge`, `list_knowledge_documents`).
+ */
+/** A loaded document with its original metadata. */
+export interface RAGDocument {
+    /** Relative path from the documents root directory. */
+    path: string;
+    /** Raw document text (before chunking). */
+    content: string;
+    /** Chunks produced by the text splitter. */
+    chunks: RAGChunk[];
+}
+/** A single chunk of text with its embedding vector. */
+export interface RAGChunk {
+    /** The chunk text content. */
+    text: string;
+    /** The embedding vector (populated by the EmbeddingProvider). */
+    embedding: number[];
+    /** Source document path. */
+    sourcePath: string;
+    /** Zero-based chunk index within the source document. */
+    chunkIndex: number;
+}
+/**
+ * Interface for generating text embeddings.
+ *
+ * Built-in implementation: OpenAIEmbeddingProvider (text-embedding-3-small / etc.).
+ * Users can provide their own implementation for local models or other providers.
+ */
+export interface EmbeddingProvider {
+    /** Model identifier (for logging / cost tracking). */
+    readonly model: string;
+    /**
+     * Generate embedding vectors for the given texts.
+     *
+     * Batch-friendly: the implementation should send all texts in one API call
+     * when the provider supports it.
+     */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Dimension of the embedding vectors this provider produces. */
+    readonly dimensions: number;
+}
+/** A single search result returned by the vector store. */
+export interface RAGSearchResult {
+    /** The matched chunk. */
+    chunk: RAGChunk;
+    /** Cosine similarity score (0–1). */
+    score: number;
+}
+/**
+ * Interface for storing and searching embeddings.
+ *
+ * Built-in implementation: InMemoryVectorStore (cosine similarity, no deps).
+ */
+export interface VectorStore {
+    /** Add chunks with their embeddings to the store. */
+    add(chunks: RAGChunk[]): Promise<void>;
+    /**
+     * Search for the top-K most similar chunks to the query embedding.
+     * Returns results sorted by similarity descending.
+     */
+    search(queryEmbedding: number[], topK: number): Promise<RAGSearchResult[]>;
+    /** Number of chunks currently stored. */
+    readonly size: number;
+    /** Remove all chunks. */
+    clear(): Promise<void>;
+}
+/**
+ * Interface for re-ranking retrieved results.
+ *
+ * After vector search (and optionally BM25 + RRF), a re-ranker can
+ * re-score the candidates using a more expensive but accurate model
+ * (e.g., a Cross-Encoder or LLM).
+ */
+export interface ReRanker {
+    /**
+     * Re-rank a list of candidate results for a given query.
+     *
+     * @param query   The original search query.
+     * @param results The candidate results to re-rank (typically 2–3× topK).
+     * @returns       Re-ranked results with updated scores, sorted descending.
+     */
+    rerank(query: string, results: RAGSearchResult[]): Promise<RAGSearchResult[]>;
+}
+/** Configuration for the RAG module (passed via AgentConfig.rag). */
+export interface RAGConfig {
+    /** Path to the directory containing documents to index. */
+    documentsDir: string;
+    /** Provider for generating embeddings. */
+    embeddingProvider: EmbeddingProvider;
+    /** Maximum characters per chunk (default: 1000). */
+    chunkSize?: number;
+    /** Characters of overlap between adjacent chunks (default: 200). */
+    chunkOverlap?: number;
+    /** Number of top results to return per search (default: 5). */
+    topK?: number;
+    /**
+     * Custom vector store instance (default: InMemoryVectorStore).
+     *
+     * Use this to plug in a persistent or database-backed store:
+     * ```ts
+     * store: new ChromaVectorStore({ embeddingDimension: 1536 })
+     * ```
+     */
+    store?: VectorStore;
+    /**
+     * Enable hybrid retrieval (BM25 keyword + vector + RRF fusion).
+     *
+     * When true, each search runs both a vector similarity search and a BM25
+     * keyword search in parallel, then merges the results using Reciprocal
+     * Rank Fusion. This improves recall for queries with rare keywords or
+     * domain-specific terminology.
+     *
+     * Default: false (pure vector search).
+     */
+    hybridSearch?: boolean;
+    /**
+     * When hybridSearch is enabled, each retrieval system fetches
+     * `topK * hybridRetrievalFactor` candidates before RRF fusion.
+     *
+     * Higher values improve recall at a small latency cost.
+     * Default: 3.
+     */
+    hybridRetrievalFactor?: number;
+    /**
+     * Optional re-ranker for post-retrieval refinement.
+     *
+     * After retrieval (and optionally RRF fusion), the candidate results
+     * are passed to the re-ranker, which re-scores them using a more
+     * accurate model (e.g., a Cross-Encoder or an LLM).
+     *
+     * The re-ranker receives all pre-ranked candidates and returns a
+     * re-sorted list. The final top-K results are taken from the
+     * re-ranker's output.
+     *
+     * Without a re-ranker, results are returned as-is from retrieval/RRF.
+     */
+    reRanker?: ReRanker;
+}
+//# sourceMappingURL=rag-types.d.ts.map

package/dist/rag/rag-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-types.d.ts","sourceRoot":"","sources":["../../src/rag/rag-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE5C,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,KAAK,EAAE,QAAQ,CAAC;IAChB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE3E,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yBAAyB;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC/E;AAID,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB"}

package/dist/rag/rag-types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * RAG (Retrieval-Augmented Generation) type definitions.
+ *
+ * The RAG module provides document indexing and semantic retrieval,
+ * exposed to the LLM as callable tools (`search_knowledge`, `list_knowledge_documents`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=rag-types.js.map

package/dist/rag/rag-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-types.js","sourceRoot":"","sources":["../../src/rag/rag-types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/rag/rrf.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reciprocal Rank Fusion (RRF) — merge multiple ranked result sets
+ * into a single combined ranking.
+ *
+ * RRF is a simple, hyperparameter-free method for combining rankings
+ * from different retrieval systems (e.g. vector search + BM25).
+ *
+ * Formula:
+ *   RRFscore(d) = Σ_{r ∈ R} 1 / (k + rank_r(d))
+ * where `k` is a smoothing constant (default 60) and `rank_r(d)` is the
+ * 1-based rank position of document `d` in ranking `r`.
+ *
+ * Reference: Cormack et al. "Reciprocal Rank Fusion outperforms Condorcet
+ * and individual rank learning methods" (SIGIR 2009).
+ */
+import type { RAGChunk } from "./rag-types";
+/** A single result from one retrieval system. */
+export interface RankedResult {
+    chunk: RAGChunk;
+    score: number;
+}
+/** The output of RRF fusion. */
+export interface RRFFusionResult {
+    chunk: RAGChunk;
+    rrfScore: number;
+    /** Which rankings contributed to this result (bitmask: 1<<0 = vec, 1<<1 = bm25, etc.). */
+    sources: number;
+}
+/**
+ * Generate a unique key for a chunk.
+ * Uses sourcePath + chunkIndex to uniquely identify a chunk across rankings.
+ */
+export declare function chunkKey(chunk: RAGChunk): string;
+/**
+ * Fuse multiple ranked result lists using Reciprocal Rank Fusion.
+ *
+ * Each element of `rankings` is one ranked result list (best first).
+ * Results from the same chunk (identified by `chunkKey`) across different
+ * rankings have their RRF scores summed.
+ *
+ * @param rankings  Array of ranked result lists, one per retrieval system.
+ * @param k         RRF smoothing constant (default: 60).
+ * @param topN      Number of top results to return (default: 10).
+ * @returns         Combined results sorted by RRF score descending.
+ */
+export declare function rrfFusion(rankings: RankedResult[][], k?: number, topN?: number): RRFFusionResult[];
+//# sourceMappingURL=rrf.d.ts.map

package/dist/rag/rrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../src/rag/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gCAAgC;AAChC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEhD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EAAE,EAAE,EAC1B,CAAC,GAAE,MAAW,EACd,IAAI,GAAE,MAAW,GAChB,eAAe,EAAE,CA+BnB"}

package/dist/rag/rrf.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Reciprocal Rank Fusion (RRF) — merge multiple ranked result sets
+ * into a single combined ranking.
+ *
+ * RRF is a simple, hyperparameter-free method for combining rankings
+ * from different retrieval systems (e.g. vector search + BM25).
+ *
+ * Formula:
+ *   RRFscore(d) = Σ_{r ∈ R} 1 / (k + rank_r(d))
+ * where `k` is a smoothing constant (default 60) and `rank_r(d)` is the
+ * 1-based rank position of document `d` in ranking `r`.
+ *
+ * Reference: Cormack et al. "Reciprocal Rank Fusion outperforms Condorcet
+ * and individual rank learning methods" (SIGIR 2009).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkKey = chunkKey;
+exports.rrfFusion = rrfFusion;
+// ─── Chunk key ───────────────────────────────────────────────────────────────
+/**
+ * Generate a unique key for a chunk.
+ * Uses sourcePath + chunkIndex to uniquely identify a chunk across rankings.
+ */
+function chunkKey(chunk) {
+    return `${chunk.sourcePath}#${chunk.chunkIndex}`;
+}
+// ─── RRF ─────────────────────────────────────────────────────────────────────
+/**
+ * Fuse multiple ranked result lists using Reciprocal Rank Fusion.
+ *
+ * Each element of `rankings` is one ranked result list (best first).
+ * Results from the same chunk (identified by `chunkKey`) across different
+ * rankings have their RRF scores summed.
+ *
+ * @param rankings  Array of ranked result lists, one per retrieval system.
+ * @param k         RRF smoothing constant (default: 60).
+ * @param topN      Number of top results to return (default: 10).
+ * @returns         Combined results sorted by RRF score descending.
+ */
+function rrfFusion(rankings, k = 60, topN = 10) {
+    // Map chunkKey → { chunk, accumulated RRF score, source bitmask }
+    const fused = new Map();
+    for (let r = 0; r < rankings.length; r++) {
+        const ranking = rankings[r];
+        const sourceBit = 1 << r;
+        for (let i = 0; i < ranking.length; i++) {
+            const item = ranking[i];
+            const key = chunkKey(item.chunk);
+            const rank = i + 1; // 1-based rank
+            const existing = fused.get(key);
+            if (existing) {
+                existing.rrfScore += 1 / (k + rank);
+                existing.sources |= sourceBit;
+            }
+            else {
+                fused.set(key, {
+                    chunk: item.chunk,
+                    rrfScore: 1 / (k + rank),
+                    sources: sourceBit,
+                });
+            }
+        }
+    }
+    // Sort by RRF score descending, take top-N
+    return Array.from(fused.values())
+        .sort((a, b) => b.rrfScore - a.rrfScore)
+        .slice(0, topN);
+}
+//# sourceMappingURL=rrf.js.map

package/dist/rag/rrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.js","sourceRoot":"","sources":["../../src/rag/rrf.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA0BH,4BAEC;AAgBD,8BAmCC;AA3DD,gFAAgF;AAEhF;;;GAGG;AACH,SAAgB,QAAQ,CAAC,KAAe;IACtC,OAAO,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;AACnD,CAAC;AAED,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CACvB,QAA0B,EAC1B,IAAY,EAAE,EACd,OAAe,EAAE;IAEjB,kEAAkE;IAClE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkE,CAAC;IAExF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC;QAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe;YAEnC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBACpC,QAAQ,CAAC,OAAO,IAAI,SAAS,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;oBACb,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;oBACxB,OAAO,EAAE,SAAS;iBACnB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;SACvC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AACpB,CAAC"}

package/dist/rag/search-knowledge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in RAG tools registered into the main agent's ToolRegistry.
+ *
+ * These tools are callable by the LLM:
+ * - `search_knowledge` — semantic search over the indexed knowledge base
+ * - `list_knowledge_documents` — list available document paths
+ */
+import type { Tool } from "../tools/types";
+import type { RAGManager } from "./rag-manager";
+/**
+ * Create the `search_knowledge` tool.
+ *
+ * The LLM calls this to find relevant context from the indexed document
+ * store before generating an answer.
+ */
+export declare function createSearchKnowledgeTool(manager: RAGManager): Tool;
+/**
+ * Create the `list_knowledge_documents` tool.
+ *
+ * The LLM can call this to discover what documents are available before
+ * performing a targeted search.
+ */
+export declare function createListKnowledgeDocumentsTool(manager: RAGManager): Tool;
+//# sourceMappingURL=search-knowledge.d.ts.map

package/dist/rag/search-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-knowledge.d.ts","sourceRoot":"","sources":["../../src/rag/search-knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAsCnE;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CA6B1E"}

package/dist/rag/search-knowledge.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Built-in RAG tools registered into the main agent's ToolRegistry.
+ *
+ * These tools are callable by the LLM:
+ * - `search_knowledge` — semantic search over the indexed knowledge base
+ * - `list_knowledge_documents` — list available document paths
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSearchKnowledgeTool = createSearchKnowledgeTool;
+exports.createListKnowledgeDocumentsTool = createListKnowledgeDocumentsTool;
+/**
+ * Create the `search_knowledge` tool.
+ *
+ * The LLM calls this to find relevant context from the indexed document
+ * store before generating an answer.
+ */
+function createSearchKnowledgeTool(manager) {
+    return {
+        name: "search_knowledge",
+        description: "Search the knowledge base for documents relevant to a query. " +
+            "Use this when you need context from the indexed documents to answer " +
+            "a question. Returns the top matching text chunks with source paths " +
+            "and similarity scores.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "The natural-language search query. Be specific — include key terms and concepts.",
+                },
+            },
+            required: ["query"],
+        },
+        execute: async (args) => {
+            const query = String(args.query ?? "").trim();
+            if (!query) {
+                return "Error: `query` is required and must be non-empty.";
+            }
+            if (!manager.indexed || manager.chunkCount === 0) {
+                return "The knowledge base is empty. No documents have been indexed yet.";
+            }
+            try {
+                const results = await manager.search(query);
+                return manager.formatResults(results);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return `Error searching knowledge base: ${message}`;
+            }
+        },
+    };
+}
+/**
+ * Create the `list_knowledge_documents` tool.
+ *
+ * The LLM can call this to discover what documents are available before
+ * performing a targeted search.
+ */
+function createListKnowledgeDocumentsTool(manager) {
+    return {
+        name: "list_knowledge_documents",
+        description: "List all documents currently indexed in the knowledge base. " +
+            "Use this to see what topics are covered before searching.",
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        execute: async (_args) => {
+            if (!manager.indexed) {
+                return "The knowledge base has not been indexed yet.";
+            }
+            const paths = manager.documentPaths;
+            if (paths.length === 0) {
+                return "No documents in the knowledge base.";
+            }
+            const lines = [
+                `${paths.length} document(s) indexed:\n`,
+                ...paths.map((p) => `- ${p}`),
+            ];
+            return lines.join("\n");
+        },
+    };
+}
+//# sourceMappingURL=search-knowledge.js.map

package/dist/rag/search-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-knowledge.js","sourceRoot":"","sources":["../../src/rag/search-knowledge.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAWH,8DAsCC;AAQD,4EA6BC;AAjFD;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,OAAmB;IAC3D,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,+DAA+D;YAC/D,sEAAsE;YACtE,qEAAqE;YACrE,wBAAwB;QAC1B,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,kFAAkF;iBACrF;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;QACD,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAmB,EAAE;YAChE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,mDAAmD,CAAC;YAC7D,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;gBACjD,OAAO,kEAAkE,CAAC;YAC5E,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5C,OAAO,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO,mCAAmC,OAAO,EAAE,CAAC;YACtD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gCAAgC,CAAC,OAAmB;IAClE,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,WAAW,EACT,8DAA8D;YAC9D,2DAA2D;QAC7D,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;YACd,QAAQ,EAAE,EAAE;SACb;QACD,OAAO,EAAE,KAAK,EAAE,KAA8B,EAAmB,EAAE;YACjE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACrB,OAAO,8CAA8C,CAAC;YACxD,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;YACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,qCAAqC,CAAC;YAC/C,CAAC;YAED,MAAM,KAAK,GAAa;gBACtB,GAAG,KAAK,CAAC,MAAM,yBAAyB;gBACxC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;aAC9B,CAAC;YAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/rag/text-splitter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Recursive priority-based text splitter.
+ *
+ * Splits text into chunks by trying separators in priority order:
+ *   1. Markdown heading boundaries  (##, ###)
+ *   2. Paragraph boundaries         (double newline)
+ *   3. Sentence endings             (。！？. ! ? + single newline)
+ *   4. Clause pauses                (；，、, ; :)
+ *   5. Hard cutoff                  (character-level, last resort)
+ *
+ * At each level the splitter finds the last separator within the chunk_size
+ * window and breaks there. If no separator is found, it falls back to the
+ * next priority level.
+ *
+ * Chunks overlap: adjacent chunks share `chunkOverlap` characters of context.
+ * The overlap boundary also respects separator priorities.
+ */
+/**
+ * Split `text` into chunks not exceeding `chunkSize` characters,
+ * with `chunkOverlap` characters of context between adjacent chunks.
+ *
+ * Returns an array of chunk text strings (no empty strings).
+ */
+export declare function splitText(text: string, chunkSize: number, chunkOverlap: number): string[];
+//# sourceMappingURL=text-splitter.d.ts.map

package/dist/rag/text-splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-splitter.d.ts","sourceRoot":"","sources":["../../src/rag/text-splitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAqBH;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,EAAE,CA8BV"}

package/dist/rag/text-splitter.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Recursive priority-based text splitter.
+ *
+ * Splits text into chunks by trying separators in priority order:
+ *   1. Markdown heading boundaries  (##, ###)
+ *   2. Paragraph boundaries         (double newline)
+ *   3. Sentence endings             (。！？. ! ? + single newline)
+ *   4. Clause pauses                (；，、, ; :)
+ *   5. Hard cutoff                  (character-level, last resort)
+ *
+ * At each level the splitter finds the last separator within the chunk_size
+ * window and breaks there. If no separator is found, it falls back to the
+ * next priority level.
+ *
+ * Chunks overlap: adjacent chunks share `chunkOverlap` characters of context.
+ * The overlap boundary also respects separator priorities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitText = splitText;
+// ─── Separator definitions ───────────────────────────────────────────────────
+/**
+ * Separators at each priority level (ordered highest → lowest).
+ * Each entry is a list of equivalent separators.
+ */
+const SEPARATOR_PRIORITIES = [
+    // Priority 1: Markdown heading boundaries
+    ["\n## ", "\n### ", "\n#### ", "\n# "],
+    // Priority 2: Paragraph boundaries
+    ["\n\n", "\r\n\r\n"],
+    // Priority 3: Sentence endings (Chinese + English)
+    ["。", "！", "？", ". ", "! ", "? ", "\n", ".\n", "!\n", "?\n"],
+    // Priority 4: Clause pauses
+    ["；", "，", "：", "、", "; ", ", ", ": ", ";\n", ",\n"],
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Split `text` into chunks not exceeding `chunkSize` characters,
+ * with `chunkOverlap` characters of context between adjacent chunks.
+ *
+ * Returns an array of chunk text strings (no empty strings).
+ */
+function splitText(text, chunkSize, chunkOverlap) {
+    if (text.trim().length === 0)
+        return [];
+    if (text.length <= chunkSize)
+        return [text];
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        // How far ahead we can look for a split point
+        const windowEnd = Math.min(start + chunkSize, text.length);
+        // If the remainder fits in one chunk, take it all
+        if (windowEnd >= text.length) {
+            const remainder = text.slice(start).trim();
+            if (remainder.length > 0)
+                chunks.push(remainder);
+            break;
+        }
+        // Find the best split point within [start, windowEnd]
+        const splitAt = findSplitPoint(text, start, windowEnd);
+        const chunk = text.slice(start, splitAt).trim();
+        if (chunk.length > 0)
+            chunks.push(chunk);
+        // Advance start: split point minus overlap, bounded by previous start
+        const overlapStart = findOverlapStart(text, splitAt, start, chunkOverlap);
+        start = overlapStart;
+    }
+    return chunks;
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Find the best split position within the window [start, windowEnd].
+ *
+ * Tries each priority level; returns the position of the *last* matching
+ * separator + its length (so the separator stays with the left chunk).
+ * Falls back to `windowEnd` (hard cut) if no separator is found.
+ */
+function findSplitPoint(text, start, windowEnd) {
+    for (const separators of SEPARATOR_PRIORITIES) {
+        let bestPos = -1;
+        let bestSepLen = 0;
+        for (const sep of separators) {
+            // Search backwards from windowEnd for the last occurrence of this separator
+            let pos = text.lastIndexOf(sep, windowEnd);
+            while (pos >= start && pos + sep.length > windowEnd) {
+                // Separator straddles the window boundary — try earlier
+                pos = text.lastIndexOf(sep, pos - 1);
+            }
+            if (pos >= start && pos > bestPos) {
+                bestPos = pos;
+                bestSepLen = sep.length;
+            }
+        }
+        if (bestPos >= start) {
+            return bestPos + bestSepLen; // Include the separator in the left chunk
+        }
+    }
+    // Last resort: hard cut at windowEnd
+    return windowEnd;
+}
+/**
+ * Calculate the start position for the next chunk, accounting for overlap.
+ *
+ * From `splitAt`, step back by approximately `chunkOverlap` characters,
+ * then walk further back to the nearest high-priority separator so the
+ * overlap starts at a natural boundary.
+ */
+function findOverlapStart(text, splitAt, minStart, chunkOverlap) {
+    if (chunkOverlap <= 0)
+        return splitAt;
+    const target = Math.max(minStart, splitAt - chunkOverlap);
+    if (target <= minStart)
+        return target;
+    // Look for a natural boundary near the target position
+    for (const separators of SEPARATOR_PRIORITIES) {
+        let bestPos = -1;
+        for (const sep of separators) {
+            // Search forward from target
+            let pos = text.indexOf(sep, target);
+            if (pos >= target && pos < splitAt && (bestPos === -1 || pos < bestPos)) {
+                bestPos = pos;
+            }
+            // Also try backward from target
+            pos = text.lastIndexOf(sep, target);
+            if (pos >= minStart && (bestPos === -1 || Math.abs(pos - target) < Math.abs(bestPos - target))) {
+                bestPos = pos;
+            }
+        }
+        if (bestPos >= minStart) {
+            return bestPos + 1; // Start after the separator
+        }
+    }
+    return target;
+}
+//# sourceMappingURL=text-splitter.js.map

package/dist/rag/text-splitter.js.map

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

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

@@ -0,0 +1,34 @@
+/**
+ * In-memory vector store with cosine similarity search.
+ *
+ * Zero external dependencies — pure TypeScript implementation suitable
+ * for knowledge bases with up to ~10K chunks.
+ */
+import type { VectorStore, RAGChunk, RAGSearchResult } from "./rag-types";
+/**
+ * An in-memory vector store backed by a simple array.
+ *
+ * Search uses brute-force cosine similarity, which is fast enough
+ * for typical knowledge base sizes (a few thousand chunks).
+ */
+export declare class InMemoryVectorStore implements VectorStore {
+    private chunks;
+    add(chunks: RAGChunk[]): Promise<void>;
+    get size(): number;
+    clear(): Promise<void>;
+    /**
+     * Search for the top-K most similar chunks via cosine similarity.
+     *
+     * Returns results sorted by similarity score descending (best match first).
+     * Chunks with near-zero-norm embeddings are excluded from results.
+     */
+    search(queryEmbedding: number[], topK: number): Promise<RAGSearchResult[]>;
+}
+/**
+ * Compute cosine similarity between two vectors.
+ *
+ * Returns a value in [0, 1] for non-negative embeddings (the usual case),
+ * or [-1, 1] in the general case. Returns 0 for zero-norm vectors.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=vector-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,MAAM,CAAkB;IAE1B,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAejF;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAoBjE"}