@nxuss/lemma 0.1.1 → 0.2.1

package/dist/cjs/embed/index.js

@@ -0,0 +1,989 @@
+"use strict";
+/**
+ * Lemma Embedded Mode
+ *
+ * Zero-config semantic cache for any project.
+ * No separate server, no WebSocket, no agents required.
+ *
+ * Usage:
+ *   import { Lemma } from 'lemma/embed';
+ *
+ *   const lemma = await Lemma.create();
+ *   const suggest = lemma.wrap(myOpenAIFunction);
+ *   const result = await suggest('pollo y arroz'); // cached after first call
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lemma = void 0;
+const events_1 = require("events");
+const crypto_1 = __importDefault(require("crypto"));
+// ─── Circuit Breaker ──────────────────────────────────────────────────────────
+/**
+ * Circuit Breaker implementation for backend resilience.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, requests fail fast
+ * - HALF_OPEN: Testing if backend recovered, limited requests allowed
+ */
+class BackendCircuitBreaker {
+    constructor(failureThreshold = 3, recoveryTimeout = 30000, successThreshold = 2) {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = null;
+        this.failureThreshold = failureThreshold;
+        this.recoveryTimeout = recoveryTimeout;
+        this.successThreshold = successThreshold;
+    }
+    /**
+     * Check if a request should be allowed through.
+     */
+    canAttempt() {
+        if (this.state === 'CLOSED')
+            return true;
+        if (this.state === 'OPEN') {
+            // Check if enough time has passed to try recovery
+            if (this.lastFailureTime && Date.now() - this.lastFailureTime >= this.recoveryTimeout) {
+                this.state = 'HALF_OPEN';
+                this.successCount = 0;
+                return true;
+            }
+            return false;
+        }
+        // HALF_OPEN: allow limited requests to test recovery
+        return true;
+    }
+    /**
+     * Record a successful operation.
+     */
+    recordSuccess() {
+        this.failureCount = 0;
+        if (this.state === 'HALF_OPEN') {
+            this.successCount++;
+            if (this.successCount >= this.successThreshold) {
+                this.state = 'CLOSED';
+                this.successCount = 0;
+            }
+        }
+    }
+    /**
+     * Record a failed operation.
+     */
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'HALF_OPEN') {
+            // Failed during recovery test, go back to OPEN
+            this.state = 'OPEN';
+            this.successCount = 0;
+        }
+        else if (this.failureCount >= this.failureThreshold) {
+            this.state = 'OPEN';
+        }
+    }
+    /**
+     * Get current health status.
+     */
+    getHealth() {
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailure: this.lastFailureTime,
+            successCount: this.successCount,
+        };
+    }
+    /**
+     * Reset the circuit breaker to initial state.
+     */
+    reset() {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = null;
+    }
+}
+/**
+ * Resilient wrapper for backends with circuit breaker, retries, and fallback.
+ *
+ * Features:
+ * - Circuit breaker to prevent cascading failures
+ * - Exponential backoff retries
+ * - Automatic fallback: Cloud → Chroma → Memory
+ * - Health monitoring and events
+ */
+class ResilientBackend extends events_1.EventEmitter {
+    constructor(primary, fallbacks, options = {}) {
+        super();
+        this.totalFailures = 0;
+        this.primary = primary;
+        this.fallbacks = fallbacks;
+        this.currentBackend = primary;
+        this.enableFallback = options.enableFallback ?? true;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryDelay = options.retryDelay ?? 1000;
+        this.circuitBreaker = new BackendCircuitBreaker(options.failureThreshold ?? 3, options.recoveryTimeout ?? 30000);
+    }
+    /**
+     * Execute an operation with retry logic and circuit breaker.
+     */
+    async executeWithRetry(operation, operationName) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            // Check circuit breaker
+            if (!this.circuitBreaker.canAttempt()) {
+                const error = new Error(`Circuit breaker OPEN for ${operationName}`);
+                this.emit('backend-error', { operation: operationName, error, attempt });
+                throw error;
+            }
+            try {
+                const result = await operation();
+                this.circuitBreaker.recordSuccess();
+                // If we recovered from a previous failure
+                if (this.totalFailures > 0 && this.currentBackend === this.primary) {
+                    this.emit('backend-recovered', { backend: this.getBackendName() });
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                this.circuitBreaker.recordFailure();
+                this.totalFailures++;
+                this.emit('backend-error', {
+                    operation: operationName,
+                    error,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                });
+                // Don't retry on last attempt
+                if (attempt < this.maxRetries) {
+                    const delay = this.retryDelay * Math.pow(2, attempt);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All retries exhausted, try fallback
+        if (this.enableFallback && this.fallbacks.length > 0) {
+            return this.tryFallback(operation, operationName);
+        }
+        throw lastError || new Error(`${operationName} failed after ${this.maxRetries} retries`);
+    }
+    /**
+     * Try fallback backends in order.
+     */
+    async tryFallback(operation, operationName) {
+        for (const fallback of this.fallbacks) {
+            try {
+                this.currentBackend = fallback;
+                this.emit('backend-degraded', {
+                    from: this.getBackendName(this.primary),
+                    to: this.getBackendName(fallback),
+                });
+                const result = await operation();
+                return result;
+            }
+            catch (error) {
+                this.emit('backend-error', {
+                    operation: operationName,
+                    error,
+                    backend: this.getBackendName(fallback),
+                });
+                // Continue to next fallback
+            }
+        }
+        throw new Error(`All backends failed for ${operationName}`);
+    }
+    /**
+     * Set operation with resilience.
+     */
+    async set(key, input, data, ttl) {
+        return this.executeWithRetry(() => this.currentBackend.set(key, input, data, ttl), 'set');
+    }
+    /**
+     * Find similar operation with resilience.
+     */
+    async findSimilar(input, threshold) {
+        return this.executeWithRetry(() => this.currentBackend.findSimilar(input, threshold), 'findSimilar');
+    }
+    /**
+     * Get backend health status.
+     */
+    getHealth() {
+        return {
+            ...this.circuitBreaker.getHealth(),
+            currentBackend: this.getBackendName(),
+            totalFailures: this.totalFailures,
+        };
+    }
+    /**
+     * Get current backend name.
+     */
+    getBackendName(backend) {
+        const b = backend || this.currentBackend;
+        if (b instanceof MemoryBackend)
+            return 'memory';
+        if (b instanceof ChromaBackend)
+            return 'chroma';
+        if (b instanceof CloudBackend)
+            return 'cloud';
+        return 'unknown';
+    }
+    /**
+     * Reset circuit breaker and switch back to primary.
+     */
+    reset() {
+        this.circuitBreaker.reset();
+        this.currentBackend = this.primary;
+        this.totalFailures = 0;
+    }
+    size() {
+        return this.currentBackend.size();
+    }
+    clear() {
+        this.currentBackend.clear();
+    }
+    /**
+     * Stop all backends and cleanup resources.
+     */
+    stop() {
+        // Stop primary backend if it has a stop method
+        if (this.primary instanceof MemoryBackend) {
+            this.primary.stop();
+        }
+        // Stop fallback backends
+        for (const fallback of this.fallbacks) {
+            if (fallback instanceof MemoryBackend) {
+                fallback.stop();
+            }
+        }
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+class MemoryBackend {
+    constructor(maxSize = 10000, cleanupInterval = 60000, debug = false) {
+        this.store = new Map();
+        this.cleanupTimer = null;
+        this.evictedCount = 0;
+        this.lastCleanupAt = 0;
+        this.maxSize = maxSize;
+        this.cleanupInterval = cleanupInterval;
+        this.debug = debug;
+        // Start cleanup timer if interval > 0
+        if (this.cleanupInterval > 0) {
+            this.startCleanupTimer();
+        }
+    }
+    startCleanupTimer() {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanup();
+        }, this.cleanupInterval);
+        // Prevent timer from keeping process alive
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Clean up expired entries from the store
+     */
+    cleanup() {
+        const now = Date.now();
+        let evicted = 0;
+        for (const [key, entry] of this.store.entries()) {
+            if (entry.ttl > 0 && now - entry.createdAt > entry.ttl) {
+                this.store.delete(key);
+                evicted++;
+            }
+        }
+        if (evicted > 0) {
+            this.evictedCount += evicted;
+            this.lastCleanupAt = now;
+            if (this.debug) {
+                console.log(`[Lemma] 🧹 Cleanup: evicted ${evicted} expired entries (total: ${this.evictedCount})`);
+            }
+        }
+        return evicted;
+    }
+    /**
+     * Stop cleanup timer for graceful shutdown
+     */
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+            if (this.debug) {
+                console.log('[Lemma] 🛑 Cleanup timer stopped');
+            }
+        }
+    }
+    async set(key, input, data, ttl) {
+        // Evict oldest entry if at capacity
+        if (this.store.size >= this.maxSize) {
+            const oldest = this.store.keys().next().value;
+            if (oldest) {
+                this.store.delete(oldest);
+                this.evictedCount++;
+            }
+        }
+        this.store.set(key, { key, input, data, createdAt: Date.now(), ttl });
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (entry.ttl > 0 && Date.now() - entry.createdAt > entry.ttl) {
+            this.store.delete(key);
+            this.evictedCount++;
+            return null;
+        }
+        return entry.data;
+    }
+    /**
+     * Exact key lookup — used for memory mode (no vector similarity)
+     */
+    async findSimilar(input, _threshold) {
+        // In memory mode we do exact normalized match
+        const normalized = normalizeText(input);
+        for (const entry of this.store.values()) {
+            // Check if expired
+            if (entry.ttl > 0 && Date.now() - entry.createdAt > entry.ttl) {
+                this.store.delete(entry.key);
+                this.evictedCount++;
+                continue;
+            }
+            if (normalizeText(entry.input) === normalized) {
+                return { data: entry.data, similarity: 1.0 };
+            }
+        }
+        return null;
+    }
+    size() {
+        return this.store.size;
+    }
+    getEvictedCount() {
+        return this.evictedCount;
+    }
+    getLastCleanupAt() {
+        return this.lastCleanupAt;
+    }
+    clear() {
+        this.store.clear();
+        this.evictedCount = 0;
+        this.lastCleanupAt = 0;
+    }
+}
+class SemanticMemoryBackend {
+    constructor(maxSize = 10000, modelName = 'Xenova/all-MiniLM-L6-v2') {
+        this.store = new Map();
+        this.pipeline = null;
+        this.embeddingCache = new Map();
+        this.evictedCount = 0;
+        this.maxSize = maxSize;
+        this.modelName = modelName;
+    }
+    /**
+     * Lazy-load the transformers.js pipeline
+     */
+    async initialize() {
+        if (this.pipeline)
+            return;
+        try {
+            // @ts-ignore - Optional dependency
+            const { pipeline } = await Promise.resolve().then(() => __importStar(require('@xenova/transformers')));
+            this.pipeline = await pipeline('feature-extraction', this.modelName);
+        }
+        catch (err) {
+            throw new Error(`Lemma: Could not load @xenova/transformers.\n` +
+                `Install it with: npm install @xenova/transformers\n` +
+                `Original error: ${err.message}`);
+        }
+    }
+    async set(key, input, data, ttl) {
+        await this.initialize();
+        // Evict oldest entry if at capacity
+        if (this.store.size >= this.maxSize) {
+            const oldest = this.store.keys().next().value;
+            if (oldest) {
+                this.store.delete(oldest);
+                this.evictedCount++;
+            }
+        }
+        const embedding = await this.embed(input);
+        this.store.set(key, {
+            key,
+            input,
+            embedding,
+            data,
+            createdAt: Date.now(),
+            ttl,
+        });
+    }
+    async findSimilar(input, threshold) {
+        await this.initialize();
+        if (this.store.size === 0)
+            return null;
+        const queryEmbedding = await this.embed(input);
+        let bestMatch = null;
+        let bestSimilarity = -1;
+        for (const entry of this.store.values()) {
+            // Check TTL
+            if (entry.ttl > 0 && Date.now() - entry.createdAt > entry.ttl) {
+                this.store.delete(entry.key);
+                this.evictedCount++;
+                continue;
+            }
+            const similarity = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (similarity > bestSimilarity && similarity >= threshold) {
+                bestSimilarity = similarity;
+                bestMatch = { data: entry.data, similarity };
+            }
+        }
+        return bestMatch;
+    }
+    /**
+     * Generate embedding with caching
+     */
+    async embed(text) {
+        const normalized = normalizeText(text);
+        if (this.embeddingCache.has(normalized)) {
+            return this.embeddingCache.get(normalized);
+        }
+        const output = await this.pipeline(text, {
+            pooling: 'mean',
+            normalize: true,
+        });
+        // Convert tensor to array
+        const embedding = Array.from(output.data);
+        // Cache the embedding
+        this.embeddingCache.set(normalized, embedding);
+        // Limit cache size
+        if (this.embeddingCache.size > this.maxSize) {
+            const firstKey = this.embeddingCache.keys().next().value;
+            if (firstKey)
+                this.embeddingCache.delete(firstKey);
+        }
+        return embedding;
+    }
+    size() {
+        return this.store.size;
+    }
+    getEvictedCount() {
+        return this.evictedCount;
+    }
+    getLastCleanupAt() {
+        return 0; // Semantic backend doesn't have scheduled cleanup
+    }
+    stop() {
+        // No cleanup timer to stop in semantic backend
+    }
+    clear() {
+        this.store.clear();
+        this.embeddingCache.clear();
+        this.evictedCount = 0;
+    }
+}
+/**
+ * Calculate cosine similarity between two vectors
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have the same length');
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denominator === 0)
+        return 0;
+    return dotProduct / denominator;
+}
+// ─── ChromaDB + Ollama Backend ────────────────────────────────────────────────
+class ChromaBackend {
+    constructor(chromaUrl, ollamaUrl, model, collection) {
+        this.embeddingCache = new Map();
+        // Lazy-loaded to avoid import errors when not using chroma
+        this.chromaClient = null;
+        this.chromaCollection = null;
+        this.chromaUrl = chromaUrl;
+        this.ollamaUrl = ollamaUrl;
+        this.model = model;
+        this.collection = collection;
+    }
+    async initialize() {
+        try {
+            const { ChromaClient } = await Promise.resolve().then(() => __importStar(require('chromadb')));
+            this.chromaClient = new ChromaClient({ path: this.chromaUrl });
+            this.chromaCollection = await this.chromaClient.getOrCreateCollection({
+                name: this.collection,
+                metadata: { 'hnsw:space': 'cosine' },
+            });
+        }
+        catch (err) {
+            throw new Error(`Lemma: Could not connect to ChromaDB at ${this.chromaUrl}.\n` +
+                `Make sure ChromaDB is running: chroma run --path ./chroma_data\n` +
+                `Original error: ${err.message}`);
+        }
+    }
+    async set(key, input, data, _ttl) {
+        const embedding = await this.embed(input);
+        await this.chromaCollection.add({
+            ids: [key],
+            embeddings: [embedding],
+            documents: [input],
+            metadatas: [{ data: JSON.stringify(data), timestamp: Date.now() }],
+        });
+    }
+    async findSimilar(input, threshold) {
+        const embedding = await this.embed(input);
+        const results = await this.chromaCollection.query({
+            queryEmbeddings: [embedding],
+            nResults: 1,
+            include: ['metadatas', 'distances'],
+        });
+        if (!results.ids?.[0]?.length)
+            return null;
+        const distance = results.distances[0][0];
+        const similarity = 1 - distance;
+        if (similarity < threshold)
+            return null;
+        const meta = results.metadatas[0][0];
+        return { data: JSON.parse(meta.data), similarity };
+    }
+    async embed(text) {
+        const key = normalizeText(text);
+        if (this.embeddingCache.has(key))
+            return this.embeddingCache.get(key);
+        const axios = (await Promise.resolve().then(() => __importStar(require('axios')))).default;
+        const res = await axios.post(`${this.ollamaUrl}/api/embeddings`, {
+            model: this.model,
+            prompt: text,
+        });
+        const embedding = res.data.embedding;
+        this.embeddingCache.set(key, embedding);
+        return embedding;
+    }
+    size() {
+        return 0; // ChromaDB doesn't expose sync count
+    }
+    getEvictedCount() {
+        return 0;
+    }
+    getLastCleanupAt() {
+        return 0;
+    }
+    stop() {
+        // No cleanup needed for ChromaDB
+    }
+    clear() {
+        this.embeddingCache.clear();
+    }
+}
+// ─── Cloud Backend ────────────────────────────────────────────────────────────
+class CloudBackend {
+    constructor(apiKey, cloudUrl) {
+        this.axios = null;
+        this.apiKey = apiKey;
+        this.cloudUrl = cloudUrl.replace(/\/$/, '');
+    }
+    async initialize() {
+        this.axios = (await Promise.resolve().then(() => __importStar(require('axios')))).default;
+        // Validate key on startup
+        try {
+            await this.axios.get(`${this.cloudUrl}/v1/ping`, {
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                timeout: 5000,
+            });
+        }
+        catch (err) {
+            const status = err.response?.status;
+            if (status === 401)
+                throw new Error('Lemma Cloud: Invalid API key. Check your key at https://lemma.dev');
+            if (status === 403)
+                throw new Error('Lemma Cloud: API key suspended or plan limit reached.');
+            throw new Error(`Lemma Cloud: Could not connect to ${this.cloudUrl}. ${err.message}`);
+        }
+    }
+    async set(key, input, data, ttl) {
+        await this.axios.post(`${this.cloudUrl}/v1/cache`, { key, input, data, ttl }, { headers: { Authorization: `Bearer ${this.apiKey}` }, timeout: 10000 });
+    }
+    async findSimilar(input, threshold) {
+        try {
+            const res = await this.axios.post(`${this.cloudUrl}/v1/query`, { input, threshold }, { headers: { Authorization: `Bearer ${this.apiKey}` }, timeout: 10000 });
+            if (res.data?.hit) {
+                return { data: res.data.data, similarity: res.data.similarity };
+            }
+            return null;
+        }
+        catch (err) {
+            // On cloud error, degrade gracefully — treat as miss
+            if (err.response?.status === 429)
+                throw new Error('Lemma Cloud: Rate limit exceeded. Upgrade your plan at https://lemma.dev');
+            return null;
+        }
+    }
+    size() { return -1; }
+    getEvictedCount() { return 0; }
+    getLastCleanupAt() { return 0; }
+    stop() {
+        // No cleanup needed for cloud backend
+    }
+    clear() { }
+}
+class Lemma extends events_1.EventEmitter {
+    constructor(config) {
+        super();
+        this.metrics = { hits: 0, misses: 0, totalLatency: 0 };
+        this.ready = false;
+        this.config = config;
+    }
+    /**
+     * Create and initialize a Lemma instance.
+     *
+     * @example
+     * // Zero config — in-memory cache
+     * const lemma = await Lemma.create();
+     *
+     * @example
+     * // Semantic cache with lightweight embeddings
+     * const lemma = await Lemma.create({
+     *   storage: 'semantic',
+     *   threshold: 0.85,
+     * });
+     *
+     * @example
+     * // Persistent semantic cache with ChromaDB
+     * const lemma = await Lemma.create({
+     *   storage: 'chroma',
+     *   threshold: 0.90,
+     * });
+     */
+    static async create(config = {}) {
+        const resolved = {
+            storage: config.storage ?? 'memory',
+            threshold: config.threshold ?? 0.92,
+            apiKey: config.apiKey ?? '',
+            cloudUrl: config.cloudUrl ?? 'https://api.lemma.dev',
+            chromaUrl: config.chromaUrl ?? 'http://localhost:8000',
+            ollamaUrl: config.ollamaUrl ?? 'http://localhost:11434',
+            ollamaModel: config.ollamaModel ?? 'llama3',
+            embeddingModel: config.embeddingModel ?? 'Xenova/all-MiniLM-L6-v2',
+            collection: config.collection ?? 'lemma_cache',
+            ttl: config.ttl ?? 0,
+            maxSize: config.maxSize ?? 10000,
+            cleanupInterval: config.cleanupInterval ?? 60000,
+            debug: config.debug ?? false,
+            enableFallback: config.enableFallback ?? true,
+            maxRetries: config.maxRetries ?? 3,
+            retryDelay: config.retryDelay ?? 1000,
+        };
+        const instance = new Lemma(resolved);
+        await instance.init();
+        return instance;
+    }
+    async init() {
+        let primary;
+        const fallbacks = [];
+        // Initialize primary backend based on storage config
+        if (this.config.storage === 'cloud') {
+            if (!this.config.apiKey) {
+                throw new Error('Lemma Cloud requires an API key. Get yours at https://lemma.dev\nUsage: Lemma.create({ storage: \'cloud\', apiKey: \'lk_...\' })');
+            }
+            const cloudBackend = new CloudBackend(this.config.apiKey, this.config.cloudUrl);
+            await cloudBackend.initialize();
+            primary = cloudBackend;
+            this.log('✅ Primary backend: cloud');
+            // Add fallbacks: Cloud → Chroma → Memory
+            if (this.config.enableFallback) {
+                try {
+                    const chromaBackend = new ChromaBackend(this.config.chromaUrl, this.config.ollamaUrl, this.config.ollamaModel, this.config.collection);
+                    await chromaBackend.initialize();
+                    fallbacks.push(chromaBackend);
+                    this.log('✅ Fallback backend: chroma');
+                }
+                catch (err) {
+                    this.log(`⚠️  Chroma fallback unavailable: ${err.message}`);
+                }
+                const memoryBackend = new MemoryBackend(this.config.maxSize, this.config.cleanupInterval, this.config.debug);
+                fallbacks.push(memoryBackend);
+                this.log('✅ Fallback backend: memory');
+            }
+        }
+        else if (this.config.storage === 'semantic') {
+            // Try to use semantic backend, fallback to memory if transformers not available
+            try {
+                const semanticBackend = new SemanticMemoryBackend(this.config.maxSize, this.config.embeddingModel);
+                await semanticBackend.initialize();
+                primary = semanticBackend;
+                this.log(`✅ Primary backend: semantic (model: ${this.config.embeddingModel})`);
+            }
+            catch (err) {
+                this.log(`⚠️  Semantic backend unavailable: ${err.message}`);
+                this.log('⚠️  Falling back to exact-match memory backend');
+                primary = new MemoryBackend(this.config.maxSize, this.config.cleanupInterval, this.config.debug);
+                this.log('✅ Primary backend: memory (fallback mode)');
+            }
+            // Add memory fallback for semantic
+            if (this.config.enableFallback && !(primary instanceof MemoryBackend)) {
+                const memoryBackend = new MemoryBackend(this.config.maxSize, this.config.cleanupInterval, this.config.debug);
+                fallbacks.push(memoryBackend);
+                this.log('✅ Fallback backend: memory');
+            }
+        }
+        else if (this.config.storage === 'chroma') {
+            const chromaBackend = new ChromaBackend(this.config.chromaUrl, this.config.ollamaUrl, this.config.ollamaModel, this.config.collection);
+            await chromaBackend.initialize();
+            primary = chromaBackend;
+            this.log('✅ Primary backend: chroma');
+            // Add memory fallback for chroma
+            if (this.config.enableFallback) {
+                const memoryBackend = new MemoryBackend(this.config.maxSize, this.config.cleanupInterval, this.config.debug);
+                fallbacks.push(memoryBackend);
+                this.log('✅ Fallback backend: memory');
+            }
+        }
+        else {
+            primary = new MemoryBackend(this.config.maxSize, this.config.cleanupInterval, this.config.debug);
+            this.log('✅ Primary backend: memory');
+        }
+        // Wrap primary backend with ResilientBackend (only if needed)
+        if (this.config.enableFallback || (this.config.maxRetries && this.config.maxRetries > 0)) {
+            this.backend = new ResilientBackend(primary, fallbacks, {
+                enableFallback: this.config.enableFallback,
+                maxRetries: this.config.maxRetries,
+                retryDelay: this.config.retryDelay,
+            });
+            // Forward backend events to Lemma instance
+            this.backend.on('backend-error', (data) => {
+                this.log(`❌ Backend error: ${data.operation} (attempt ${data.attempt}/${data.maxRetries})`);
+                this.emit('backend-error', data);
+            });
+            this.backend.on('backend-degraded', (data) => {
+                this.log(`⚠️  Backend degraded: ${data.from} → ${data.to}`);
+                this.emit('backend-degraded', data);
+            });
+            this.backend.on('backend-recovered', (data) => {
+                this.log(`✅ Backend recovered: ${data.backend}`);
+                this.emit('backend-recovered', data);
+            });
+            this.log('✅ Lemma ready with resilient backend');
+        }
+        else {
+            // Use primary backend directly without resilience wrapper
+            this.backend = primary;
+            this.log('✅ Lemma ready (direct backend, no resilience)');
+        }
+        this.ready = true;
+    }
+    /**
+     * Wrap any async function with semantic caching.
+     * The first argument of the function is used as the cache key.
+     *
+     * @example
+     * const cachedSuggest = lemma.wrap(async (ingredients: string) => {
+     *   return await openai.chat.completions.create({ ... });
+     * });
+     *
+     * await cachedSuggest('pollo y arroz');  // calls OpenAI
+     * await cachedSuggest('arroz con pollo'); // returns from cache ⚡
+     */
+    wrap(fn) {
+        return async (...args) => {
+            const input = args[0];
+            return this.run(input, () => fn(...args));
+        };
+    }
+    /**
+     * Manually check cache and run function if miss.
+     *
+     * @example
+     * const result = await lemma.run(
+     *   userMessage,
+     *   () => openai.chat.completions.create({ ... })
+     * );
+     * if (result.fromCache) console.log('⚡ Saved an API call!');
+     */
+    async run(input, fn) {
+        this.assertReady();
+        const start = Date.now();
+        // Check cache
+        const cached = await this.backend.findSimilar(input, this.config.threshold);
+        if (cached) {
+            const latencyMs = Date.now() - start;
+            this.metrics.hits++;
+            this.metrics.totalLatency += latencyMs;
+            this.log(`⚡ Cache hit (similarity: ${cached.similarity.toFixed(3)}, ${latencyMs}ms)`);
+            this.emit('hit', { input, similarity: cached.similarity, latencyMs });
+            return { data: cached.data, fromCache: true, similarity: cached.similarity, latencyMs };
+        }
+        // Cache miss — run the function
+        this.metrics.misses++;
+        const data = await fn();
+        const latencyMs = Date.now() - start;
+        this.metrics.totalLatency += latencyMs;
+        // Store result (await to ensure it's stored before returning)
+        const key = generateKey(input);
+        try {
+            await this.backend.set(key, input, data, this.config.ttl);
+        }
+        catch (err) {
+            this.log(`⚠️  Failed to store in cache: ${err.message}`);
+        }
+        this.log(`🔄 Cache miss (${latencyMs}ms) — stored for future use`);
+        this.emit('miss', { input, latencyMs });
+        return { data, fromCache: false, latencyMs };
+    }
+    /**
+     * Manually get a value from cache.
+     * Returns null if not found.
+     */
+    async get(input) {
+        this.assertReady();
+        const start = Date.now();
+        const cached = await this.backend.findSimilar(input, this.config.threshold);
+        if (!cached)
+            return null;
+        return {
+            data: cached.data,
+            fromCache: true,
+            similarity: cached.similarity,
+            latencyMs: Date.now() - start,
+        };
+    }
+    /**
+     * Manually store a value in cache.
+     */
+    async set(input, data) {
+        this.assertReady();
+        const key = generateKey(input);
+        await this.backend.set(key, input, data, this.config.ttl);
+        this.log(`📦 Stored: "${input.slice(0, 50)}..."`);
+    }
+    /**
+     * Get performance metrics.
+     */
+    getMetrics() {
+        const total = this.metrics.hits + this.metrics.misses;
+        const health = this.backend.getHealth();
+        // Determine backend health status
+        let backendHealth = 'healthy';
+        if (health.state === 'OPEN') {
+            backendHealth = 'down';
+        }
+        else if (health.state === 'HALF_OPEN' || health.currentBackend !== this.getStorageType()) {
+            backendHealth = 'degraded';
+        }
+        return {
+            hits: this.metrics.hits,
+            misses: this.metrics.misses,
+            total,
+            hitRate: total > 0 ? this.metrics.hits / total : 0,
+            avgLatencyMs: total > 0 ? Math.round(this.metrics.totalLatency / total) : 0,
+            cacheSize: this.backend.size(),
+            backendHealth,
+            failureCount: health.totalFailures,
+            evictedCount: 0, // Will be implemented per backend
+            lastCleanupAt: 0, // Will be implemented per backend
+        };
+    }
+    /**
+     * Get backend health information.
+     */
+    getBackendHealth() {
+        return this.backend.getHealth();
+    }
+    /**
+     * Get the configured storage type.
+     */
+    getStorageType() {
+        return this.config.storage;
+    }
+    /**
+     * Clear all cached entries and reset metrics.
+     */
+    clear() {
+        this.backend.clear();
+        this.metrics = { hits: 0, misses: 0, totalLatency: 0 };
+        this.log('🗑️  Cache cleared');
+    }
+    /**
+     * Update similarity threshold at runtime.
+     */
+    setThreshold(threshold) {
+        if (threshold < 0 || threshold > 1)
+            throw new Error('Threshold must be 0–1');
+        this.config.threshold = threshold;
+    }
+    /**
+     * Stop cleanup timer and perform graceful shutdown.
+     * Call this before your application exits to prevent memory leaks.
+     *
+     * @example
+     * const lemma = await Lemma.create();
+     * // ... use lemma ...
+     * lemma.stop(); // cleanup before exit
+     */
+    stop() {
+        this.backend.stop();
+        this.log('🛑 Lemma stopped');
+    }
+    assertReady() {
+        if (!this.ready)
+            throw new Error('Lemma not initialized. Use Lemma.create()');
+    }
+    log(msg) {
+        if (this.config.debug)
+            console.log(`[Lemma] ${msg}`);
+    }
+}
+exports.Lemma = Lemma;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function normalizeText(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function generateKey(input) {
+    return crypto_1.default.createHash('sha256').update(normalizeText(input)).digest('hex').slice(0, 16);
+}
+// ─── Default export ───────────────────────────────────────────────────────────
+exports.default = Lemma;
+//# sourceMappingURL=index.js.map