@lov3kaizen/agentsea-embeddings 0.5.1

package/dist/caching/index.js

@@ -0,0 +1,1005 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/caching/index.ts
+var caching_exports = {};
+__export(caching_exports, {
+  BaseCache: () => BaseCache,
+  MemoryCache: () => MemoryCache,
+  RedisCache: () => RedisCache,
+  SQLiteCache: () => SQLiteCache,
+  TieredCache: () => TieredCache,
+  createCache: () => createCache,
+  createMemoryCache: () => createMemoryCache,
+  createRedisCache: () => createRedisCache,
+  createSQLiteCache: () => createSQLiteCache,
+  createStandardTieredCache: () => createStandardTieredCache,
+  createTieredCache: () => createTieredCache
+});
+module.exports = __toCommonJS(caching_exports);
+
+// src/core/utils.ts
+var import_crypto = require("crypto");
+function contentHash(text, algorithm = "sha256") {
+  return (0, import_crypto.createHash)(algorithm).update(text).digest("hex");
+}
+
+// src/caching/BaseCache.ts
+var BaseCache = class {
+  /** Cache options */
+  options;
+  /** Cache statistics */
+  stats;
+  constructor(options = {}) {
+    this.options = {
+      defaultTTL: options.defaultTTL ?? 0,
+      maxEntries: options.maxEntries ?? 1e5,
+      maxSizeBytes: options.maxSizeBytes ?? 1024 * 1024 * 1024,
+      // 1GB
+      keyPrefix: options.keyPrefix ?? "emb",
+      compression: options.compression ?? false,
+      compressionThreshold: options.compressionThreshold ?? 1024
+    };
+    this.stats = this.createInitialStats();
+  }
+  createInitialStats() {
+    return {
+      entries: 0,
+      sizeBytes: 0,
+      hits: 0,
+      misses: 0,
+      hitRate: 0,
+      gets: 0,
+      sets: 0,
+      deletes: 0,
+      evictions: 0,
+      avgGetLatencyMs: 0,
+      avgSetLatencyMs: 0
+    };
+  }
+  /**
+   * Generate cache key from text and model
+   */
+  generateKey(text, model) {
+    const hash = contentHash(`${model}:${text}`);
+    return `${this.options.keyPrefix}:${model}:${hash}`;
+  }
+  /**
+   * Lookup with timing and stats
+   */
+  async lookup(key) {
+    const startTime = performance.now();
+    this.stats.gets++;
+    const entry = await this.get(key);
+    const latencyMs = performance.now() - startTime;
+    this.stats.avgGetLatencyMs = (this.stats.avgGetLatencyMs * (this.stats.gets - 1) + latencyMs) / this.stats.gets;
+    if (entry) {
+      this.stats.hits++;
+      this.updateHitRate();
+      return { hit: true, entry, latencyMs };
+    } else {
+      this.stats.misses++;
+      this.updateHitRate();
+      return { hit: false, latencyMs };
+    }
+  }
+  /**
+   * Batch lookup
+   */
+  async lookupBatch(keys) {
+    const startTime = performance.now();
+    const hits = /* @__PURE__ */ new Map();
+    const misses = [];
+    for (const key of keys) {
+      const result = await this.lookup(key);
+      if (result.hit && result.entry) {
+        hits.set(key, result.entry);
+      } else {
+        misses.push(key);
+      }
+    }
+    return {
+      hits,
+      misses,
+      hitRate: keys.length > 0 ? hits.size / keys.length : 0,
+      latencyMs: performance.now() - startTime
+    };
+  }
+  /**
+   * Store with timing and stats
+   */
+  async store(key, result, model, ttl) {
+    const startTime = performance.now();
+    this.stats.sets++;
+    const entry = {
+      key,
+      vector: result.vector,
+      text: result.text,
+      model,
+      dimensions: result.dimensions,
+      tokenCount: result.tokenCount,
+      createdAt: Date.now(),
+      accessedAt: Date.now(),
+      accessCount: 0,
+      ttl: ttl ?? this.options.defaultTTL ?? 0
+    };
+    await this.set(key, entry);
+    const latencyMs = performance.now() - startTime;
+    this.stats.avgSetLatencyMs = (this.stats.avgSetLatencyMs * (this.stats.sets - 1) + latencyMs) / this.stats.sets;
+  }
+  /**
+   * Store batch of results
+   */
+  async storeBatch(entries, ttl) {
+    for (const entry of entries) {
+      await this.store(entry.key, entry.result, entry.model, ttl);
+    }
+  }
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Reset statistics
+   */
+  resetStats() {
+    this.stats = this.createInitialStats();
+  }
+  /**
+   * Update hit rate
+   */
+  updateHitRate() {
+    const total = this.stats.hits + this.stats.misses;
+    this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
+  }
+  /**
+   * Cleanup expired/old entries
+   */
+  async cleanup(options) {
+    const startTime = performance.now();
+    const dryRun = options?.dryRun ?? false;
+    const now = Date.now();
+    let removed = 0;
+    let freedBytes = 0;
+    const keys = await this.keys();
+    for (const key of keys) {
+      const entry = await this.get(key);
+      if (!entry) continue;
+      let shouldRemove = false;
+      if (options?.removeExpired && entry.ttl > 0) {
+        if (entry.createdAt + entry.ttl * 1e3 < now) {
+          shouldRemove = true;
+        }
+      }
+      if (options?.olderThan) {
+        if (entry.createdAt < now - options.olderThan * 1e3) {
+          shouldRemove = true;
+        }
+      }
+      if (options?.notAccessedSince) {
+        if (entry.accessedAt < now - options.notAccessedSince * 1e3) {
+          shouldRemove = true;
+        }
+      }
+      if (options?.model && entry.model !== options.model) {
+        shouldRemove = false;
+      }
+      if (options?.version && entry.version !== options.version) {
+        shouldRemove = false;
+      }
+      if (shouldRemove && !dryRun) {
+        const size = this.estimateEntrySize(entry);
+        await this.delete(key);
+        removed++;
+        freedBytes += size;
+        this.stats.evictions++;
+      } else if (shouldRemove) {
+        removed++;
+        freedBytes += this.estimateEntrySize(entry);
+      }
+    }
+    return {
+      removed,
+      freedBytes,
+      durationMs: performance.now() - startTime,
+      dryRun
+    };
+  }
+  /**
+   * Export cache contents
+   */
+  async export() {
+    const keys = await this.keys();
+    const entries = [];
+    for (const key of keys) {
+      const entry = await this.get(key);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+    return {
+      version: "1.0",
+      exportedAt: Date.now(),
+      totalEntries: entries.length,
+      entries
+    };
+  }
+  /**
+   * Import cache contents
+   */
+  async import(data, options) {
+    let imported = 0;
+    let skipped = 0;
+    for (let i = 0; i < data.entries.length; i++) {
+      const entry = data.entries[i];
+      if (options?.validate) {
+        if (!entry.key || !entry.vector || !entry.model) {
+          skipped++;
+          continue;
+        }
+      }
+      const exists = await this.has(entry.key);
+      if (exists) {
+        if (options?.skipExisting) {
+          skipped++;
+          continue;
+        }
+        if (!options?.updateExisting) {
+          skipped++;
+          continue;
+        }
+      }
+      await this.set(entry.key, entry);
+      imported++;
+      if (options?.onProgress) {
+        options.onProgress({ imported, total: data.entries.length });
+      }
+    }
+    return { imported, skipped };
+  }
+  /**
+   * Estimate entry size in bytes
+   */
+  estimateEntrySize(entry) {
+    const vectorSize = entry.vector.length * 4;
+    const textSize = (entry.text?.length ?? 0) * 2;
+    const overheadSize = 200;
+    return vectorSize + textSize + overheadSize;
+  }
+};
+
+// src/caching/MemoryCache.ts
+var import_lru_cache = require("lru-cache");
+var MemoryCache = class extends BaseCache {
+  backendType = "memory";
+  cache;
+  constructor(options = {}) {
+    super(options);
+    this.cache = new import_lru_cache.LRUCache({
+      max: options.maxEntries ?? 1e5,
+      maxSize: options.maxSizeBytes ?? 1024 * 1024 * 1024,
+      sizeCalculation: (entry) => this.estimateEntrySize(entry),
+      ttl: options.maxAge ?? 0,
+      updateAgeOnGet: options.updateAgeOnGet ?? true,
+      allowStale: options.staleWhileRevalidate ? true : false
+    });
+  }
+  async get(key) {
+    const entry = this.cache.get(key);
+    if (entry) {
+      entry.accessedAt = Date.now();
+      entry.accessCount++;
+    }
+    return Promise.resolve(entry);
+  }
+  set(key, entry) {
+    const ttl = entry.ttl > 0 ? entry.ttl * 1e3 : void 0;
+    this.cache.set(key, entry, { ttl });
+    this.stats.entries = this.cache.size;
+    return Promise.resolve();
+  }
+  has(key) {
+    return Promise.resolve(this.cache.has(key));
+  }
+  async delete(key) {
+    const existed = this.cache.has(key);
+    this.cache.delete(key);
+    this.stats.deletes++;
+    this.stats.entries = this.cache.size;
+    return Promise.resolve(existed);
+  }
+  clear() {
+    this.cache.clear();
+    this.stats.entries = 0;
+    return Promise.resolve();
+  }
+  size() {
+    return Promise.resolve(this.cache.size);
+  }
+  keys() {
+    return Promise.resolve(Array.from(this.cache.keys()));
+  }
+  async close() {
+    this.cache.clear();
+    return Promise.resolve();
+  }
+  /**
+   * Get memory usage info
+   */
+  getMemoryInfo() {
+    return {
+      entries: this.cache.size,
+      calculatedSize: this.cache.calculatedSize,
+      maxSize: this.cache.max
+    };
+  }
+  /**
+   * Prune stale entries
+   */
+  prune() {
+    this.cache.purgeStale();
+    this.stats.entries = this.cache.size;
+  }
+};
+function createMemoryCache(options) {
+  return new MemoryCache(options);
+}
+
+// src/caching/RedisCache.ts
+var RedisCache = class extends BaseCache {
+  backendType = "redis";
+  client = null;
+  config;
+  connected = false;
+  constructor(options) {
+    super(options);
+    this.config = options;
+  }
+  /**
+   * Connect to Redis
+   */
+  async connect() {
+    if (this.connected) return;
+    try {
+      const { Redis } = await import("ioredis");
+      if (this.config.url) {
+        this.client = new Redis(this.config.url, {
+          connectTimeout: this.config.connectTimeout ?? 1e4,
+          commandTimeout: this.config.commandTimeout ?? 5e3,
+          lazyConnect: false
+        });
+      } else if (this.config.cluster && this.config.clusterNodes) {
+        const { Cluster } = await import("ioredis");
+        this.client = new Cluster(this.config.clusterNodes, {
+          redisOptions: {
+            password: this.config.password
+          }
+        });
+      } else if (this.config.sentinel) {
+        this.client = new Redis({
+          sentinels: this.config.sentinel.sentinels,
+          name: this.config.sentinel.master,
+          password: this.config.password
+        });
+      } else {
+        this.client = new Redis({
+          host: this.config.host ?? "localhost",
+          port: this.config.port ?? 6379,
+          password: this.config.password,
+          db: this.config.db ?? 0,
+          connectTimeout: this.config.connectTimeout ?? 1e4,
+          commandTimeout: this.config.commandTimeout ?? 5e3
+        });
+      }
+      await this.client.ping();
+      this.connected = true;
+    } catch (error) {
+      throw new Error(
+        `Failed to connect to Redis: ${error.message}`
+      );
+    }
+  }
+  /**
+   * Ensure connected
+   */
+  async ensureConnected() {
+    if (!this.connected || !this.client) {
+      await this.connect();
+    }
+    if (!this.client) {
+      throw new Error("Redis client not initialized");
+    }
+    return this.client;
+  }
+  async get(key) {
+    const client = await this.ensureConnected();
+    const data = await client.get(this.prefixKey(key));
+    if (!data) return void 0;
+    try {
+      const entry = JSON.parse(data);
+      entry.accessedAt = Date.now();
+      entry.accessCount++;
+      client.set(this.prefixKey(key), JSON.stringify(entry)).catch(() => {
+      });
+      return entry;
+    } catch {
+      return void 0;
+    }
+  }
+  async set(key, entry) {
+    const client = await this.ensureConnected();
+    const data = JSON.stringify(entry);
+    const options = {};
+    if (entry.ttl > 0) {
+      options.EX = entry.ttl;
+    } else if (this.config.defaultTTL && this.config.defaultTTL > 0) {
+      options.EX = this.config.defaultTTL;
+    }
+    await client.set(this.prefixKey(key), data, options);
+    this.stats.entries++;
+  }
+  async has(key) {
+    const client = await this.ensureConnected();
+    const exists = await client.exists(this.prefixKey(key));
+    return exists > 0;
+  }
+  async delete(key) {
+    const client = await this.ensureConnected();
+    const deleted = await client.del(this.prefixKey(key));
+    if (deleted > 0) {
+      this.stats.deletes++;
+      this.stats.entries = Math.max(0, this.stats.entries - 1);
+    }
+    return deleted > 0;
+  }
+  async clear() {
+    const client = await this.ensureConnected();
+    const keys = await client.keys(this.prefixKey("*"));
+    if (keys.length > 0) {
+      await client.del(...keys);
+    }
+    this.stats.entries = 0;
+  }
+  async size() {
+    const client = await this.ensureConnected();
+    const keys = await client.keys(this.prefixKey("*"));
+    return keys.length;
+  }
+  async keys() {
+    const client = await this.ensureConnected();
+    const keys = await client.keys(this.prefixKey("*"));
+    const prefix = this.prefixKey("");
+    return keys.map((k) => k.slice(prefix.length));
+  }
+  async close() {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+      this.connected = false;
+    }
+  }
+  /**
+   * Add prefix to key
+   */
+  prefixKey(key) {
+    const prefix = this.config.keyPrefix ?? this.options.keyPrefix ?? "emb";
+    return `${prefix}:${key}`;
+  }
+  /**
+   * Check if connected
+   */
+  isConnected() {
+    return this.connected;
+  }
+};
+function createRedisCache(options) {
+  return new RedisCache(options);
+}
+
+// src/caching/SQLiteCache.ts
+var SQLiteCache = class extends BaseCache {
+  backendType = "sqlite";
+  db = null;
+  config;
+  initialized = false;
+  vacuumCounter = 0;
+  constructor(options = {}) {
+    super(options);
+    this.config = {
+      dbPath: options.dbPath ?? "./embeddings_cache.db",
+      inMemory: options.inMemory ?? false,
+      walMode: options.walMode ?? true,
+      busyTimeout: options.busyTimeout ?? 5e3,
+      autoVacuum: options.autoVacuum ?? true,
+      vacuumInterval: options.vacuumInterval ?? 1e3,
+      ...options
+    };
+  }
+  /**
+   * Initialize database
+   */
+  async init() {
+    if (this.initialized) return;
+    try {
+      const Database = (await import("better-sqlite3")).default;
+      const dbPath = this.config.inMemory ? ":memory:" : this.config.dbPath;
+      this.db = new Database(dbPath);
+      if (this.config.walMode) {
+        this.db.exec("PRAGMA journal_mode = WAL");
+      }
+      if (this.config.busyTimeout) {
+        this.db.exec(`PRAGMA busy_timeout = ${this.config.busyTimeout}`);
+      }
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS embeddings (
+          key TEXT PRIMARY KEY,
+          vector BLOB NOT NULL,
+          text TEXT,
+          model TEXT NOT NULL,
+          dimensions INTEGER NOT NULL,
+          token_count INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          accessed_at INTEGER NOT NULL,
+          access_count INTEGER DEFAULT 0,
+          ttl INTEGER DEFAULT 0,
+          version TEXT,
+          metadata TEXT
+        )
+      `);
+      this.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_model ON embeddings(model);
+        CREATE INDEX IF NOT EXISTS idx_created_at ON embeddings(created_at);
+        CREATE INDEX IF NOT EXISTS idx_accessed_at ON embeddings(accessed_at);
+      `);
+      this.initialized = true;
+    } catch (error) {
+      throw new Error(
+        `Failed to initialize SQLite: ${error.message}`
+      );
+    }
+  }
+  /**
+   * Ensure initialized
+   */
+  async ensureInitialized() {
+    if (!this.initialized || !this.db) {
+      await this.init();
+    }
+    if (!this.db) {
+      throw new Error("SQLite database not initialized");
+    }
+    return this.db;
+  }
+  async get(key) {
+    const db = await this.ensureInitialized();
+    const stmt = db.prepare(`
+      SELECT * FROM embeddings WHERE key = ?
+    `);
+    const row = stmt.get(key);
+    if (!row) return void 0;
+    const ttl = row.ttl;
+    if (ttl > 0) {
+      const createdAt = row.created_at;
+      if (Date.now() > createdAt + ttl * 1e3) {
+        await this.delete(key);
+        return void 0;
+      }
+    }
+    const updateStmt = db.prepare(`
+      UPDATE embeddings
+      SET accessed_at = ?, access_count = access_count + 1
+      WHERE key = ?
+    `);
+    updateStmt.run(Date.now(), key);
+    const vectorBuffer = row.vector;
+    const vector = Array.from(new Float32Array(vectorBuffer.buffer));
+    return {
+      key: row.key,
+      vector,
+      text: row.text,
+      model: row.model,
+      dimensions: row.dimensions,
+      tokenCount: row.token_count,
+      createdAt: row.created_at,
+      accessedAt: Date.now(),
+      accessCount: row.access_count + 1,
+      ttl,
+      version: row.version,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0
+    };
+  }
+  async set(key, entry) {
+    const db = await this.ensureInitialized();
+    const vectorBuffer = Buffer.from(new Float32Array(entry.vector).buffer);
+    const stmt = db.prepare(`
+      INSERT OR REPLACE INTO embeddings
+      (key, vector, text, model, dimensions, token_count, created_at, accessed_at, access_count, ttl, version, metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    stmt.run(
+      entry.key,
+      vectorBuffer,
+      entry.text,
+      entry.model,
+      entry.dimensions,
+      entry.tokenCount,
+      entry.createdAt,
+      entry.accessedAt,
+      entry.accessCount,
+      entry.ttl,
+      entry.version,
+      entry.metadata ? JSON.stringify(entry.metadata) : null
+    );
+    this.stats.entries++;
+    this.maybeVacuum();
+  }
+  async has(key) {
+    const db = await this.ensureInitialized();
+    const stmt = db.prepare("SELECT 1 FROM embeddings WHERE key = ?");
+    return !!stmt.get(key);
+  }
+  async delete(key) {
+    const db = await this.ensureInitialized();
+    const stmt = db.prepare("DELETE FROM embeddings WHERE key = ?");
+    const result = stmt.run(key);
+    if (result.changes > 0) {
+      this.stats.deletes++;
+      this.stats.entries = Math.max(0, this.stats.entries - 1);
+    }
+    return result.changes > 0;
+  }
+  async clear() {
+    const db = await this.ensureInitialized();
+    db.exec("DELETE FROM embeddings");
+    this.stats.entries = 0;
+  }
+  async size() {
+    const db = await this.ensureInitialized();
+    const stmt = db.prepare("SELECT COUNT(*) as count FROM embeddings");
+    const row = stmt.get();
+    return row.count;
+  }
+  async keys() {
+    const db = await this.ensureInitialized();
+    const stmt = db.prepare("SELECT key FROM embeddings");
+    const rows = stmt.all();
+    return rows.map((r) => r.key);
+  }
+  async close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+      this.initialized = false;
+    }
+    return Promise.resolve();
+  }
+  /**
+   * Maybe run vacuum
+   */
+  maybeVacuum() {
+    if (!this.config.autoVacuum) return;
+    this.vacuumCounter++;
+    if (this.vacuumCounter >= (this.config.vacuumInterval ?? 1e3)) {
+      this.vacuumCounter = 0;
+      this.vacuum().catch(() => {
+      });
+    }
+  }
+  /**
+   * Run vacuum
+   */
+  async vacuum() {
+    const db = await this.ensureInitialized();
+    db.exec("VACUUM");
+  }
+  /**
+   * Remove expired entries
+   */
+  async removeExpired() {
+    const db = await this.ensureInitialized();
+    const now = Date.now();
+    const stmt = db.prepare(`
+      DELETE FROM embeddings
+      WHERE ttl > 0 AND (created_at + ttl * 1000) < ?
+    `);
+    const result = stmt.run(now);
+    return result.changes;
+  }
+};
+function createSQLiteCache(options) {
+  return new SQLiteCache(options);
+}
+
+// src/caching/TieredCache.ts
+var TieredCache = class extends BaseCache {
+  backendType = "tiered";
+  tiers = [];
+  writeThrough;
+  promoteOnHit;
+  constructor(options) {
+    super(options);
+    this.writeThrough = options.writeThrough ?? true;
+    this.promoteOnHit = options.promoteOnHit ?? true;
+    this.initializeTiers(options.tiers);
+  }
+  /**
+   * Initialize cache tiers
+   */
+  initializeTiers(tierConfigs) {
+    const sorted = [...tierConfigs].sort((a, b) => a.priority - b.priority);
+    for (const config of sorted) {
+      let cache;
+      switch (config.type) {
+        case "memory":
+          cache = new MemoryCache(config.options);
+          break;
+        case "redis":
+          cache = new RedisCache(config.options);
+          break;
+        case "sqlite":
+          cache = new SQLiteCache(config.options);
+          break;
+        default:
+          continue;
+      }
+      this.tiers.push({
+        name: config.name,
+        cache,
+        priority: config.priority
+      });
+    }
+  }
+  /**
+   * Initialize all tier connections
+   */
+  async init() {
+    for (const tier of this.tiers) {
+      if (tier.cache instanceof RedisCache) {
+        await tier.cache.connect();
+      } else if (tier.cache instanceof SQLiteCache) {
+        await tier.cache.init();
+      }
+    }
+  }
+  async get(key) {
+    let foundEntry;
+    let foundTierIndex = -1;
+    for (let i = 0; i < this.tiers.length; i++) {
+      const entry = await this.tiers[i].cache.get(key);
+      if (entry) {
+        foundEntry = entry;
+        foundTierIndex = i;
+        break;
+      }
+    }
+    if (foundEntry && foundTierIndex > 0 && this.promoteOnHit) {
+      for (let i = 0; i < foundTierIndex; i++) {
+        await this.tiers[i].cache.set(key, foundEntry);
+      }
+    }
+    return foundEntry;
+  }
+  async set(key, entry) {
+    if (this.writeThrough) {
+      for (const tier of this.tiers) {
+        await tier.cache.set(key, entry);
+      }
+    } else {
+      if (this.tiers.length > 0) {
+        await this.tiers[0].cache.set(key, entry);
+      }
+    }
+    this.stats.entries++;
+  }
+  async has(key) {
+    for (const tier of this.tiers) {
+      if (await tier.cache.has(key)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  async delete(key) {
+    let deleted = false;
+    for (const tier of this.tiers) {
+      if (await tier.cache.delete(key)) {
+        deleted = true;
+      }
+    }
+    if (deleted) {
+      this.stats.deletes++;
+      this.stats.entries = Math.max(0, this.stats.entries - 1);
+    }
+    return deleted;
+  }
+  async clear() {
+    for (const tier of this.tiers) {
+      await tier.cache.clear();
+    }
+    this.stats.entries = 0;
+  }
+  async size() {
+    if (this.tiers.length === 0) return 0;
+    return this.tiers[this.tiers.length - 1].cache.size();
+  }
+  async keys() {
+    const allKeys = /* @__PURE__ */ new Set();
+    for (const tier of this.tiers) {
+      const keys = await tier.cache.keys();
+      for (const key of keys) {
+        allKeys.add(key);
+      }
+    }
+    return Array.from(allKeys);
+  }
+  async close() {
+    for (const tier of this.tiers) {
+      await tier.cache.close();
+    }
+    this.tiers = [];
+  }
+  /**
+   * Override lookup to track tier hits
+   */
+  async lookup(key) {
+    const startTime = performance.now();
+    this.stats.gets++;
+    let foundEntry;
+    let foundTierName;
+    let foundTierIndex = -1;
+    for (let i = 0; i < this.tiers.length; i++) {
+      const entry = await this.tiers[i].cache.get(key);
+      if (entry) {
+        foundEntry = entry;
+        foundTierName = this.tiers[i].name;
+        foundTierIndex = i;
+        break;
+      }
+    }
+    const latencyMs = performance.now() - startTime;
+    this.stats.avgGetLatencyMs = (this.stats.avgGetLatencyMs * (this.stats.gets - 1) + latencyMs) / this.stats.gets;
+    if (foundEntry) {
+      this.stats.hits++;
+      this.updateHitRate();
+      if (foundTierIndex > 0 && this.promoteOnHit) {
+        for (let i = 0; i < foundTierIndex; i++) {
+          await this.tiers[i].cache.set(key, foundEntry);
+        }
+      }
+      return { hit: true, entry: foundEntry, tier: foundTierName, latencyMs };
+    } else {
+      this.stats.misses++;
+      this.updateHitRate();
+      return { hit: false, latencyMs };
+    }
+  }
+  /**
+   * Get statistics for all tiers
+   */
+  getTierStats() {
+    const tierStats = {};
+    for (const tier of this.tiers) {
+      tierStats[tier.name] = tier.cache.getStats();
+    }
+    return tierStats;
+  }
+  /**
+   * Get cache from specific tier
+   */
+  getTier(name) {
+    return this.tiers.find((t) => t.name === name)?.cache;
+  }
+  /**
+   * Get all tier names
+   */
+  getTierNames() {
+    return this.tiers.map((t) => t.name);
+  }
+  /**
+   * Override getStats to include tier stats
+   */
+  getStats() {
+    const stats = super.getStats();
+    return {
+      ...stats,
+      tierStats: this.getTierStats()
+    };
+  }
+};
+function createTieredCache(options) {
+  return new TieredCache(options);
+}
+function createStandardTieredCache(options) {
+  const tiers = [
+    {
+      name: "memory",
+      type: "memory",
+      options: {
+        maxEntries: options?.memoryMaxEntries ?? 1e4
+      },
+      priority: 1
+    }
+  ];
+  if (options?.useRedis && options.redisUrl) {
+    tiers.push({
+      name: "redis",
+      type: "redis",
+      options: {
+        url: options.redisUrl
+      },
+      priority: 2
+    });
+  } else {
+    tiers.push({
+      name: "sqlite",
+      type: "sqlite",
+      options: {
+        dbPath: options?.persistentPath ?? "./embeddings_cache.db"
+      },
+      priority: 2
+    });
+  }
+  return new TieredCache({
+    tiers,
+    writeThrough: true,
+    promoteOnHit: true
+  });
+}
+
+// src/caching/index.ts
+function createCache(type, options) {
+  switch (type) {
+    case "memory":
+      return new MemoryCache(options);
+    case "redis":
+      return new RedisCache(options);
+    case "sqlite":
+      return new SQLiteCache(options);
+    case "tiered":
+      return new TieredCache(options);
+    default:
+      return new MemoryCache(options);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseCache,
+  MemoryCache,
+  RedisCache,
+  SQLiteCache,
+  TieredCache,
+  createCache,
+  createMemoryCache,
+  createRedisCache,
+  createSQLiteCache,
+  createStandardTieredCache,
+  createTieredCache
+});