@nxuss/lemma 0.1.1 → 0.2.0

package/dist/{embed → cjs/embed}/index.d.ts

@@ -16,10 +16,11 @@ export interface LemmaConfig {
     /**
      * Storage backend.
      * - 'memory': in-process Map, zero dependencies, resets on restart (default)
+     * - 'semantic': in-process semantic cache using lightweight embeddings (requires @xenova/transformers)
      * - 'chroma': ChromaDB + Ollama for persistent semantic cache
      * - 'cloud': Lemma Cloud — managed semantic cache, just add an API key
      */
-    storage?: 'memory' | 'chroma' | 'cloud';
+    storage?: 'memory' | 'semantic' | 'chroma' | 'cloud';
     /**
      * Lemma Cloud API key. Required when storage='cloud'.
      * Get yours at https://lemma.dev
@@ -48,6 +49,11 @@ export interface LemmaConfig {
      * Ollama model for embeddings. Default: 'llama3'
      */
     ollamaModel?: string;
+    /**
+     * Embedding model for semantic storage. Default: 'Xenova/all-MiniLM-L6-v2'
+     * Only used when storage='semantic'.
+     */
+    embeddingModel?: string;
     /**
      * Collection name in ChromaDB. Default: 'lemma_cache'
      */
@@ -60,10 +66,30 @@ export interface LemmaConfig {
      * Max entries in memory cache. Default: 10000
      */
     maxSize?: number;
+    /**
+     * Cleanup interval in milliseconds for expired entries.
+     * Set to 0 to disable automatic cleanup. Default: 60000 (1 minute)
+     */
+    cleanupInterval?: number;
     /**
      * Log cache hits/misses to console. Default: false
      */
     debug?: boolean;
+    /**
+     * Enable automatic fallback to alternative backends on failure.
+     * Default: true
+     */
+    enableFallback?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations.
+     * Default: 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds between retry attempts.
+     * Uses exponential backoff. Default: 1000
+     */
+    retryDelay?: number;
 }
 export interface CacheResult<T = any> {
     data: T;
@@ -78,6 +104,17 @@ export interface LemmaMetrics {
     hitRate: number;
     avgLatencyMs: number;
     cacheSize: number;
+    backendHealth: 'healthy' | 'degraded' | 'down';
+    failureCount: number;
+    evictedCount: number;
+    lastCleanupAt: number;
+}
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface BackendHealth {
+    state: CircuitState;
+    failureCount: number;
+    lastFailure: number | null;
+    successCount: number;
 }
 export declare class Lemma extends EventEmitter {
     private backend;
@@ -93,6 +130,13 @@ export declare class Lemma extends EventEmitter {
      * 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',
@@ -138,6 +182,17 @@ export declare class Lemma extends EventEmitter {
      * Get performance metrics.
      */
     getMetrics(): LemmaMetrics;
+    /**
+     * Get backend health information.
+     */
+    getBackendHealth(): BackendHealth & {
+        currentBackend: string;
+        totalFailures: number;
+    };
+    /**
+     * Get the configured storage type.
+     */
+    private getStorageType;
     /**
      * Clear all cached entries and reset metrics.
      */
@@ -146,6 +201,16 @@ export declare class Lemma extends EventEmitter {
      * Update similarity threshold at runtime.
      */
     setThreshold(threshold: number): void;
+    /**
+     * 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(): void;
     private assertReady;
     private log;
 }

package/dist/cjs/embed/index.d.ts.map

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