@massa-ai/core 1.2.1

package/dist/services/context/session-file-cache.js

@@ -0,0 +1,213 @@
+/**
+ * Session File Cache
+ *
+ * Tracks which file chunks have already been delivered to an LLM in the
+ * current conversation session.  Enables diff-only context delivery:
+ *
+ *   • "new"       → first time this chunk is seen; deliver full content.
+ *   • "unchanged" → already delivered, content identical; deliver a compact
+ *                   reference token instead (~8 tokens vs hundreds).
+ *   • "changed"   → already delivered, content differs; deliver a line-level
+ *                   diff block instead of the full new content.
+ *
+ * Lifecycle:  purely in-memory (no persistence).  Sessions are evicted by
+ * LRU after MAX_SESSIONS entries or after SESSION_TTL_MS inactivity.
+ */
+import { createHash } from "crypto";
+import { logger, estimateTokens } from "@massa-ai/shared";
+import { TokenMetrics } from "../metrics/token-metrics.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Approximate token cost of a single reference tag `[CACHED: path:L1-L2]`. */
+export const REFERENCE_TOKEN_COST = 8;
+/** Maximum number of concurrent sessions kept in memory. */
+const MAX_SESSIONS = 200;
+/** Evict sessions that have been idle for more than this duration. */
+const SESSION_TTL_MS = 4 * 60 * 60 * 1000; // 4 h
+// ── Diff Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Compute a compact, positional line-level diff.
+ *
+ * Lines are compared by position.  A line pair that differs produces a
+ * `- old` / `+ new` entry.  Extra lines at the end of either side are
+ * emitted as pure additions or removals.  Identical runs are omitted to
+ * keep the diff minimal.
+ */
+function computeDiff(oldContent, newContent) {
+    if (oldContent === newContent)
+        return "";
+    const oldLines = oldContent.split("\n");
+    const newLines = newContent.split("\n");
+    const diffLines = [];
+    const maxLen = Math.max(oldLines.length, newLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        const o = oldLines[i];
+        const n = newLines[i];
+        if (o === undefined) {
+            diffLines.push(`+ ${n}`);
+        }
+        else if (n === undefined) {
+            diffLines.push(`- ${o}`);
+        }
+        else if (o !== n) {
+            diffLines.push(`- ${o}`);
+            diffLines.push(`+ ${n}`);
+        }
+        // identical lines: intentionally omitted (context-free diff)
+    }
+    return diffLines.length > 0 ? diffLines.join("\n") : "";
+}
+// ── Service ───────────────────────────────────────────────────────────────────
+/**
+ * Singleton session-scoped file chunk cache.
+ */
+export class SessionFileCache {
+    static instance = null;
+    /** sessionId  →  chunkKey  →  ChunkRecord */
+    sessions = new Map();
+    /** sessionId → last-access timestamp (ms) — used for LRU eviction */
+    lastAccess = new Map();
+    stats = {
+        totalChecks: 0,
+        cacheHits: 0,
+        unchangedHits: 0,
+        changedHits: 0,
+        totalTokensSaved: 0,
+    };
+    constructor() { }
+    static getInstance() {
+        if (!SessionFileCache.instance) {
+            SessionFileCache.instance = new SessionFileCache();
+        }
+        return SessionFileCache.instance;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Build the canonical chunk key from file metadata.
+     *
+     * @param filePath   Relative or absolute path of the file.
+     * @param lineStart  First line of the chunk (1-based).
+     * @param lineEnd    Last line of the chunk (1-based, inclusive).
+     */
+    chunkKey(filePath, lineStart, lineEnd) {
+        return `${filePath}:${lineStart}-${lineEnd}`;
+    }
+    /**
+     * Check whether a chunk should be delivered in full, as a reference token,
+     * or as a diff block.
+     *
+     * Call this once per chunk per `getOptimizedContext` invocation.  The cache
+     * is updated automatically: on a cache miss the chunk is stored; on a
+     * "changed" hit the record is updated with the new content.
+     *
+     * @param sessionId  Conversation / session identifier.
+     * @param key        Chunk key produced by `chunkKey()`.
+     * @param content    Current full text content of the chunk.
+     */
+    check(sessionId, key, content) {
+        this.touch(sessionId);
+        this.stats.totalChecks++;
+        const hash = this.hashContent(content);
+        const sessionMap = this.sessions.get(sessionId);
+        const existing = sessionMap.get(key);
+        // ── First delivery ──────────────────────────────────────────────────────
+        if (!existing) {
+            sessionMap.set(key, { hash, content, deliveredAt: Date.now() });
+            return { status: "new", tokensSaved: 0 };
+        }
+        // ── Content identical ───────────────────────────────────────────────────
+        if (existing.hash === hash) {
+            this.stats.cacheHits++;
+            this.stats.unchangedHits++;
+            const saved = Math.max(0, estimateTokens(content, "code") - REFERENCE_TOKEN_COST);
+            this.stats.totalTokensSaved += saved;
+            // Record in global TokenMetrics
+            TokenMetrics.getInstance().recordSessionCacheSavings(saved);
+            logger.debug("Session file cache: unchanged chunk", {
+                sessionId,
+                key,
+                tokensSaved: saved,
+            });
+            return { status: "unchanged", tokensSaved: saved };
+        }
+        // ── Content changed ─────────────────────────────────────────────────────
+        const diff = computeDiff(existing.content, content);
+        // Update the cached record to the latest content
+        sessionMap.set(key, { hash, content, deliveredAt: Date.now() });
+        this.stats.cacheHits++;
+        this.stats.changedHits++;
+        // Tokens saved = full content – diff (diff is usually much smaller)
+        const diffTokens = estimateTokens(diff, "code");
+        const fullTokens = estimateTokens(content, "code");
+        const saved = Math.max(0, fullTokens - diffTokens);
+        this.stats.totalTokensSaved += saved;
+        // Record in global TokenMetrics
+        TokenMetrics.getInstance().recordSessionCacheSavings(saved);
+        logger.debug("Session file cache: changed chunk", {
+            sessionId,
+            key,
+            fullTokens,
+            diffTokens,
+            tokensSaved: saved,
+        });
+        return { status: "changed", diff: diff || "(binary change)", tokensSaved: saved };
+    }
+    /**
+     * Invalidate all tracked chunks for a session.
+     * Useful when the caller explicitly requests a fresh context.
+     */
+    invalidateSession(sessionId) {
+        this.sessions.delete(sessionId);
+        this.lastAccess.delete(sessionId);
+        logger.info("Session file cache invalidated", { sessionId });
+    }
+    /** Global statistics across all sessions. */
+    getStats() {
+        return {
+            trackedSessions: this.sessions.size,
+            ...this.stats,
+        };
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    hashContent(content) {
+        return createHash("sha256").update(content, "utf8").digest("hex");
+    }
+    /** Ensure the session map exists and refresh its LRU timestamp. */
+    touch(sessionId) {
+        this.lastAccess.set(sessionId, Date.now());
+        if (!this.sessions.has(sessionId)) {
+            this.evictIfNeeded();
+            this.sessions.set(sessionId, new Map());
+            logger.debug("Session file cache: new session", { sessionId });
+        }
+    }
+    /** LRU + TTL eviction when we exceed MAX_SESSIONS. */
+    evictIfNeeded() {
+        if (this.sessions.size < MAX_SESSIONS)
+            return;
+        const now = Date.now();
+        // Phase 1: remove stale sessions (idle > TTL)
+        for (const [id, ts] of this.lastAccess) {
+            if (now - ts > SESSION_TTL_MS) {
+                this.sessions.delete(id);
+                this.lastAccess.delete(id);
+            }
+        }
+        // Phase 2: if still at capacity, evict the least-recently-used session
+        if (this.sessions.size >= MAX_SESSIONS) {
+            let lruId = null;
+            let lruTs = Infinity;
+            for (const [id, ts] of this.lastAccess) {
+                if (ts < lruTs) {
+                    lruTs = ts;
+                    lruId = id;
+                }
+            }
+            if (lruId) {
+                this.sessions.delete(lruId);
+                this.lastAccess.delete(lruId);
+                logger.debug("Session file cache: LRU eviction", { evictedSession: lruId });
+            }
+        }
+    }
+}
+//# sourceMappingURL=session-file-cache.js.map

package/dist/services/context/session-file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-file-cache.js","sourceRoot":"","sources":["../../../src/services/context/session-file-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,iFAAiF;AAEjF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,sEAAsE;AACtE,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM;AAsCjD,iFAAiF;AAEjF;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,UAAkB,EAAE,UAAkB;IACzD,IAAI,UAAU,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAEtB,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAC3B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACzB,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;QACD,6DAA6D;IAC/D,CAAC;IAED,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,iFAAiF;AAEjF;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAC,QAAQ,GAA4B,IAAI,CAAC;IAExD,6CAA6C;IAC5B,QAAQ,GAAG,IAAI,GAAG,EAAoC,CAAC;IAExE,qEAAqE;IACpD,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvC,KAAK,GAAG;QACvB,WAAW,EAAE,CAAC;QACd,SAAS,EAAE,CAAC;QACZ,aAAa,EAAE,CAAC;QAChB,WAAW,EAAE,CAAC;QACd,gBAAgB,EAAE,CAAC;KACpB,CAAC;IAEF,gBAAuB,CAAC;IAExB,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC;YAC/B,gBAAgB,CAAC,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACrD,CAAC;QACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,8EAA8E;IAE9E;;;;;;OAMG;IACH,QAAQ,CAAC,QAAgB,EAAE,SAAiB,EAAE,OAAe;QAC3D,OAAO,GAAG,QAAQ,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,SAAiB,EAAE,GAAW,EAAE,OAAe;QACnD,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,2EAA2E;QAC3E,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAChE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QAC3C,CAAC;QAED,2EAA2E;QAC3E,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,EACD,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,oBAAoB,CACvD,CAAC;YACF,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC;YAErC,gCAAgC;YAChC,YAAY,CAAC,WAAW,EAAE,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC;YAE5D,MAAM,CAAC,KAAK,CAAC,qCAAqC,EAAE;gBAClD,SAAS;gBACT,GAAG;gBACH,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QACrD,CAAC;QAED,2EAA2E;QAC3E,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpD,iDAAiD;QACjD,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAEhE,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACzB,oEAAoE;QACpE,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC;QAErC,gCAAgC;QAChC,YAAY,CAAC,WAAW,EAAE,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC;QAE5D,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE;YAChD,SAAS;YACT,GAAG;YACH,UAAU;YACV,UAAU;YACV,WAAW,EAAE,KAAK;SACnB,CAAC,CAAC;QAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,IAAI,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACpF,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,SAAiB;QACjC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,6CAA6C;IAC7C,QAAQ;QACN,OAAO;YACL,eAAe,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;YACnC,GAAG,IAAI,CAAC,KAAK;SACd,CAAC;IACJ,CAAC;IAED,8EAA8E;IAEtE,WAAW,CAAC,OAAe;QACjC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,CAAC;IAED,mEAAmE;IAC3D,KAAK,CAAC,SAAiB;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,sDAAsD;IAC9C,aAAa;QACnB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,YAAY;YAAE,OAAO;QAE9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,8CAA8C;QAC9C,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,IAAI,GAAG,GAAG,EAAE,GAAG,cAAc,EAAE,CAAC;gBAC9B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACzB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QAED,uEAAuE;QACvE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;YACvC,IAAI,KAAK,GAAkB,IAAI,CAAC;YAChC,IAAI,KAAK,GAAG,QAAQ,CAAC;YACrB,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACvC,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;oBACf,KAAK,GAAG,EAAE,CAAC;oBACX,KAAK,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;YACD,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC9B,MAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;IACH,CAAC"}

package/dist/services/embeddings/cached-provider.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Cached Embedding Provider
+ *
+ * Transparent caching layer for embedding providers.
+ * Wraps any EmbeddingProvider with automatic caching using SHA-256 content hashing.
+ *
+ * Features:
+ * - Transparent cache hits (0.09ms average latency)
+ * - Automatic cache misses fallback to base provider
+ * - Batch operation support with partial cache hits
+ * - Cache statistics tracking (hits, misses, hit rate)
+ *
+ * Based on OpenClaw's EmbeddingCache pattern.
+ */
+import type { EmbeddingProvider } from "./provider.js";
+import type { EmbeddingProviderConfig } from "./config.js";
+import type { EmbeddingCacheStore } from "../cache/embedding-cache-contract.js";
+/**
+ * Cache statistics for monitoring performance
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    totalRequests: number;
+}
+/**
+ * Embedding provider with transparent caching
+ *
+ * Automatically caches embeddings using content-based SHA-256 hashing.
+ * Cache hits return in ~0.09ms, cache misses fall back to base provider.
+ */
+export declare class CachedEmbeddingProvider implements EmbeddingProvider {
+    private readonly baseProvider;
+    private readonly cache;
+    readonly id: string;
+    readonly model: string;
+    readonly dimensions: number;
+    private hits;
+    private misses;
+    constructor(baseProvider: EmbeddingProvider, cache: EmbeddingCacheStore);
+    /**
+     * Embed a single query with caching
+     *
+     * Flow:
+     * 1. Check cache (SHA-256 hash of text)
+     * 2. If hit: return cached embedding (~0.09ms)
+     * 3. If miss: call base provider, cache result, return
+     */
+    embedQuery(text: string): Promise<number[]>;
+    /**
+     * Embed batch with partial cache hits
+     *
+     * Optimized flow:
+     * 1. Check cache for all texts (parallel)
+     * 2. Identify cache misses
+     * 3. Batch embed only misses
+     * 4. Cache new embeddings
+     * 5. Merge cached + new results in original order
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Check if base provider is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get base provider configuration
+     */
+    getConfig(): EmbeddingProviderConfig;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Get cache statistics from underlying cache
+     */
+    getCacheInfo(): Promise<{
+        totalEntries: number;
+        cacheSize: number;
+        hitRate: number;
+        avgDimensions: number;
+    }>;
+    /**
+     * Cleanup expired cache entries
+     *
+     * @param maxAgeMs Maximum age in milliseconds (default: 7 days)
+     */
+    cleanup(maxAgeMs?: number): Promise<number>;
+}
+/**
+ * Factory function to wrap a provider with caching
+ */
+export declare function withCache(provider: EmbeddingProvider, cache: EmbeddingCacheStore): CachedEmbeddingProvider;
+//# sourceMappingURL=cached-provider.d.ts.map

package/dist/services/embeddings/cached-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-provider.d.ts","sourceRoot":"","sources":["../../../src/services/embeddings/cached-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAS7D,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IATxB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAGA,YAAY,EAAE,iBAAiB,EAC/B,KAAK,EAAE,mBAAmB;IAO7C;;;;;;;OAOG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkBjD;;;;;;;;;OASG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAoDtD;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;OAEG;IACH,SAAS,IAAI,uBAAuB;IAIpC;;OAEG;IACH,QAAQ,IAAI,UAAU;IAUtB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IAIF;;;;OAIG;IACG,OAAO,CAAC,QAAQ,GAAE,MAAgC,GAAG,OAAO,CAAC,MAAM,CAAC;CAG3E;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,mBAAmB,GACzB,uBAAuB,CAEzB"}

package/dist/services/embeddings/cached-provider.js

@@ -0,0 +1,162 @@
+/**
+ * Cached Embedding Provider
+ *
+ * Transparent caching layer for embedding providers.
+ * Wraps any EmbeddingProvider with automatic caching using SHA-256 content hashing.
+ *
+ * Features:
+ * - Transparent cache hits (0.09ms average latency)
+ * - Automatic cache misses fallback to base provider
+ * - Batch operation support with partial cache hits
+ * - Cache statistics tracking (hits, misses, hit rate)
+ *
+ * Based on OpenClaw's EmbeddingCache pattern.
+ */
+/**
+ * Embedding provider with transparent caching
+ *
+ * Automatically caches embeddings using content-based SHA-256 hashing.
+ * Cache hits return in ~0.09ms, cache misses fall back to base provider.
+ */
+export class CachedEmbeddingProvider {
+    baseProvider;
+    cache;
+    id;
+    model;
+    dimensions;
+    hits = 0;
+    misses = 0;
+    constructor(baseProvider, cache) {
+        this.baseProvider = baseProvider;
+        this.cache = cache;
+        this.id = `${baseProvider.id}-cached`;
+        this.model = baseProvider.model;
+        this.dimensions = baseProvider.dimensions;
+    }
+    /**
+     * Embed a single query with caching
+     *
+     * Flow:
+     * 1. Check cache (SHA-256 hash of text)
+     * 2. If hit: return cached embedding (~0.09ms)
+     * 3. If miss: call base provider, cache result, return
+     */
+    async embedQuery(text) {
+        // Try cache first
+        const cached = await this.cache.get(text);
+        if (cached && cached.length === this.dimensions) {
+            this.hits++;
+            return cached;
+        }
+        // Cache miss - call base provider
+        this.misses++;
+        const embedding = await this.baseProvider.embedQuery(text);
+        // Cache for future requests
+        await this.cache.set(text, embedding);
+        return embedding;
+    }
+    /**
+     * Embed batch with partial cache hits
+     *
+     * Optimized flow:
+     * 1. Check cache for all texts (parallel)
+     * 2. Identify cache misses
+     * 3. Batch embed only misses
+     * 4. Cache new embeddings
+     * 5. Merge cached + new results in original order
+     */
+    async embedBatch(texts) {
+        if (texts.length === 0) {
+            return [];
+        }
+        // Try to get all from cache
+        const cachedResults = await this.cache.getBatch(texts);
+        // Identify misses
+        const missIndices = [];
+        const missTexts = [];
+        cachedResults.forEach((cached, idx) => {
+            if (cached === null || cached.length !== this.dimensions) {
+                missIndices.push(idx);
+                missTexts.push(texts[idx]);
+            }
+            else {
+                this.hits++;
+            }
+        });
+        // If all cached, return immediately
+        if (missTexts.length === 0) {
+            return cachedResults;
+        }
+        // Embed misses only
+        this.misses += missTexts.length;
+        const newEmbeddings = await this.baseProvider.embedBatch(missTexts);
+        // Cache new embeddings
+        await this.cache.setBatch(missTexts, newEmbeddings);
+        // Merge results maintaining original order
+        const results = [];
+        let missIdx = 0;
+        for (let i = 0; i < texts.length; i++) {
+            if (cachedResults[i] !== null &&
+                cachedResults[i].length === this.dimensions) {
+                results.push(cachedResults[i]);
+            }
+            else {
+                results.push(newEmbeddings[missIdx]);
+                missIdx++;
+            }
+        }
+        return results;
+    }
+    /**
+     * Check if base provider is available
+     */
+    async isAvailable() {
+        return this.baseProvider.isAvailable();
+    }
+    /**
+     * Get base provider configuration
+     */
+    getConfig() {
+        return this.baseProvider.getConfig();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const totalRequests = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: totalRequests > 0 ? this.hits / totalRequests : 0,
+            totalRequests,
+        };
+    }
+    /**
+     * Reset statistics counters
+     */
+    resetStats() {
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Get cache statistics from underlying cache
+     */
+    async getCacheInfo() {
+        return this.cache.getStats();
+    }
+    /**
+     * Cleanup expired cache entries
+     *
+     * @param maxAgeMs Maximum age in milliseconds (default: 7 days)
+     */
+    async cleanup(maxAgeMs = 7 * 24 * 60 * 60 * 1000) {
+        return this.cache.cleanup(maxAgeMs);
+    }
+}
+/**
+ * Factory function to wrap a provider with caching
+ */
+export function withCache(provider, cache) {
+    return new CachedEmbeddingProvider(provider, cache);
+}
+//# sourceMappingURL=cached-provider.js.map

package/dist/services/embeddings/cached-provider.js.map

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

package/dist/services/embeddings/config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Embedding Provider Configuration
+ *
+ * Multi-provider configuration using Vercel AI SDK
+ * Supports: OpenAI, Google, Cohere, Ollama (local), Mistral
+ */
+export interface EmbeddingProviderConfig {
+    provider: "openai" | "google" | "cohere" | "ollama" | "mistral" | "vercel" | "custom" | "litellm" | string;
+    model: string;
+    apiKey?: string;
+    baseURL?: string;
+    dimensions?: number;
+    priority: number;
+    timeout?: number;
+    maxRetries?: number;
+    maxChars?: number;
+    rateLimits?: {
+        requestsPerMinute?: number;
+        tokensPerMinute?: number;
+        requestsPerDay?: number;
+        batchSize?: number;
+        batchDelayMs?: number;
+    };
+}
+/**
+ * Get rate limits from environment variables for a provider
+ *
+ * Supports provider-specific env vars:
+ * - {PROVIDER}_EMBEDDING_RPM - Requests per minute
+ * - {PROVIDER}_EMBEDDING_TPM - Tokens per minute
+ * - {PROVIDER}_EMBEDDING_RPD - Requests per day
+ * - {PROVIDER}_EMBEDDING_BATCH_SIZE - Max texts per batch
+ * - {PROVIDER}_EMBEDDING_BATCH_DELAY - Delay between batches (ms)
+ *
+ * Falls back to generic EMBEDDING_* vars if provider-specific not set
+ */
+export declare function getRateLimits(providerPrefix: string): EmbeddingProviderConfig['rateLimits'];
+export declare function getMaxChars(providerPrefix: string, model: string): number;
+/**
+ * Provider configurations sorted by priority
+ *
+ * Priority order (default):
+ * 1. Ollama (local, low latency) - ENABLED
+ * 2. Mistral Text (general purpose, good quality) - ENABLED
+ * 3. Mistral Code (specialized for code) - ENABLED
+ * 4. Google (API key required) - ENABLED if GOOGLE_API_KEY is set
+ *
+ * Override with EMBEDDING_PROVIDER env var:
+ * - EMBEDDING_PROVIDER=google - Force Google
+ * - EMBEDDING_PROVIDER=ollama - Force Ollama
+ * - EMBEDDING_PROVIDER=mistral - Force Mistral
+ *
+ * Rate Limiting (all providers):
+ * Set provider-specific vars (e.g., GOOGLE_EMBEDDING_RPM) or generic vars (e.g., EMBEDDING_RPM)
+ *
+ * DISABLED (no API keys configured):
+ * - OpenAI (no API key)
+ * - Cohere (no API key)
+ */
+export declare const embeddingProviders: Record<string, EmbeddingProviderConfig>;
+/**
+ * Get providers sorted by priority
+ */
+export declare function getProvidersByPriority(): Array<[
+    string,
+    EmbeddingProviderConfig
+]>;
+/**
+ * Check if provider has required API key or is a local provider
+ */
+export declare function hasApiKey(providerName: string): boolean;
+/**
+ * Retry configuration (OpenClaw pattern)
+ */
+export declare const RETRY_CONFIG: {
+    MAX_ATTEMPTS: number;
+    BASE_DELAY_MS: number;
+    MAX_DELAY_MS: number;
+    BACKOFF_MULTIPLIER: number;
+};
+/**
+ * Batching configuration (OpenClaw pattern)
+ */
+export declare const BATCH_CONFIG: {
+    MAX_TOKENS: number;
+    APPROX_CHARS_PER_TOKEN: number;
+    CONCURRENCY: number;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/services/embeddings/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/services/embeddings/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3G,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE;QACX,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,uBAAuB,CAAC,YAAY,CAAC,CA0D3F;AAED,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAsLtE,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,KAAK,CAC7C;IAAC,MAAM;IAAE,uBAAuB;CAAC,CAClC,CAIA;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAuCvD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;CAKxB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY;;;;CAIxB,CAAC"}