@mcp-abap-adt/llm-agent 6.0.2 → 8.0.0

package/dist/smart-agent/rag/search-strategy.js

@@ -0,0 +1,200 @@
+// ---------------------------------------------------------------------------
+// Module-private helpers (reused by all strategies in this file)
+// ---------------------------------------------------------------------------
+function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] ** 2;
+        nb += b[i] ** 2;
+    }
+    return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}
+function bm25(queryTokens, docText, context) {
+    const docTokens = context.tokenize(docText);
+    if (queryTokens.length === 0 || docTokens.length === 0)
+        return 0;
+    const avgDocLength = context.index.avgDocLength || 1;
+    const n = context.index.docCount || 1;
+    const k1 = 1.2;
+    const b = 0.75;
+    let score = 0;
+    for (const token of new Set(queryTokens)) {
+        const df = context.index.getDocFrequency(token);
+        const idf = Math.log((n - df + 0.5) / (df + 0.5) + 1);
+        const tf = docTokens.filter((t) => t === token).length;
+        const tfScored = (tf * (k1 + 1)) /
+            (tf + k1 * (1 - b + b * (docTokens.length / avgDocLength)));
+        score += idf * tfScored;
+    }
+    return Math.min(score / 5, 1.0);
+}
+// ---------------------------------------------------------------------------
+// WeightedFusionStrategy
+// ---------------------------------------------------------------------------
+export class WeightedFusionStrategy {
+    name = 'weighted-fusion';
+    vectorWeight;
+    keywordWeight;
+    constructor(config) {
+        this.vectorWeight = config?.vectorWeight ?? 0.7;
+        this.keywordWeight = config?.keywordWeight ?? 0.3;
+    }
+    score(query, candidates, context) {
+        const queryTokens = context.tokenize(query.text);
+        return candidates
+            .map((c) => ({
+            text: c.text,
+            metadata: c.metadata,
+            score: cosine(query.vector, c.vector) * this.vectorWeight +
+                bm25(queryTokens, c.text, context) * this.keywordWeight,
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}
+// ---------------------------------------------------------------------------
+// RrfStrategy
+// ---------------------------------------------------------------------------
+/**
+ * Reciprocal Rank Fusion: combines vector and BM25 rankings using
+ * `score(doc) = 1/(k + rank_vector) + 1/(k + rank_bm25)`.
+ *
+ * RRF is rank-based — it doesn't depend on raw score magnitudes,
+ * which makes it more stable than weighted sum when vector and BM25
+ * score distributions differ.
+ */
+export class RrfStrategy {
+    name = 'rrf';
+    k;
+    constructor(config) {
+        this.k = config?.k ?? 60;
+    }
+    score(query, candidates, context) {
+        const queryTokens = context.tokenize(query.text);
+        // Score by each method independently
+        const vectorScores = candidates.map((c, i) => ({
+            idx: i,
+            score: cosine(query.vector, c.vector),
+        }));
+        const bm25Scores = candidates.map((c, i) => ({
+            idx: i,
+            score: bm25(queryTokens, c.text, context),
+        }));
+        // Sort each list desc to get ranks
+        vectorScores.sort((a, b) => b.score - a.score);
+        bm25Scores.sort((a, b) => b.score - a.score);
+        // Build rank maps (0-indexed rank)
+        const vectorRank = new Map();
+        const bm25Rank = new Map();
+        for (let i = 0; i < vectorScores.length; i++)
+            vectorRank.set(vectorScores[i].idx, i);
+        for (let i = 0; i < bm25Scores.length; i++)
+            bm25Rank.set(bm25Scores[i].idx, i);
+        // Compute RRF score
+        return candidates
+            .map((c, i) => ({
+            text: c.text,
+            metadata: c.metadata,
+            score: 1 / (this.k + (vectorRank.get(i) ?? candidates.length)) +
+                1 / (this.k + (bm25Rank.get(i) ?? candidates.length)),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}
+// ---------------------------------------------------------------------------
+// VectorOnlyStrategy
+// ---------------------------------------------------------------------------
+/**
+ * Pure vector cosine similarity. No keyword component.
+ * Useful as a baseline or when BM25 tokenization doesn't match the domain.
+ */
+export class VectorOnlyStrategy {
+    name = 'vector-only';
+    score(query, candidates, _context) {
+        return candidates
+            .map((c) => ({
+            text: c.text,
+            metadata: c.metadata,
+            score: cosine(query.vector, c.vector),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}
+// ---------------------------------------------------------------------------
+// Bm25OnlyStrategy
+// ---------------------------------------------------------------------------
+/**
+ * Pure BM25 lexical scoring. No vector component.
+ * Useful when embedder is unavailable or for exact-match-heavy domains.
+ */
+export class Bm25OnlyStrategy {
+    name = 'bm25-only';
+    score(query, candidates, context) {
+        const queryTokens = context.tokenize(query.text);
+        return candidates
+            .map((c) => ({
+            text: c.text,
+            metadata: c.metadata,
+            score: bm25(queryTokens, c.text, context),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}
+/**
+ * Combines multiple strategies via weighted Reciprocal Rank Fusion.
+ *
+ * Each child strategy scores all candidates independently.
+ * Results are merged using: `score(doc) = Σ weight_i / (k + rank_i)`
+ *
+ * All child strategies run synchronously on the same candidates —
+ * no I/O, pure CPU, single event-loop tick.
+ */
+export class CompositeStrategy {
+    name;
+    entries;
+    k;
+    constructor(entries, config) {
+        this.entries = entries;
+        this.k = config?.k ?? 60;
+        this.name = `composite(${entries.map((e) => e.strategy.name).join('+')})`;
+    }
+    score(query, candidates, context) {
+        if (candidates.length === 0)
+            return [];
+        // Run all strategies on the same candidates
+        const rankedLists = this.entries.map((entry) => {
+            const scored = entry.strategy.score(query, candidates, context);
+            // Build rank map: metadata.id → rank (0-indexed)
+            const rankMap = new Map();
+            for (let i = 0; i < scored.length; i++) {
+                const id = scored[i].metadata.id;
+                // For dual-index: same tool may appear multiple times.
+                // Keep best rank (first occurrence = highest score).
+                if (!rankMap.has(id))
+                    rankMap.set(id, i);
+            }
+            return { rankMap, weight: entry.weight };
+        });
+        // Compute weighted RRF per candidate
+        const scoreMap = new Map();
+        for (const c of candidates) {
+            const id = c.metadata.id;
+            if (scoreMap.has(id))
+                continue; // dedup by id — take first occurrence
+            let totalScore = 0;
+            for (const { rankMap, weight } of rankedLists) {
+                const rank = rankMap.get(id) ?? candidates.length;
+                totalScore += weight / (this.k + rank);
+            }
+            scoreMap.set(id, {
+                text: c.text,
+                metadata: c.metadata,
+                score: totalScore,
+            });
+        }
+        return [...scoreMap.values()].sort((a, b) => b.score - a.score);
+    }
+}
+//# sourceMappingURL=search-strategy.js.map

package/dist/smart-agent/rag/search-strategy.js.map

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

package/dist/smart-agent/rag/tool-indexing-strategy.d.ts

@@ -0,0 +1,58 @@
+import type { ILlm } from '../interfaces/llm.js';
+import type { IRequestLogger } from '../interfaces/request-logger.js';
+import type { CallOptions } from '../interfaces/types.js';
+/**
+ * A tool description to be indexed in RAG.
+ */
+export interface IToolDescriptor {
+    name: string;
+    description: string;
+}
+/**
+ * A text variant to upsert into RAG. Each variant gets its own embedding.
+ * Multiple variants per tool = broader recall.
+ */
+export interface IToolIndexEntry {
+    /** RAG record id. Format: tool:<name>[:<suffix>] */
+    id: string;
+    /** Text to embed and store. */
+    text: string;
+}
+/**
+ * Generates text variants for tool indexing in RAG.
+ * Each strategy produces one or more entries per tool.
+ * Strategies can be combined — builder upserts all entries from all strategies.
+ */
+export interface IToolIndexingStrategy {
+    readonly name: string;
+    prepare(tool: IToolDescriptor, options?: CallOptions): Promise<IToolIndexEntry[]>;
+}
+/**
+ * Indexes the raw tool description as-is.
+ * This is the current default behavior.
+ */
+export declare class OriginalToolIndexing implements IToolIndexingStrategy {
+    readonly name = "original";
+    prepare(tool: IToolDescriptor): Promise<IToolIndexEntry[]>;
+}
+/**
+ * LLM generates concise intent keywords for the tool.
+ * Indexed alongside the original for broader keyword coverage.
+ */
+export declare class IntentToolIndexing implements IToolIndexingStrategy {
+    private readonly llm;
+    private readonly requestLogger?;
+    readonly name = "intent";
+    constructor(llm: ILlm, requestLogger?: IRequestLogger | undefined);
+    prepare(tool: IToolDescriptor, options?: CallOptions): Promise<IToolIndexEntry[]>;
+}
+/**
+ * Adds action verb synonyms to the tool description.
+ * E.g. "ReadClass" → also indexed with "show class, display class, view class".
+ * Purely deterministic — no LLM needed.
+ */
+export declare class SynonymToolIndexing implements IToolIndexingStrategy {
+    readonly name = "synonym";
+    prepare(tool: IToolDescriptor): Promise<IToolIndexEntry[]>;
+}
+//# sourceMappingURL=tool-indexing-strategy.d.ts.map

package/dist/smart-agent/rag/tool-indexing-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-indexing-strategy.d.ts","sourceRoot":"","sources":["../../../src/smart-agent/rag/tool-indexing-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CACL,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC/B;AAMD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,qBAAqB;IAChE,QAAQ,CAAC,IAAI,cAAc;IAErB,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAQjE;AAmBD;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,qBAAqB;IAI5D,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAJjC,QAAQ,CAAC,IAAI,YAAY;gBAGN,GAAG,EAAE,IAAI,EACT,aAAa,CAAC,EAAE,cAAc,YAAA;IAG3C,OAAO,CACX,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC;CAqC9B;AAmBD;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,qBAAqB;IAC/D,QAAQ,CAAC,IAAI,aAAa;IAEpB,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CA6BjE"}

package/dist/smart-agent/rag/tool-indexing-strategy.js

@@ -0,0 +1,130 @@
+// ---------------------------------------------------------------------------
+// Original — current behavior: "Tool: name — description"
+// ---------------------------------------------------------------------------
+/**
+ * Indexes the raw tool description as-is.
+ * This is the current default behavior.
+ */
+export class OriginalToolIndexing {
+    name = 'original';
+    async prepare(tool) {
+        return [
+            {
+                id: `tool:${tool.name}`,
+                text: `${tool.name}: ${tool.description}`,
+            },
+        ];
+    }
+}
+// ---------------------------------------------------------------------------
+// Intent — LLM generates concise keyword phrases
+// ---------------------------------------------------------------------------
+const INTENT_PROMPT = `You receive a tool description with its name and parameters.
+Extract the core INTENT in 3-5 short keyword phrases that a user would type when needing this tool.
+Focus on WHAT the tool does, not HOW. Use simple action words.
+
+Format: return ONLY the keyword phrases separated by commas, no explanation.
+
+Examples:
+- Input: "GetTableContents: Retrieve contents (data preview) of an ABAP database table or CDS view."
+  Output: table data preview, read table contents, SE16 data, select from table, show table rows
+
+- Input: "SearchObject: Find, search, locate, or check if an ABAP repository object exists by name or wildcard pattern."
+  Output: search object by name, find ABAP object, locate program class table, does object exist, wildcard search`;
+/**
+ * LLM generates concise intent keywords for the tool.
+ * Indexed alongside the original for broader keyword coverage.
+ */
+export class IntentToolIndexing {
+    llm;
+    requestLogger;
+    name = 'intent';
+    constructor(llm, requestLogger) {
+        this.llm = llm;
+        this.requestLogger = requestLogger;
+    }
+    async prepare(tool, options) {
+        const inputText = `${tool.name}: ${tool.description}`;
+        try {
+            const chatStart = Date.now();
+            const res = await this.llm.chat([
+                { role: 'system', content: INTENT_PROMPT },
+                { role: 'user', content: inputText },
+            ], [], options);
+            if (this.requestLogger) {
+                this.requestLogger.logLlmCall({
+                    component: 'helper',
+                    model: this.llm.model ?? 'unknown',
+                    promptTokens: res.ok ? (res.value.usage?.promptTokens ?? 0) : 0,
+                    completionTokens: res.ok
+                        ? (res.value.usage?.completionTokens ?? 0)
+                        : 0,
+                    totalTokens: res.ok ? (res.value.usage?.totalTokens ?? 0) : 0,
+                    durationMs: Date.now() - chatStart,
+                });
+            }
+            if (!res.ok || !res.value.content.trim())
+                return [];
+            return [
+                {
+                    id: `tool:${tool.name}:intent`,
+                    text: `${tool.name}: ${res.value.content.trim()}`,
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Synonym — adds action verb synonyms
+// ---------------------------------------------------------------------------
+const ACTION_SYNONYMS = {
+    read: ['show', 'display', 'view', 'get', 'retrieve'],
+    create: ['add', 'new', 'make', 'generate'],
+    update: ['modify', 'change', 'edit', 'set'],
+    delete: ['remove', 'drop', 'destroy'],
+    search: ['find', 'locate', 'lookup', 'discover'],
+    list: ['show all', 'enumerate', 'browse'],
+    run: ['execute', 'start', 'launch', 'trigger'],
+    check: ['validate', 'verify', 'test', 'inspect'],
+    get: ['read', 'fetch', 'retrieve', 'show'],
+    activate: ['enable', 'publish', 'deploy'],
+};
+/**
+ * Adds action verb synonyms to the tool description.
+ * E.g. "ReadClass" → also indexed with "show class, display class, view class".
+ * Purely deterministic — no LLM needed.
+ */
+export class SynonymToolIndexing {
+    name = 'synonym';
+    async prepare(tool) {
+        const nameLower = tool.name.toLowerCase();
+        const synonymPhrases = [];
+        for (const [verb, synonyms] of Object.entries(ACTION_SYNONYMS)) {
+            if (nameLower.startsWith(verb)) {
+                const objectPart = tool.name
+                    .replace(/^[A-Z][a-z]+/, '') // Remove first word (the verb)
+                    .replace(/([A-Z])/g, ' $1') // CamelCase to spaces
+                    .trim()
+                    .toLowerCase();
+                if (objectPart) {
+                    for (const syn of synonyms) {
+                        synonymPhrases.push(`${syn} ${objectPart}`);
+                    }
+                }
+                break;
+            }
+        }
+        if (synonymPhrases.length === 0)
+            return [];
+        return [
+            {
+                id: `tool:${tool.name}:synonym`,
+                text: `${tool.name}: ${synonymPhrases.join(', ')}`,
+            },
+        ];
+    }
+}
+//# sourceMappingURL=tool-indexing-strategy.js.map

package/dist/smart-agent/rag/tool-indexing-strategy.js.map

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

package/dist/smart-agent/rag/vector-rag.d.ts

@@ -1,6 +1,8 @@
 import type { IQueryEmbedding } from '../interfaces/query-embedding.js';
 import type { IEmbedder, IPrecomputedVectorRag } from '../interfaces/rag.js';
 import { type CallOptions, RagError, type RagMetadata, type RagResult, type Result } from '../interfaces/types.js';
+import type { IDocumentEnricher, IQueryPreprocessor } from './preprocessor.js';
+import type { ISearchStrategy } from './search-strategy.js';
 export interface VectorRagConfig {
     /** Cosine similarity threshold for dedup. Default: 0.92 */
     dedupThreshold?: number;
@@ -10,6 +12,12 @@ export interface VectorRagConfig {
     vectorWeight?: number;
     /** Weight for keyword search (0..1). Default: 0.3 */
     keywordWeight?: number;
+    /** Search scoring strategy. Default: WeightedFusionStrategy with the configured weights. */
+    strategy?: ISearchStrategy;
+    /** Query preprocessors (translate, expand, etc.). Applied in order before embedding. */
+    queryPreprocessors?: IQueryPreprocessor[];
+    /** Document enrichers. Applied in order before embedding on upsert. */
+    documentEnrichers?: IDocumentEnricher[];
 }
 export declare class VectorRag implements IPrecomputedVectorRag {
     private readonly embedder;
@@ -19,6 +27,9 @@ export declare class VectorRag implements IPrecomputedVectorRag {
     private readonly namespace?;
     private vectorWeight;
     private keywordWeight;
+    private strategy;
+    private readonly queryPreprocessors;
+    private readonly documentEnrichers;
     constructor(embedder: IEmbedder, config?: VectorRagConfig);
     /** Update hybrid search weights at runtime (hot-reload). */
     updateWeights(config: {
@@ -27,11 +38,6 @@ export declare class VectorRag implements IPrecomputedVectorRag {
     }): void;
     private tokenize;
     private cosine;
-    /**
-     * BM25 Lexical Scorer.
-     * Uses pre-built InvertedIndex for O(1) DF lookups.
-     */
-    private bm25Score;
     private upsertKnownVector;
     upsert(text: string, metadata: RagMetadata, options?: CallOptions): Promise<Result<void, RagError>>;
     upsertPrecomputed(text: string, vector: number[], metadata: RagMetadata, _options?: CallOptions): Promise<Result<void, RagError>>;

package/dist/smart-agent/rag/vector-rag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-rag.d.ts","sourceRoot":"","sources":["../../../src/smart-agent/rag/vector-rag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,KAAK,WAAW,EAChB,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,wBAAwB,CAAC;AAUhC,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,SAAU,YAAW,qBAAqB;IASnD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAS;gBAGX,QAAQ,EAAE,SAAS,EACpC,MAAM,GAAE,eAAoB;IAQ9B,4DAA4D;IAC5D,aAAa,CAAC,MAAM,EAAE;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,IAAI;IAOR,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,MAAM;IAYd;;;OAGG;IACH,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,iBAAiB;IA0CnB,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,WAAW,EACrB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAsB5B,iBAAiB,CACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,WAAW,EACrB,QAAQ,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAS5B,KAAK,CACT,SAAS,EAAE,eAAe,EAC1B,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,CAAC,CAAC;IAwDnC,WAAW,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAezE,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"vector-rag.d.ts","sourceRoot":"","sources":["../../../src/smart-agent/rag/vector-rag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,KAAK,WAAW,EAChB,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,OAAO,KAAK,EAIV,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAS9B,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC1C,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACzC;AAED,qBAAa,SAAU,YAAW,qBAAqB;IAYnD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX3B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAuB;IAC1D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;gBAGrC,QAAQ,EAAE,SAAS,EACpC,MAAM,GAAE,eAAoB;IAgB9B,4DAA4D;IAC5D,aAAa,CAAC,MAAM,EAAE;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,IAAI;IAaR,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,iBAAiB;IA0CnB,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,WAAW,EACrB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IA2B5B,iBAAiB,CACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,WAAW,EACrB,QAAQ,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAS5B,KAAK,CACT,SAAS,EAAE,eAAe,EAC1B,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,CAAC,CAAC;IAgEnC,WAAW,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAezE,KAAK,IAAI,IAAI;CAId"}

package/dist/smart-agent/rag/vector-rag.js

@@ -1,6 +1,7 @@
 import { RagError, } from '../interfaces/types.js';
 import { InvertedIndex } from './inverted-index.js';
-import { FallbackQueryEmbedding } from './query-embedding.js';
+import { FallbackQueryEmbedding, QueryEmbedding } from './query-embedding.js';
+import { WeightedFusionStrategy } from './search-strategy.js';
 export class VectorRag {
     embedder;
     records = [];
@@ -9,12 +10,23 @@ export class VectorRag {
     namespace;
     vectorWeight;
     keywordWeight;
+    strategy;
+    queryPreprocessors;
+    documentEnrichers;
     constructor(embedder, config = {}) {
         this.embedder = embedder;
         this.dedupThreshold = config.dedupThreshold ?? 0.92;
         this.namespace = config.namespace;
         this.vectorWeight = config.vectorWeight ?? 0.7;
         this.keywordWeight = config.keywordWeight ?? 0.3;
+        this.strategy =
+            config.strategy ??
+                new WeightedFusionStrategy({
+                    vectorWeight: this.vectorWeight,
+                    keywordWeight: this.keywordWeight,
+                });
+        this.queryPreprocessors = config.queryPreprocessors ?? [];
+        this.documentEnrichers = config.documentEnrichers ?? [];
     }
     /** Update hybrid search weights at runtime (hot-reload). */
     updateWeights(config) {
@@ -22,6 +34,12 @@ export class VectorRag {
             this.vectorWeight = config.vectorWeight;
         if (config.keywordWeight !== undefined)
             this.keywordWeight = config.keywordWeight;
+        if (this.strategy.name === 'weighted-fusion') {
+            this.strategy = new WeightedFusionStrategy({
+                vectorWeight: this.vectorWeight,
+                keywordWeight: this.keywordWeight,
+            });
+        }
     }
     tokenize(s) {
         return s
@@ -40,31 +58,6 @@ export class VectorRag {
         }
         return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
     }
-    /**
-     * BM25 Lexical Scorer.
-     * Uses pre-built InvertedIndex for O(1) DF lookups.
-     */
-    bm25Score(query, text) {
-        const queryTokens = this.tokenize(query);
-        const docTokens = this.tokenize(text);
-        if (queryTokens.length === 0 || docTokens.length === 0)
-            return 0;
-        const avgDocLength = this.index.avgDocLength || 1;
-        const n = this.index.docCount || 1;
-        const k1 = 1.2;
-        const b = 0.75;
-        let score = 0;
-        for (const token of new Set(queryTokens)) {
-            const df = this.index.getDocFrequency(token);
-            const idf = Math.log((n - df + 0.5) / (df + 0.5) + 1);
-            const tf = docTokens.filter((t) => t === token).length;
-            const tfScored = (tf * (k1 + 1)) /
-                (tf + k1 * (1 - b + b * (docTokens.length / avgDocLength)));
-            score += idf * tfScored;
-        }
-        // Normalize to [0, 1] range (rough approximation for fusion)
-        return Math.min(score / 5, 1.0);
-    }
     upsertKnownVector(text, vector, metadata) {
         const newTokens = this.tokenize(text);
         // Idempotent upsert: if metadata.id matches, replace in-place
@@ -109,8 +102,14 @@ export class VectorRag {
             return { ok: true, value: undefined };
         }
         try {
-            const vector = await this.embedder.embed(text, options);
-            return this.upsertKnownVector(text, vector, metadata);
+            let enrichedText = text;
+            for (const enricher of this.documentEnrichers) {
+                const eResult = await enricher.enrich(enrichedText, options);
+                if (eResult.ok)
+                    enrichedText = eResult.value;
+            }
+            const { vector } = await this.embedder.embed(enrichedText, options);
+            return this.upsertKnownVector(enrichedText, vector, metadata);
         }
         catch (err) {
             if (err instanceof RagError)
@@ -134,15 +133,22 @@ export class VectorRag {
         }
         try {
             const text = embedding.text;
+            let searchText = text;
+            for (const pp of this.queryPreprocessors) {
+                const ppResult = await pp.process(searchText, options);
+                if (ppResult.ok)
+                    searchText = ppResult.value;
+            }
             const nowSecs = Date.now() / 1000;
-            const safe = new FallbackQueryEmbedding(embedding, this.embedder);
-            const queryVector = await safe.toVector();
+            // If preprocessors transformed the text, embed the transformed version
+            const effectiveEmbedding = searchText !== text
+                ? new QueryEmbedding(searchText, this.embedder, options)
+                : new FallbackQueryEmbedding(embedding, this.embedder);
+            const queryVector = await effectiveEmbedding.toVector();
             const targetNamespace = options?.ragFilter?.namespace;
-            const scored = this.records
-                .filter((r) => {
+            const filtered = this.records.filter((r) => {
                 if (r.metadata.ttl !== undefined && r.metadata.ttl < nowSecs)
                     return false;
-                // Apply dynamic filter from CallOptions
                 if (targetNamespace !== undefined &&
                     r.metadata.namespace !== targetNamespace)
                     return false;
@@ -151,19 +157,22 @@ export class VectorRag {
                     r.metadata.namespace !== this.namespace)
                     return false;
                 return true;
-            })
-                .map((r) => {
-                const vScore = this.cosine(queryVector, r.vector);
-                const lScore = this.bm25Score(text, r.text);
-                // Hybrid Fusion: Weighted Sum
-                const combinedScore = vScore * this.vectorWeight + lScore * this.keywordWeight;
-                return {
-                    text: r.text,
-                    metadata: r.metadata,
-                    score: combinedScore,
-                };
-            })
-                .sort((a, b) => b.score - a.score)
+            });
+            const candidates = filtered.map((r) => ({
+                text: r.text,
+                vector: r.vector,
+                metadata: r.metadata,
+            }));
+            const searchQuery = {
+                text: searchText,
+                vector: queryVector,
+            };
+            const context = {
+                index: this.index,
+                tokenize: this.tokenize.bind(this),
+            };
+            const scored = this.strategy
+                .score(searchQuery, candidates, context)
                 .slice(0, k);
             return { ok: true, value: scored };
         }