@agenticc/core 1.0.0

package/dist/knowledge/retriever.js

@@ -0,0 +1,399 @@
+/**
+ * Knowledge Retriever
+ *
+ * Provides advanced retrieval capabilities including keyword search,
+ * semantic search, and hybrid search with knowledge sufficiency assessment.
+ *
+ * _Requirements: 3.2, 3.3, 3.4, 5.1, 5.2_
+ */
+import { cosineSimilarity } from './embedder.js';
+const DEFAULT_CONFIG = {
+    defaultTopK: 10,
+    defaultMinScore: 0.3,
+    keywordWeight: 0.3,
+    semanticWeight: 0.7,
+    sufficientThreshold: 0.7,
+    ambiguousThreshold: 0.4,
+};
+/**
+ * Knowledge Retriever class
+ *
+ * Provides keyword, semantic, and hybrid search capabilities
+ * with knowledge sufficiency assessment.
+ */
+export class Retriever {
+    store;
+    embedder;
+    config;
+    constructor(store, embedder, config) {
+        this.store = store;
+        this.embedder = embedder;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Search the knowledge base
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Array of search results sorted by relevance
+     */
+    async search(query, options) {
+        const method = options?.method ?? 'hybrid';
+        const topK = options?.topK ?? this.config.defaultTopK;
+        const minScore = options?.minScore ?? this.config.defaultMinScore;
+        const category = options?.category;
+        let results;
+        switch (method) {
+            case 'keyword':
+                results = await this.keywordSearch(query, category);
+                break;
+            case 'semantic':
+                results = await this.semanticSearch(query, category);
+                break;
+            case 'hybrid':
+            default:
+                results = await this.hybridSearch(query, category);
+                break;
+        }
+        // Filter by minimum score and limit results
+        // Results are already sorted by score descending
+        return results.filter((r) => r.score >= minScore).slice(0, topK);
+    }
+    /**
+     * Keyword-based search using text matching
+     *
+     * Implements simple keyword matching with term frequency scoring.
+     * Supports category filtering.
+     *
+     * _Requirements: 3.4_
+     *
+     * @param query - Search query
+     * @param category - Optional category filter
+     * @returns Search results sorted by score descending
+     */
+    async keywordSearch(query, category) {
+        const documents = await this.store.getAllDocuments();
+        const matches = this.performKeywordMatch(query, documents, category);
+        // Convert to SearchResult and sort by score descending
+        return matches
+            .map((match) => ({
+            document: match.document,
+            score: match.score,
+            confidence: this.scoreToConfidence(match.score),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Perform keyword matching on documents
+     */
+    performKeywordMatch(query, documents, category) {
+        const queryLower = query.toLowerCase();
+        const queryTerms = this.tokenize(queryLower);
+        if (queryTerms.length === 0) {
+            return [];
+        }
+        const matches = [];
+        for (const doc of documents) {
+            // Filter by category if specified
+            if (category && doc.category !== category) {
+                continue;
+            }
+            const contentLower = doc.content.toLowerCase();
+            const titleLower = (doc.title ?? '').toLowerCase();
+            const combinedText = `${titleLower} ${contentLower}`;
+            // Calculate term frequency score
+            const matchedTerms = [];
+            let totalScore = 0;
+            for (const term of queryTerms) {
+                // Check for exact term match
+                if (combinedText.includes(term)) {
+                    matchedTerms.push(term);
+                    // Count occurrences for TF scoring
+                    const regex = new RegExp(this.escapeRegex(term), 'gi');
+                    const occurrences = (combinedText.match(regex) || []).length;
+                    // TF score with diminishing returns
+                    totalScore += Math.log(1 + occurrences);
+                    // Boost for title matches
+                    if (titleLower.includes(term)) {
+                        totalScore += 0.5;
+                    }
+                }
+            }
+            if (matchedTerms.length > 0) {
+                // Normalize score by query length and document length
+                const coverageScore = matchedTerms.length / queryTerms.length;
+                const lengthNorm = 1 / Math.sqrt(combinedText.length / 1000 + 1);
+                const finalScore = Math.min(1, (totalScore * coverageScore * lengthNorm) / queryTerms.length);
+                matches.push({
+                    document: doc,
+                    score: finalScore,
+                    matchedTerms,
+                });
+            }
+        }
+        return matches;
+    }
+    /**
+     * Semantic search using embedding similarity
+     *
+     * Uses vector similarity to find semantically related documents.
+     * Falls back to keyword search if embedder is not available.
+     *
+     * _Requirements: 3.3_
+     *
+     * @param query - Search query
+     * @param category - Optional category filter
+     * @returns Search results sorted by score descending
+     */
+    async semanticSearch(query, category) {
+        // Fall back to keyword search if no embedder
+        if (!this.embedder) {
+            return this.keywordSearch(query, category);
+        }
+        // Generate query embedding
+        let queryEmbedding;
+        try {
+            const result = await this.embedder.embed(query);
+            queryEmbedding = result.embedding;
+        }
+        catch (error) {
+            console.warn('Failed to generate query embedding, falling back to keyword search:', error);
+            return this.keywordSearch(query, category);
+        }
+        const documents = await this.store.getAllDocuments();
+        const matches = await this.performSemanticMatch(queryEmbedding, documents, category);
+        // Convert to SearchResult and sort by score descending
+        return matches
+            .map((match) => ({
+            document: match.document,
+            score: match.score,
+            confidence: this.scoreToConfidence(match.score),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Perform semantic matching on documents
+     */
+    async performSemanticMatch(queryEmbedding, documents, category) {
+        const matches = [];
+        for (const doc of documents) {
+            // Filter by category if specified
+            if (category && doc.category !== category) {
+                continue;
+            }
+            // Get document embedding from store
+            const docEmbedding = this.store.getEmbedding(doc.id);
+            if (!docEmbedding || docEmbedding.length === 0) {
+                continue;
+            }
+            // Calculate cosine similarity
+            try {
+                const similarity = cosineSimilarity(queryEmbedding, docEmbedding);
+                // Normalize to 0-1 range (cosine similarity is -1 to 1)
+                const normalizedScore = (similarity + 1) / 2;
+                matches.push({
+                    document: doc,
+                    score: normalizedScore,
+                    embedding: docEmbedding,
+                });
+            }
+            catch (error) {
+                // Skip documents with incompatible embeddings
+                console.warn(`Skipping document ${doc.id} due to embedding error:`, error);
+            }
+        }
+        return matches;
+    }
+    /**
+     * Hybrid search combining keyword and semantic results
+     *
+     * Merges results from both methods with configurable weights.
+     * Deduplicates and re-ranks results.
+     *
+     * _Requirements: 3.2_
+     *
+     * @param query - Search query
+     * @param category - Optional category filter
+     * @returns Search results sorted by combined score descending
+     */
+    async hybridSearch(query, category) {
+        // Get results from both methods
+        const keywordResults = await this.keywordSearch(query, category);
+        const semanticResults = await this.semanticSearch(query, category);
+        // Merge results with weighted scores
+        const scoreMap = new Map();
+        for (const result of keywordResults) {
+            scoreMap.set(result.document.id, {
+                keyword: result.score,
+                semantic: 0,
+                document: result.document,
+            });
+        }
+        for (const result of semanticResults) {
+            const existing = scoreMap.get(result.document.id);
+            if (existing) {
+                existing.semantic = result.score;
+            }
+            else {
+                scoreMap.set(result.document.id, {
+                    keyword: 0,
+                    semantic: result.score,
+                    document: result.document,
+                });
+            }
+        }
+        // Calculate combined scores
+        const results = [];
+        for (const [, scores] of scoreMap.entries()) {
+            const combinedScore = scores.keyword * this.config.keywordWeight + scores.semantic * this.config.semanticWeight;
+            results.push({
+                document: scores.document,
+                score: combinedScore,
+                confidence: this.scoreToConfidence(combinedScore),
+            });
+        }
+        // Sort by score descending
+        return results.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Assess knowledge sufficiency for a given intent
+     *
+     * Evaluates whether the retrieved knowledge is sufficient
+     * to answer the user's query.
+     *
+     * _Requirements: 5.1, 5.2_
+     *
+     * @param results - Search results to assess
+     * @param intent - User intent information
+     * @returns Knowledge assessment with status and confidence
+     */
+    assessKnowledge(results, intent) {
+        // No results - insufficient knowledge
+        if (results.length === 0) {
+            return {
+                status: 'insufficient',
+                confidence: 0,
+                missingTopic: intent.requiredTopics?.[0] ?? intent.action,
+            };
+        }
+        // Calculate overall confidence from top results
+        const topResults = results.slice(0, 5);
+        const avgScore = topResults.reduce((sum, r) => sum + r.score, 0) / topResults.length;
+        const maxScore = Math.max(...topResults.map((r) => r.score));
+        // Check if required topics are covered
+        const coveredTopics = this.findCoveredTopics(results, intent);
+        const requiredTopics = intent.requiredTopics ?? [intent.action];
+        const missingTopics = requiredTopics.filter((t) => !coveredTopics.has(t.toLowerCase()));
+        // Determine status based on scores and coverage
+        if (maxScore >= this.config.sufficientThreshold && missingTopics.length === 0) {
+            return {
+                status: 'sufficient',
+                confidence: avgScore,
+            };
+        }
+        if (maxScore >= this.config.ambiguousThreshold) {
+            // Check for ambiguity - multiple high-scoring but different results
+            const highScoreResults = results.filter((r) => r.score >= this.config.ambiguousThreshold);
+            if (highScoreResults.length > 1) {
+                const categories = new Set(highScoreResults.map((r) => r.document.category));
+                if (categories.size > 1) {
+                    // Multiple categories with high scores - ambiguous
+                    return {
+                        status: 'ambiguous',
+                        confidence: avgScore,
+                        alternatives: Array.from(categories).map((cat) => ({
+                            interpretation: cat,
+                            confidence: highScoreResults
+                                .filter((r) => r.document.category === cat)
+                                .reduce((sum, r) => sum + r.score, 0) / highScoreResults.length,
+                        })),
+                    };
+                }
+            }
+            // Partial coverage
+            if (missingTopics.length > 0) {
+                return {
+                    status: 'insufficient',
+                    confidence: avgScore,
+                    missingTopic: missingTopics[0],
+                };
+            }
+            return {
+                status: 'sufficient',
+                confidence: avgScore,
+            };
+        }
+        // Low scores - insufficient
+        return {
+            status: 'insufficient',
+            confidence: avgScore,
+            missingTopic: missingTopics[0] ?? intent.action,
+        };
+    }
+    /**
+     * Find topics covered by search results
+     */
+    findCoveredTopics(results, intent) {
+        const covered = new Set();
+        for (const result of results) {
+            const content = `${result.document.title ?? ''} ${result.document.content}`.toLowerCase();
+            // Check action
+            if (content.includes(intent.action.toLowerCase())) {
+                covered.add(intent.action.toLowerCase());
+            }
+            // Check entities
+            for (const entity of intent.entities) {
+                if (content.includes(entity.toLowerCase())) {
+                    covered.add(entity.toLowerCase());
+                }
+            }
+            // Check required topics
+            for (const topic of intent.requiredTopics ?? []) {
+                if (content.includes(topic.toLowerCase())) {
+                    covered.add(topic.toLowerCase());
+                }
+            }
+            // Add category as covered topic
+            covered.add(result.document.category.toLowerCase());
+        }
+        return covered;
+    }
+    /**
+     * Tokenize text into search terms
+     */
+    tokenize(text) {
+        return text
+            .split(/\s+/)
+            .map((t) => t.replace(/[^\w\u4e00-\u9fff]/g, '')) // Keep alphanumeric and Chinese chars
+            .filter((t) => t.length > 0);
+    }
+    /**
+     * Escape special regex characters
+     */
+    escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * Convert score to confidence level
+     */
+    scoreToConfidence(score) {
+        if (score >= 0.7)
+            return 'high';
+        if (score >= 0.4)
+            return 'medium';
+        return 'low';
+    }
+    /**
+     * Get retriever configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update retriever configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+//# sourceMappingURL=retriever.js.map

package/dist/knowledge/retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../src/knowledge/retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoBjD,MAAM,cAAc,GAA8B;IAChD,WAAW,EAAE,EAAE;IACf,eAAe,EAAE,GAAG;IACpB,aAAa,EAAE,GAAG;IAClB,cAAc,EAAE,GAAG;IACnB,mBAAmB,EAAE,GAAG;IACxB,kBAAkB,EAAE,GAAG;CACxB,CAAC;AAgCF;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACZ,KAAK,CAAiB;IACtB,QAAQ,CAAY;IACpB,MAAM,CAA4B;IAE1C,YAAY,KAAqB,EAAE,QAAmB,EAAE,MAAwB;QAC9E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,QAAQ,CAAC;QAC3C,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACtD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;QAClE,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;QAEnC,IAAI,OAAuB,CAAC;QAE5B,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,SAAS;gBACZ,OAAO,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACpD,MAAM;YACR,KAAK,UAAU;gBACb,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACrD,MAAM;YACR,KAAK,QAAQ,CAAC;YACd;gBACE,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACnD,MAAM;QACV,CAAC;QAED,4CAA4C;QAC5C,iDAAiD;QACjD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,QAAiB;QAClD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAErE,uDAAuD;QACvD,OAAO,OAAO;aACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU,EAAE,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC;SAChD,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACK,mBAAmB,CACzB,KAAa,EACb,SAAqB,EACrB,QAAiB;QAEjB,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAE7C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,kCAAkC;YAClC,IAAI,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1C,SAAS;YACX,CAAC;YAED,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YACnD,MAAM,YAAY,GAAG,GAAG,UAAU,IAAI,YAAY,EAAE,CAAC;YAErD,iCAAiC;YACjC,MAAM,YAAY,GAAa,EAAE,CAAC;YAClC,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,6BAA6B;gBAC7B,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBAChC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAExB,mCAAmC;oBACnC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;oBACvD,MAAM,WAAW,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;oBAE7D,oCAAoC;oBACpC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;oBAExC,0BAA0B;oBAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC9B,UAAU,IAAI,GAAG,CAAC;oBACpB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,sDAAsD;gBACtD,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;gBAC9D,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;gBACjE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CACzB,CAAC,EACD,CAAC,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC,GAAG,UAAU,CAAC,MAAM,CAC9D,CAAC;gBAEF,OAAO,CAAC,IAAI,CAAC;oBACX,QAAQ,EAAE,GAAG;oBACb,KAAK,EAAE,UAAU;oBACjB,YAAY;iBACb,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,cAAc,CAAC,KAAa,EAAE,QAAiB;QACnD,6CAA6C;QAC7C,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QAED,2BAA2B;QAC3B,IAAI,cAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAChD,cAAc,GAAG,MAAM,CAAC,SAAS,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,qEAAqE,EAAE,KAAK,CAAC,CAAC;YAC3F,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QACrD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAErF,uDAAuD;QACvD,OAAO,OAAO;aACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU,EAAE,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC;SAChD,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB,CAChC,cAAwB,EACxB,SAAqB,EACrB,QAAiB;QAEjB,MAAM,OAAO,GAAoB,EAAE,CAAC;QAEpC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,kCAAkC;YAClC,IAAI,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1C,SAAS;YACX,CAAC;YAED,oCAAoC;YACpC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAErD,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/C,SAAS;YACX,CAAC;YAED,8BAA8B;YAC9B,IAAI,CAAC;gBACH,MAAM,UAAU,GAAG,gBAAgB,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;gBAElE,wDAAwD;gBACxD,MAAM,eAAe,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBAE7C,OAAO,CAAC,IAAI,CAAC;oBACX,QAAQ,EAAE,GAAG;oBACb,KAAK,EAAE,eAAe;oBACtB,SAAS,EAAE,YAAY;iBACxB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,8CAA8C;gBAC9C,OAAO,CAAC,IAAI,CAAC,qBAAqB,GAAG,CAAC,EAAE,0BAA0B,EAAE,KAAK,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,QAAiB;QACjD,gCAAgC;QAChC,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjE,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAEnE,qCAAqC;QACrC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqE,CAAC;QAE9F,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;YACpC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE;gBAC/B,OAAO,EAAE,MAAM,CAAC,KAAK;gBACrB,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAClD,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE;oBAC/B,OAAO,EAAE,CAAC;oBACV,QAAQ,EAAE,MAAM,CAAC,KAAK;oBACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,KAAK,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,MAAM,aAAa,GACjB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;YAE5F,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,KAAK,EAAE,aAAa;gBACpB,UAAU,EAAE,IAAI,CAAC,iBAAiB,CAAC,aAAa,CAAC;aAClD,CAAC,CAAC;QACL,CAAC;QAED,2BAA2B;QAC3B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,OAAuB,EAAE,MAAc;QACrD,sCAAsC;QACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,MAAM,EAAE,cAAc;gBACtB,UAAU,EAAE,CAAC;gBACb,YAAY,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM;aAC1D,CAAC;QACJ,CAAC;QAED,gDAAgD;QAChD,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;QACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAE7D,uCAAuC;QACvC,MAAM,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAExF,gDAAgD;QAChD,IAAI,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9E,OAAO;gBACL,MAAM,EAAE,YAAY;gBACpB,UAAU,EAAE,QAAQ;aACrB,CAAC;QACJ,CAAC;QAED,IAAI,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC/C,oEAAoE;YACpE,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;YAE1F,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAE7E,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBACxB,mDAAmD;oBACnD,OAAO;wBACL,MAAM,EAAE,WAAW;wBACnB,UAAU,EAAE,QAAQ;wBACpB,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;4BACjD,cAAc,EAAE,GAAG;4BACnB,UAAU,EACR,gBAAgB;iCACb,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,KAAK,GAAG,CAAC;iCAC1C,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,gBAAgB,CAAC,MAAM;yBACpE,CAAC,CAAC;qBACJ,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,mBAAmB;YACnB,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7B,OAAO;oBACL,MAAM,EAAE,cAAc;oBACtB,UAAU,EAAE,QAAQ;oBACpB,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;iBAC/B,CAAC;YACJ,CAAC;YAED,OAAO;gBACL,MAAM,EAAE,YAAY;gBACpB,UAAU,EAAE,QAAQ;aACrB,CAAC;QACJ,CAAC;QAED,4BAA4B;QAC5B,OAAO;YACL,MAAM,EAAE,cAAc;YACtB,UAAU,EAAE,QAAQ;YACpB,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM;SAChD,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,OAAuB,EAAE,MAAc;QAC/D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAElC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;YAE1F,eAAe;YACf,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBAClD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;YAC3C,CAAC;YAED,iBAAiB;YACjB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;oBAC3C,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YAED,wBAAwB;YACxB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;gBAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;oBAC1C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;YAED,gCAAgC;YAChC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,IAAY;QAC3B,OAAO,IAAI;aACR,KAAK,CAAC,KAAK,CAAC;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,sCAAsC;aACvF,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,GAAW;QAC7B,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,KAAa;QACrC,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO,MAAM,CAAC;QAChC,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO,QAAQ,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAgC;QAC3C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,CAAC;CACF"}

package/dist/knowledge/store.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Knowledge Store
+ *
+ * In-memory document storage with semantic search for RAG (Retrieval-Augmented Generation).
+ *
+ * **Why In-Memory?**
+ * - RAG requires fast semantic search during conversation processing
+ * - Documents are typically loaded at application startup
+ * - Embeddings are expensive to generate (cached in memory for performance)
+ * - Conversation history is stored externally (database), but knowledge is cached
+ *
+ * **Design Philosophy:**
+ * - Knowledge documents are relatively static (updated infrequently)
+ * - Fast retrieval is critical for responsive agent interactions
+ * - In-memory storage provides sub-millisecond search performance
+ * - For large knowledge bases, consider implementing pagination or lazy loading
+ *
+ * **For Production:**
+ * - Load documents at startup from files or database
+ * - Use document versioning to detect changes
+ * - Implement periodic refresh if documents change
+ * - Consider distributed caching (Redis) for multi-instance deployments
+ *
+ * Handles storage and retrieval of knowledge documents.
+ * Supports document CRUD operations with embedding generation.
+ * Includes automatic text chunking for large documents.
+ *
+ * _Requirements: 3.1, 3.5, 3.6_
+ */
+import type { Document, DocumentInput, KnowledgeBase, SearchOptions, SearchResult } from '../types/knowledge.js';
+import type { Embedder } from './embedder.js';
+import { type ChunkerConfig } from './chunker.js';
+/**
+ * Knowledge store configuration
+ */
+export interface KnowledgeStoreConfig {
+    /** Embedder instance for generating embeddings */
+    embedder?: Embedder;
+    /** Whether to generate embeddings on document add */
+    generateEmbeddings?: boolean;
+    /** Default number of results for search */
+    defaultTopK?: number;
+    /** Default minimum score for search results */
+    defaultMinScore?: number;
+    /** Chunker configuration */
+    chunkerConfig?: ChunkerConfig;
+    /** Whether to enable chunking for large documents */
+    enableChunking?: boolean;
+}
+/**
+ * In-memory Knowledge Store implementation
+ *
+ * Provides document storage with optional embedding generation
+ * and semantic search capabilities.
+ */
+export declare class KnowledgeStore implements KnowledgeBase {
+    private documents;
+    private config;
+    private chunker;
+    constructor(config?: KnowledgeStoreConfig);
+    /**
+     * Add a document to the knowledge base
+     * Generates embedding if embedder is configured
+     * Automatically chunks large documents
+     *
+     * @returns Document ID (or parent document ID if chunked)
+     */
+    addDocument(doc: DocumentInput): Promise<string>;
+    /**
+     * Add a single document (no chunking)
+     */
+    private addSingleDocument;
+    /**
+     * Add a large document by chunking it
+     */
+    private addChunkedDocument;
+    /**
+     * Get a document by ID
+     */
+    getDocument(id: string): Promise<Document | null>;
+    /**
+     * Delete a document by ID
+     */
+    deleteDocument(id: string): Promise<boolean>;
+    /**
+     * Update a document
+     */
+    updateDocument(id: string, updates: Partial<DocumentInput>): Promise<boolean>;
+    /**
+     * Search the knowledge base
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * List all categories
+     */
+    listCategories(): Promise<string[]>;
+    /**
+     * Get documents by category
+     */
+    getDocumentsByCategory(category: string): Promise<Document[]>;
+    /**
+     * Get all documents
+     */
+    getAllDocuments(): Promise<Document[]>;
+    /**
+     * Get document count
+     */
+    getDocumentCount(): number;
+    /**
+     * Check if a document has an embedding
+     */
+    hasEmbedding(id: string): boolean;
+    /**
+     * Get the embedding for a document
+     */
+    getEmbedding(id: string): number[] | undefined;
+    /**
+     * Get the embedding dimension (from first document with embedding)
+     */
+    getEmbeddingDimension(): number | undefined;
+    /**
+     * Clear all documents
+     */
+    clear(): void;
+    /**
+     * Keyword-based search using simple text matching
+     */
+    private keywordSearch;
+    /**
+     * Semantic search using embedding similarity
+     */
+    private semanticSearch;
+    /**
+     * Hybrid search combining keyword and semantic results
+     */
+    private hybridSearch;
+    /**
+     * Convert score to confidence level
+     */
+    private scoreToConfidence;
+    /**
+     * Convert stored document to public document (without embedding)
+     */
+    private toDocument;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/knowledge/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/knowledge/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,aAAa,EACb,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAgB/D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qDAAqD;IACrD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qDAAqD;IACrD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAcD;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,MAAM,CAGZ;IACF,OAAO,CAAC,OAAO,CAAc;gBAEjB,MAAM,CAAC,EAAE,oBAAoB;IAKzC;;;;;;OAMG;IACG,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAStD;;OAEG;YACW,iBAAiB;IA6C/B;;OAEG;YACW,kBAAkB;IAsChC;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAWvD;;OAEG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;OAEG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCnF;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAyB7E;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAUzC;;OAEG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAYnE;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAKjC;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAI9C;;OAEG;IACH,qBAAqB,IAAI,MAAM,GAAG,SAAS;IAS3C;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,CAAC,aAAa;IAoCrB;;OAEG;YACW,cAAc;IAmD5B;;OAEG;YACW,YAAY;IA2C1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,OAAO,CAAC,UAAU;CAWnB"}