@theokit/sdk-cache 0.1.0

package/dist/index.js

@@ -0,0 +1,658 @@
+import { definePlugin } from '@theokit/sdk';
+import { PersistenceSchema, atomicWriteText } from '@theokit/sdk/internal/persistence';
+import { z } from 'zod';
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import { readFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+
+// src/cache.ts
+
+// src/internal/embed-helper.ts
+async function embedOrDegrade(embedder, prompt, store, span, context) {
+  try {
+    const result = await embedder.embed([prompt]);
+    return result[0];
+  } catch (err) {
+    store.incrementEmbedderFailures();
+    const action = context === "lookup" ? "degrading to miss" : "skipping cache write";
+    console.warn(
+      `[cache] embedder failed during ${context}, ${action}:`,
+      err instanceof Error ? err.message : err
+    );
+    span.setAttribute("cache.bypass_reason", "embedder_failure");
+    return void 0;
+  }
+}
+function computeCacheKey(p) {
+  const normalized = p.prompt.trim().replace(/\s+/g, " ").toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return `${p.namespace}:${p.embedderId}:${p.modelId}:${hash}`;
+}
+var noopSpan = {
+  setAttribute: () => noopSpan,
+  end: () => void 0
+};
+var tracerCache = /* @__PURE__ */ new Map();
+function getTracer(name, version = "1.0.0") {
+  const cached = tracerCache.get(name);
+  if (cached !== void 0) return cached.tracer ?? void 0;
+  try {
+    const r = createRequire(import.meta.url);
+    const otel = r("@opentelemetry/api");
+    if (otel.trace?.getTracer === void 0) {
+      tracerCache.set(name, { tracer: null });
+      return void 0;
+    }
+    const tracer = otel.trace.getTracer(name, version);
+    tracerCache.set(name, { tracer });
+    return tracer;
+  } catch {
+    tracerCache.set(name, { tracer: null });
+    return void 0;
+  }
+}
+var TRACER_NAME = "@theokit/sdk/cache";
+function startCacheLookupSpan(info) {
+  const tracer = getTracer(TRACER_NAME);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("cache.lookup", {
+    attributes: {
+      "cache.namespace": info.namespace,
+      "cache.embedder_id": info.embedderId
+    }
+  });
+}
+function startCacheStoreSpan(info) {
+  const tracer = getTracer(TRACER_NAME);
+  if (tracer === void 0) return noopSpan;
+  return tracer.startSpan("cache.store", {
+    attributes: {
+      "cache.namespace": info.namespace,
+      "cache.embedder_id": info.embedderId
+    }
+  });
+}
+
+// src/internal/lookup.ts
+async function performLookup(p) {
+  const span = startCacheLookupSpan({
+    namespace: p.namespace,
+    embedderId: p.embedder.id
+  });
+  try {
+    if (p.prompt.trim().length === 0) {
+      p.store.incrementMisses();
+      span.setAttribute("cache.bypass_reason", "empty_prompt");
+      return { cached: false };
+    }
+    if (p.ttl.exclude?.test(p.prompt)) {
+      p.store.incrementExcluded();
+      span.setAttribute("cache.bypass_reason", "exclude_regex");
+      return { cached: false };
+    }
+    const key = computeCacheKey({
+      namespace: p.namespace,
+      embedderId: p.embedder.id,
+      modelId: p.modelId,
+      prompt: p.prompt
+    });
+    const now = Date.now();
+    const kv = p.store.kvGet(key, now);
+    if (kv !== void 0) {
+      p.store.incrementKvHits();
+      span.setAttribute("cache.hit", "kv");
+      span.setAttribute("cache.ttl_remaining_s", Math.floor((kv.expiresAt - now) / 1e3));
+      return { cached: true, response: kv.response, source: "kv" };
+    }
+    const vec = await embedOrDegrade(p.embedder, p.prompt, p.store, span, "lookup");
+    if (vec === void 0) return { cached: false };
+    const match = p.store.semanticSearch(vec, p.threshold, p.embedder.id, p.namespace, now);
+    if (match !== void 0) {
+      p.store.incrementSemanticHits();
+      span.setAttribute("cache.hit", "semantic");
+      span.setAttribute("cache.distance", match.distance);
+      span.setAttribute("cache.ttl_remaining_s", Math.floor((match.entry.expiresAt - now) / 1e3));
+      return {
+        cached: true,
+        response: match.entry.response,
+        source: "semantic",
+        distance: match.distance
+      };
+    }
+    p.store.incrementMisses();
+    span.setAttribute("cache.hit", "miss");
+    return { cached: false };
+  } finally {
+    span.end();
+  }
+}
+
+// src/internal/cosine.ts
+function cosineDistance(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`cosineDistance: dim mismatch (${a.length} vs ${b.length})`);
+  }
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    const av = a[i];
+    const bv = b[i];
+    dot += av * bv;
+    normA += av * av;
+    normB += bv * bv;
+  }
+  if (normA === 0 || normB === 0) return 1;
+  return 1 - dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// src/internal/store.ts
+var InMemoryCacheStore = class {
+  constructor(maxEntries) {
+    this.maxEntries = maxEntries;
+  }
+  maxEntries;
+  map = /* @__PURE__ */ new Map();
+  counters = {
+    kvHits: 0,
+    semanticHits: 0,
+    misses: 0,
+    excluded: 0,
+    evicted: 0,
+    embedderFailures: 0
+  };
+  kvGet(key, now) {
+    const e = this.map.get(key);
+    if (e === void 0) return void 0;
+    if (e.expiresAt <= now) {
+      this.map.delete(key);
+      this.counters.evicted += 1;
+      return void 0;
+    }
+    this.map.delete(key);
+    this.map.set(key, { ...e, accessedAt: now, accessCount: e.accessCount + 1 });
+    return this.map.get(key);
+  }
+  isEligibleForSearch(e, embedderId, namespace, dim, now) {
+    if (e.embedderId !== embedderId) return false;
+    if (e.namespace !== namespace) return false;
+    if (e.vector.length !== dim) return false;
+    if (e.expiresAt <= now) return false;
+    return true;
+  }
+  semanticSearch(vector, threshold, embedderId, namespace, now) {
+    let best;
+    for (const e of this.map.values()) {
+      if (!this.isEligibleForSearch(e, embedderId, namespace, vector.length, now)) continue;
+      const d = cosineDistance(e.vector, vector);
+      if (d <= threshold && (best === void 0 || d < best.distance)) {
+        best = { entry: e, distance: d };
+      }
+    }
+    if (best !== void 0) {
+      this.map.delete(best.entry.key);
+      this.map.set(best.entry.key, {
+        ...best.entry,
+        accessedAt: now,
+        accessCount: best.entry.accessCount + 1
+      });
+    }
+    return best;
+  }
+  set(entry) {
+    if (this.map.has(entry.key)) {
+      this.map.delete(entry.key);
+    }
+    this.map.set(entry.key, entry);
+    while (this.map.size > this.maxEntries) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.map.delete(oldestKey);
+      this.counters.evicted += 1;
+    }
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+  async clear() {
+    this.map.clear();
+  }
+  stats() {
+    return {
+      entries: this.map.size,
+      kvHits: this.counters.kvHits,
+      semanticHits: this.counters.semanticHits,
+      misses: this.counters.misses,
+      excluded: this.counters.excluded,
+      evicted: this.counters.evicted,
+      embedderFailures: this.counters.embedderFailures
+    };
+  }
+  evictExpired(now) {
+    let count = 0;
+    for (const [k, e] of this.map.entries()) {
+      if (e.expiresAt <= now) {
+        this.map.delete(k);
+        count += 1;
+      }
+    }
+    this.counters.evicted += count;
+    return count;
+  }
+  loadAll(entries) {
+    for (const e of entries) this.map.set(e.key, e);
+  }
+  dump() {
+    return [...this.map.values()];
+  }
+  /** Internal helpers for counters (used by lookup/store handlers). */
+  incrementKvHits() {
+    this.counters.kvHits += 1;
+  }
+  incrementSemanticHits() {
+    this.counters.semanticHits += 1;
+  }
+  incrementMisses() {
+    this.counters.misses += 1;
+  }
+  incrementExcluded() {
+    this.counters.excluded += 1;
+  }
+  incrementEmbedderFailures() {
+    this.counters.embedderFailures += 1;
+  }
+};
+
+// src/types/cache.ts
+var CacheEmbedderError = class extends Error {
+  name = "CacheEmbedderError";
+  cause;
+  constructor(message, cause) {
+    super(`Cache embedder failed: ${message}`);
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var CacheInvalidTtlError = class extends Error {
+  constructor(input) {
+    super(
+      `Invalid TTL value: "${String(input)}". Expected number (seconds) or string like "1h" / "30m" / "7d".`
+    );
+    this.input = input;
+  }
+  input;
+  name = "CacheInvalidTtlError";
+};
+
+// src/internal/ttl.ts
+var TTL_PATTERN = /^(\d+)\s*(s|m|h|d|w)$/i;
+function parseTtlMs(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0) {
+      throw new CacheInvalidTtlError(input);
+    }
+    return Math.floor(input * 1e3);
+  }
+  const trimmed = input.trim();
+  const m = TTL_PATTERN.exec(trimmed);
+  if (m === null) {
+    throw new CacheInvalidTtlError(input);
+  }
+  const value = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  switch (unit) {
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 6e4;
+    case "h":
+      return value * 36e5;
+    case "d":
+      return value * 864e5;
+    case "w":
+      return value * 6048e5;
+    /* c8 ignore next 2 */
+    default:
+      throw new CacheInvalidTtlError(input);
+  }
+}
+
+// src/internal/store-handler.ts
+async function performStore(p) {
+  const span = startCacheStoreSpan({
+    namespace: p.namespace,
+    embedderId: p.embedder.id
+  });
+  try {
+    if (p.prompt.trim().length === 0) {
+      span.setAttribute("cache.bypass_reason", "empty_prompt");
+      return;
+    }
+    if (p.response.length === 0) {
+      span.setAttribute("cache.bypass_reason", "empty_response");
+      return;
+    }
+    if (p.usedTools === true) {
+      span.setAttribute("cache.bypass_reason", "used_tools");
+      return;
+    }
+    if (p.ttl.exclude?.test(p.prompt)) {
+      span.setAttribute("cache.bypass_reason", "exclude_regex");
+      return;
+    }
+    const key = computeCacheKey({
+      namespace: p.namespace,
+      embedderId: p.embedder.id,
+      modelId: p.modelId,
+      prompt: p.prompt
+    });
+    const vec = await embedOrDegrade(p.embedder, p.prompt, p.store, span, "store");
+    if (vec === void 0) return;
+    const now = Date.now();
+    const ttlMs = parseTtlMs(p.ttl.default);
+    p.store.set({
+      key,
+      namespace: p.namespace,
+      embedderId: p.embedder.id,
+      modelId: p.modelId,
+      prompt: p.prompt,
+      response: p.response,
+      vector: vec,
+      createdAt: now,
+      expiresAt: now + ttlMs,
+      accessedAt: now,
+      accessCount: 0
+    });
+    span.setAttribute("cache.stored", true);
+  } finally {
+    span.end();
+  }
+}
+var FLUSH_DEBOUNCE_MS = 200;
+var JsonFileCacheStore = class {
+  constructor(dir, namespace, maxEntries) {
+    this.dir = dir;
+    this.namespace = namespace;
+    this.inner = new InMemoryCacheStore(maxEntries);
+  }
+  dir;
+  namespace;
+  inner;
+  flushTimer;
+  dirty = false;
+  /** Hydrate from disk. EC-7: corrupt file → empty cache. */
+  async hydrate() {
+    const file = this.filePath();
+    try {
+      const raw = await readFile(file, "utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        console.warn(
+          `[cache] corrupt snapshot at ${file}, starting fresh:`,
+          err instanceof Error ? err.message : err
+        );
+        return;
+      }
+      if (parsed._schemaVersion !== 1) {
+        console.warn(
+          `[cache] unsupported schema v${parsed._schemaVersion} at ${file}, starting fresh`
+        );
+        return;
+      }
+      const valid = parsed.entries.filter((e) => e.namespace === this.namespace);
+      this.inner.loadAll(valid);
+    } catch (err) {
+      if (err.code === "ENOENT") return;
+      console.warn(`[cache] failed to read ${file}:`, err instanceof Error ? err.message : err);
+    }
+  }
+  kvGet(key, now) {
+    return this.inner.kvGet(key, now);
+  }
+  semanticSearch(vector, threshold, embedderId, namespace, now) {
+    return this.inner.semanticSearch(vector, threshold, embedderId, namespace, now);
+  }
+  set(entry) {
+    this.inner.set(entry);
+    this.markDirty();
+  }
+  delete(key) {
+    this.inner.delete(key);
+    this.markDirty();
+  }
+  async clear() {
+    await this.inner.clear();
+    this.markDirty();
+    await this.flush();
+  }
+  stats() {
+    return this.inner.stats();
+  }
+  evictExpired(now) {
+    const n = this.inner.evictExpired(now);
+    if (n > 0) this.markDirty();
+    return n;
+  }
+  /** Force write the current snapshot. Called on shutdown / clear. */
+  async flush() {
+    if (this.flushTimer !== void 0) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+    if (!this.dirty) return;
+    await this.writeSnapshot();
+    this.dirty = false;
+  }
+  /** Counters proxied to inner. */
+  incrementKvHits() {
+    this.inner.incrementKvHits();
+  }
+  incrementSemanticHits() {
+    this.inner.incrementSemanticHits();
+  }
+  incrementMisses() {
+    this.inner.incrementMisses();
+  }
+  incrementExcluded() {
+    this.inner.incrementExcluded();
+  }
+  incrementEmbedderFailures() {
+    this.inner.incrementEmbedderFailures();
+  }
+  filePath() {
+    return join(this.dir, `${this.namespace}.json`);
+  }
+  markDirty() {
+    this.dirty = true;
+    if (this.flushTimer === void 0) {
+      this.flushTimer = setTimeout(() => {
+        this.flushTimer = void 0;
+        void this.flush().catch(
+          (err) => console.warn(`[cache] debounced flush failed:`, err instanceof Error ? err.message : err)
+        );
+      }, FLUSH_DEBOUNCE_MS);
+    }
+  }
+  async writeSnapshot() {
+    await mkdir(this.dir, { recursive: true });
+    const snapshot = {
+      _schemaVersion: 1,
+      namespace: this.namespace,
+      entries: this.inner.dump()
+    };
+    const serialized = JSON.stringify(snapshot);
+    await atomicWriteText(this.filePath(), serialized);
+  }
+};
+
+// src/cache.ts
+var CacheSemanticOptionsSchema = z.object({
+  embedder: z.unknown().refine(
+    (v) => {
+      if (v === null || typeof v !== "object") return false;
+      const o = v;
+      return typeof o.id === "string" && typeof o.embed === "function" && typeof o.dimension === "number";
+    },
+    { message: "embedder must be a CacheEmbedderRuntime with { id, dimension, embed }" }
+  ),
+  threshold: z.number().min(0).max(2).optional(),
+  ttl: z.object({
+    default: z.union([z.string(), z.number()]),
+    exclude: z.instanceof(RegExp).optional()
+  }).optional(),
+  namespace: z.string().min(1).max(64).optional(),
+  modelId: z.string().min(1).max(128).optional(),
+  maxEntries: z.number().int().min(1).max(1e6).optional(),
+  persistence: PersistenceSchema
+});
+var DEFAULT_THRESHOLD = 0.85;
+var DEFAULT_TTL = { default: "1h" };
+var DEFAULT_NAMESPACE = "global";
+var DEFAULT_MAX_ENTRIES = 1e3;
+var Cache = class _Cache {
+  constructor(embedder, threshold, ttl, namespace, modelId, store) {
+    this.embedder = embedder;
+    this.threshold = threshold;
+    this.ttl = ttl;
+    this.namespace = namespace;
+    this.modelId = modelId;
+    this.store = store;
+  }
+  embedder;
+  threshold;
+  ttl;
+  namespace;
+  modelId;
+  store;
+  _plugin;
+  static semantic(options) {
+    CacheSemanticOptionsSchema.parse(options);
+    const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+    const ttl = options.ttl ?? DEFAULT_TTL;
+    const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+    const modelId = options.modelId ?? "unknown";
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const store = createStore(namespace, maxEntries, options.persistence);
+    return new _Cache(options.embedder, threshold, ttl, namespace, modelId, store);
+  }
+  /**
+   * EC-4 absorbed: memoized so repeated `asPlugin()` calls return the SAME
+   * plugin descriptor — no duplicate hook registration.
+   */
+  asPlugin() {
+    if (this._plugin !== void 0) return this._plugin;
+    const cache = this;
+    this._plugin = definePlugin({
+      name: `cache-semantic-${this.namespace}`,
+      version: "1.0.0",
+      kind: "general",
+      register(ctx) {
+        ctx.on("pre_user_send", async (rawCtx) => {
+          const c = rawCtx;
+          const result = await performLookup({
+            prompt: c.prompt,
+            store: cache.store,
+            embedder: cache.embedder,
+            threshold: cache.threshold,
+            ttl: cache.ttl,
+            namespace: cache.namespace,
+            modelId: cache.modelId
+          });
+          if (result.cached === true) {
+            const wrapped = {
+              recalledContext: result.response
+            };
+            return wrapped;
+          }
+          const miss = {};
+          return miss;
+        });
+        ctx.on("post_assistant_reply", async (rawCtx) => {
+          const c = rawCtx;
+          await performStore({
+            prompt: c.prompt,
+            response: c.reply,
+            usedTools: false,
+            store: cache.store,
+            embedder: cache.embedder,
+            ttl: cache.ttl,
+            namespace: cache.namespace,
+            modelId: cache.modelId
+          });
+          return void 0;
+        });
+      }
+    });
+    return this._plugin;
+  }
+  /**
+   * Explicit cache lookup — callers that want true LLM short-circuit
+   * call this BEFORE `agent.send()`, then dispatch to the LLM only on miss.
+   *
+   * v1 plugin mode provides recall + context-inject (LLM still called).
+   * v1.x will add transparent short-circuit via an agent-loop refactor.
+   */
+  async consult(prompt) {
+    const result = await performLookup({
+      prompt,
+      store: this.store,
+      embedder: this.embedder,
+      threshold: this.threshold,
+      ttl: this.ttl,
+      namespace: this.namespace,
+      modelId: this.modelId
+    });
+    if (result.cached === true) {
+      return {
+        hit: true,
+        response: result.response ?? "",
+        source: result.source ?? "kv",
+        ...result.distance !== void 0 ? { distance: result.distance } : {}
+      };
+    }
+    return { hit: false };
+  }
+  /**
+   * Explicit cache store — pair with `consult()` to manually feed the
+   * cache after dispatching the LLM call yourself.
+   */
+  async remember(prompt, response, opts) {
+    await performStore({
+      prompt,
+      response,
+      usedTools: opts?.usedTools === true,
+      store: this.store,
+      embedder: this.embedder,
+      ttl: this.ttl,
+      namespace: this.namespace,
+      modelId: this.modelId
+    });
+  }
+  /** Stats snapshot — primary observable for dogfood verification. */
+  stats() {
+    return this.store.stats();
+  }
+  /** Clear all entries (and flush to disk if JSON backend). */
+  async clear() {
+    await this.store.clear();
+  }
+  /** Force-evict expired entries. Returns count removed. */
+  evictExpired(now = Date.now()) {
+    return this.store.evictExpired(now);
+  }
+};
+function createStore(namespace, maxEntries, persistence) {
+  if (persistence?.backend === "json") {
+    const dir = persistence.dir;
+    const store = new JsonFileCacheStore(dir, namespace, maxEntries);
+    void store.hydrate();
+    return store;
+  }
+  return new InMemoryCacheStore(maxEntries);
+}
+
+export { Cache, CacheEmbedderError, CacheInvalidTtlError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map