@theokit/sdk-cache 0.3.1 → 1.0.0

package/dist/index.d.cts

@@ -6,44 +6,170 @@ import { Plugin } from '@theokit/sdk';
  *
  * @public
  */
+/**
+ * How long entries live, and which prompts never become entries at all.
+ *
+ * @public
+ */
 interface CacheTTLConfig {
-    /** Default TTL applied to all entries. Format: `"1h" | "30m" | 86400 (seconds)`. */
+    /**
+     * Lifetime applied to every entry written, evaluated at write time.
+     *
+     * A NUMBER is SECONDS (`3600` is an hour). A STRING needs a unit suffix — `s`, `m`, `h`, `d`, `w`
+     * (`"30m"`, `"1h"`, `"7d"`). A bare numeric string is not a duration: `"3600"` throws
+     * {@link CacheInvalidTtlError}, and so do a negative number and an unknown unit. `0` / `"0s"`
+     * parses fine and writes entries that are already expired, which disables the cache without
+     * disabling the embedding calls.
+     *
+     * The throw happens on the WRITE, not at `Cache.semantic(...)` — a bad value survives
+     * construction and surfaces on the first `remember()` or the first cached assistant reply.
+     */
     readonly default: string | number;
-    /** Regex marking queries that must NEVER be cached (e.g. /weather|today|now/i). */
+    /**
+     * Prompts matching this regex are never cached — e.g. `/weather|today|now/i` for anything whose
+     * answer goes stale.
+     *
+     * Applies to BOTH directions: a matching prompt is not looked up (it counts as
+     * {@link CacheStats.excluded}, not a miss) and not stored. Test it against your real prompts —
+     * a regex broad enough to match every question disables the cache while every counter still
+     * looks healthy.
+     *
+     * Bring your own regex object; a `/g` flag is a hazard here because `RegExp.test` is stateful
+     * with it and would match every other call.
+     */
     readonly exclude?: RegExp;
 }
+/**
+ * Where cached entries live between process restarts.
+ *
+ * `"memory"` (the default when {@link CacheSemanticOptions.persistence} is omitted) keeps everything
+ * in the process and loses it on exit — right for a request-scoped worker, wrong for a CLI that runs
+ * once per invocation and would never see a hit.
+ *
+ * `"json"` writes the whole entry set, VECTORS INCLUDED, to a file under `dir`. That file grows with
+ * `maxEntries` × the embedder's dimension, so a 1000-entry cache over a 1536-dimension embedder is
+ * on the order of megabytes, and it is plaintext: every prompt and response is readable. Do not point
+ * `dir` at a directory that gets committed.
+ */
 interface CachePersistenceOptions {
+    /** `"memory"` for process-local, `"json"` for a file under {@link CachePersistenceOptions.dir}. */
     readonly backend: "memory" | "json";
-    /** Required when backend = "json". */
+    /**
+     * Directory holding `<namespace>.json`. REQUIRED when `backend` is `"json"` — omitting it makes
+     * `Cache.semantic(...)` throw `ZodError`, it is not silently downgraded to memory.
+     *
+     * Created recursively on the first write. Writes are atomic but DEBOUNCED by 200 ms, and loading
+     * is fire-and-forget, so the file is eventually-consistent with memory in both directions. A
+     * corrupt or wrong-schema file is logged and treated as an empty cache — it never blocks startup.
+     */
     readonly dir?: string;
 }
 /**
  * Embedder runtime shape — minimal subset of `EmbeddingRuntime` (D11) the
  * Cache actually uses. Lets tests inject fake embedders without pulling
  * the full memory subsystem.
+ *
+ * `@theokit/sdk-cache` ships one implementation, `createLexicalEmbedder()`; anything with these
+ * four members works, including a wrapper around a provider's embedding endpoint.
+ *
+ * @public
  */
 interface CacheEmbedderRuntime {
+    /**
+     * Stable identity of this embedding SPACE, not of the object.
+     *
+     * It is part of the exact-match key and of the semantic eligibility filter, so changing it
+     * invalidates every existing entry — which is the point: vectors from two different embedders
+     * are not comparable, and a shared id would let one embedder's vectors be matched against
+     * another's. Version it whenever the model, its parameters or the dimension change.
+     */
     readonly id: string;
+    /** Human-facing model name. Recorded for diagnostics; the cache never keys on it. */
     readonly model: string;
+    /**
+     * Length of the vectors `embed` returns.
+     *
+     * Entries whose stored vector has a different length are skipped during the semantic scan rather
+     * than compared, so a dimension change silently costs you the whole warm cache instead of
+     * throwing.
+     */
     readonly dimension: number;
+    /**
+     * Embed a batch; the cache always passes exactly one text and reads `result[0]`.
+     *
+     * A rejection is NOT propagated to the caller: the cache logs it, counts it in
+     * {@link CacheStats.embedderFailures} and treats the operation as a miss / skipped write. Return
+     * a zero vector only if you want it treated as a non-match, since cosine distance against it is
+     * defined as 1.0.
+     */
     embed(texts: ReadonlyArray<string>): Promise<number[][]>;
 }
+/**
+ * Configuration for `Cache.semantic(...)`.
+ *
+ * Only `embedder` is required, and deliberately so: autoselecting one would make an agent start
+ * calling an embedding API because a cache was enabled, which is a surprise bill rather than a
+ * default. Everything else has a working default.
+ *
+ * The lookup runs in two stages — an exact key match first, then a vector search — so an identical
+ * prompt never pays for an embedding call. Only the second stage consults `threshold`.
+ */
 interface CacheSemanticOptions {
     /** Embedder instance. REQUIRED in v1 — no autoselect (avoids surprise API calls). */
     readonly embedder: CacheEmbedderRuntime;
-    /** Cosine distance threshold (0..2). Default 0.85; lower = stricter. */
+    /**
+     * Maximum cosine DISTANCE (`1 - cosine similarity`) at which a stored entry counts as a match.
+     * Default 0.85. Lower is stricter; 0 requires an identical direction, 1 accepts orthogonal
+     * vectors, and the accepted range is 0..2.
+     *
+     * It is a distance and not a similarity, so raising it LOOSENS matching — 0.85 is already
+     * permissive for normalized embeddings and will return semantically unrelated answers if your
+     * embedder spreads vectors narrowly. Only the vector stage consults it; an exact-key hit ignores
+     * it entirely. Watch {@link CacheStats.semanticHits} when you tune it.
+     */
     readonly threshold?: number;
     /** TTL config. Default `{ default: "1h" }`. */
     readonly ttl?: CacheTTLConfig;
-    /** Multi-tenant namespace. Default `"global"`. */
+    /**
+     * Isolation bucket, 1..64 chars. Default `"global"`. Entries never match across namespaces.
+     *
+     * It is also the plugin name (`cache-semantic-<namespace>`) and, under `"json"` persistence, the
+     * FILE name. Two caches sharing a namespace and a `dir` therefore share ONE store rather than
+     * racing over one file (#359) — with the consequence that the second one's `maxEntries` is
+     * ignored, since the store already exists.
+     */
     readonly namespace?: string;
-    /** Default modelId attached to entries when caller doesn't override. */
+    /**
+     * Model id stamped on every entry, and part of both the exact key and the semantic eligibility
+     * filter — a response cached for one model is never returned for another.
+     *
+     * Defaults to the literal string `"unknown"`, which is an ORDINARY value rather than a wildcard:
+     * entries written by a cache that defaulted it are visible only to another cache that also
+     * defaults it. Set it to the same id you pass to `Agent.create({ model })`.
+     */
     readonly modelId?: string;
-    /** Max entries (LRU eviction). Default 1000. */
+    /**
+     * Ceiling on stored entries. Default 1000. Exceeding it evicts the least recently used entry and
+     * increments {@link CacheStats.evicted}.
+     *
+     * Sizes the JSON snapshot too: the file holds every entry's full embedding, so this multiplied by
+     * the embedder dimension is the file's order of magnitude.
+     */
     readonly maxEntries?: number;
     /** Persistence backend. Default in-memory. */
     readonly persistence?: CachePersistenceOptions;
 }
+/**
+ * One cached prompt/response pair, as `Cache` stores it.
+ *
+ * Read-only from the outside: entries are produced by the cache, and reach a caller only through a
+ * `"json"` persistence dump. `vector` is the embedding of `prompt`, which is what makes the file
+ * large; `accessedAt` / `accessCount` are what LRU eviction reads when `maxEntries` is reached.
+ *
+ * `key` is the exact-match key (a hash of namespace, embedder, model and prompt), so two entries with
+ * the same prompt under different models are different entries — a cached answer never crosses a
+ * model boundary.
+ */
 interface CacheEntry {
     readonly key: string;
     readonly namespace: string;
@@ -57,6 +183,24 @@ interface CacheEntry {
     readonly accessedAt: number;
     readonly accessCount: number;
 }
+/**
+ * Counters returned by `Cache.stats()`. All monotonic within a process; a `"json"` backend does not
+ * restore them, so they count THIS process's traffic, not the file's history.
+ *
+ * The three miss-shaped counters are distinct on purpose, and the distinction is the point of
+ * reading stats at all:
+ *
+ * - `misses` — looked up, nothing matched. The cache is working and cold. An empty or
+ *   whitespace-only prompt also lands here, having never been looked up at all.
+ * - `excluded` — {@link CacheTTLConfig.exclude} matched the prompt, so no lookup happened. High and
+ *   unexpected means the regex is too broad.
+ * - `embedderFailures` — the embedder threw. The lookup DEGRADES to a miss rather than failing the
+ *   call, so a broken embedder shows up here as a rising number and nowhere else. A cache that
+ *   suddenly stops hitting, with this climbing, is an embedder outage — not a cold cache.
+ *
+ * `kvHits` counts exact-key matches (no embedding call); `semanticHits` counts vector matches.
+ * A `semanticHits` of zero with healthy `kvHits` means `threshold` is too strict.
+ */
 interface CacheStats {
     readonly entries: number;
     readonly kvHits: number;
@@ -66,11 +210,18 @@ interface CacheStats {
     readonly evicted: number;
     readonly embedderFailures: number;
 }
-declare class CacheEmbedderError extends Error {
-    readonly name = "CacheEmbedderError";
-    readonly cause?: Error;
-    constructor(message: string, cause?: Error);
-}
+/**
+ * A TTL value that could not be parsed, thrown at configuration time rather than on first use.
+ *
+ * Accepts a number of SECONDS, or a string with a unit suffix `s` / `m` / `h` / `d` / `w`
+ * (`"30m"`, `"1h"`, `"7d"`). A bare numeric string is not a duration — `"3600"` is rejected,
+ * `3600` is an hour. Also rejected: a negative or non-finite number, and any unit outside that
+ * set. `input` carries what was passed, so the message names the offending value rather than the
+ * field.
+ *
+ * "Configuration time" means the first WRITE that applies the TTL, not `Cache.semantic(...)` —
+ * `CacheSemanticOptions` is validated for shape, never for TTL parseability.
+ */
 declare class CacheInvalidTtlError extends Error {
     readonly input: string | number;
     readonly name = "CacheInvalidTtlError";
@@ -83,28 +234,52 @@ declare class CacheInvalidTtlError extends Error {
  *
  * Usage:
  *
- *   import { Agent, Cache, definePlugin } from "@theokit/sdk";
+ *   import { Agent } from "@theokit/sdk";
+ *   import { Cache, createLexicalEmbedder } from "@theokit/sdk-cache";
  *
  *   const cache = Cache.semantic({
- *     embedder: myEmbedderRuntime,    // EmbeddingRuntime (D11)
+ *     embedder: createLexicalEmbedder(),   // or any CacheEmbedderRuntime
  *     threshold: 0.85,
  *     ttl: { default: "1h", exclude: /weather|today|now/i },
  *     namespace: "my-app",
  *     modelId: "openai/gpt-4o-mini",
  *   });
  *
+ *   // (a) Plugin mode — the cached answer is INJECTED as context; the LLM is still called.
  *   const agent = await Agent.create({
  *     model: { id: "openai/gpt-4o-mini" },
  *     plugins: [cache.asPlugin()],
- *     // ...
  *   });
  *
- *   await agent.send("What is the capital of France?");   // miss → LLM
- *   await agent.send("Tell me the capital of France");    // semantic hit
+ *   // (b) Explicit mode — this is the one that skips the LLM call.
+ *   const hit = await cache.consult(prompt);
+ *   const answer = hit.hit ? hit.response : await callTheModel(prompt);
+ *   if (!hit.hit) await cache.remember(prompt, answer);
+ *
+ * The distinction between (a) and (b) is the single most important thing to know about this
+ * package — see `Cache.asPlugin`.
  *
  * @public
  */
 
+/**
+ * A semantic response cache: an exact-key lookup, then a vector-similarity lookup, over
+ * prompt/response pairs the caller has stored.
+ *
+ * Build one with {@link Cache.semantic}; `new Cache()` is a compile error. One instance owns one
+ * store, so two `Cache.semantic(...)` calls never share entries even under the same `namespace`
+ * and the same `dir` — the JSON backend will have both instances writing the same file.
+ *
+ * Two ways to use it, and they do NOT save the same thing:
+ *
+ * | | {@link Cache.consult} + {@link Cache.remember} | {@link Cache.asPlugin} |
+ * |---|---|---|
+ * | LLM call on a hit | skipped | still made |
+ * | What you save | the whole call | nothing, today |
+ * | Who drives it | you | the agent loop |
+ *
+ * @public
+ */
 declare class Cache {
     private readonly embedder;
     private readonly threshold;
@@ -112,20 +287,92 @@ declare class Cache {
     private readonly namespace;
     private readonly modelId;
     private readonly store;
+    private readonly hydrated;
     private _plugin?;
     private constructor();
+    /**
+     * Resolves once the `"json"` backend has finished reading its snapshot; resolves immediately on
+     * the in-memory backend.
+     *
+     * You rarely need it: `consult` and `remember` await hydration themselves, so a cache is correct
+     * without it. It exists for a caller who wants the read charged to startup rather than to the
+     * first lookup — and because the code promised it long before it existed (#359).
+     *
+     * A corrupt or unreadable snapshot resolves normally with an empty cache and a warning on
+     * stderr; a cache must not take the process down.
+     */
+    ready(): Promise<void>;
+    /**
+     * Write the pending snapshot to disk now, keeping every entry. No-op on the in-memory backend.
+     *
+     * Writes are debounced 200ms, so a process that remembers something and exits inside that window
+     * persists nothing — precisely the once-per-invocation CLI the `"json"` backend exists for. Call
+     * this before exiting. Nothing flushes on teardown: an `exit` handler cannot await, and a library
+     * installing a process-level hook is a side effect the caller did not ask for.
+     *
+     * Until #359 the only public call that wrote the snapshot was `clear()`, which also destroyed
+     * everything you wanted to persist.
+     */
+    flush(): Promise<void>;
+    /**
+     * Build a cache. Validates `options` with Zod and THROWS `ZodError` on a bad shape — an
+     * `embedder` missing `{ id, dimension, embed }`, a `threshold` outside `0..2`, a `namespace`
+     * longer than 64 chars, or `persistence: { backend: "json" }` without a `dir`.
+     *
+     * Defaults: `threshold` 0.85, `ttl` `{ default: "1h" }`, `namespace` `"global"`, `maxEntries`
+     * 1000 (LRU), `persistence` in-memory. `modelId` defaults to the literal string `"unknown"`,
+     * which is a real namespace value and not a wildcard: entries stored while `modelId` was
+     * defaulted are only ever returned to lookups that also default it.
+     *
+     * With `persistence: { backend: "json", dir }` the snapshot is read in the background and this
+     * call does not await it — but `consult` and `remember` do, so a lookup issued immediately after
+     * construction still sees what is on disk. Await {@link Cache.ready} to charge the read to
+     * startup instead of to the first lookup. Two caches built with the same `dir` and `namespace`
+     * share one store, so they cannot overwrite each other's snapshot; the FIRST one's `maxEntries`
+     * is the one that applies.
+     */
     static semantic(options: CacheSemanticOptions): Cache;
     /**
-     * EC-4 absorbed: memoized so repeated `asPlugin()` calls return the SAME
-     * plugin descriptor — no duplicate hook registration.
+     * A `Plugin` for `Agent.create({ plugins: [...] })` that reads the cache before each user turn
+     * and writes it after each assistant reply.
+     *
+     * READ THIS BEFORE BUDGETING FOR IT. A hit does NOT skip the model call. The hook returns the
+     * cached response as `PreUserSendResult.recalledContext`, which the agent loop injects as a
+     * `<memory-context>` block ahead of the prompt — the request still goes to the provider, still
+     * costs tokens, and still returns whatever the model makes of that context, which need not be
+     * the cached text. Use {@link Cache.consult} / {@link Cache.remember} when the point is to avoid
+     * the call.
+     *
+     * A turn that invoked tools is NOT cached: the store hook reads
+     * `PostAssistantReplyContext.usedTools`, which the runtime derives from the run's tool calls
+     * (#358). Replaying such an answer would hand a later caller the result of a write that never
+     * happened. Until that signal existed the hook passed a literal `false` and cached those turns,
+     * despite the package's stated intent.
+     *
+     * Memoized: repeated calls return the SAME plugin, so registering it twice does not double the
+     * hooks.
      */
     asPlugin(): Plugin;
     /**
-     * Explicit cache lookup — callers that want true LLM short-circuit
-     * call this BEFORE `agent.send()`, then dispatch to the LLM only on miss.
+     * Look a prompt up. Call it BEFORE dispatching to the model and skip the call on a hit — this is
+     * the only path in this package that actually avoids an LLM request.
+     *
+     * ```ts
+     * const hit = await cache.consult(prompt);
+     * if (hit.hit) return hit.response;
+     * ```
+     *
+     * `source` says which stage matched: `"kv"` is an exact-key match and costs NO embedding call;
+     * `"semantic"` means the prompt was embedded and a stored vector came within `threshold`, and
+     * only then is `distance` present (cosine distance, so smaller is closer).
      *
-     * v1 plugin mode provides recall + context-inject (LLM still called).
-     * v1.x will add transparent short-circuit via an agent-loop refactor.
+     * NEVER THROWS on an embedder failure. It degrades to `{ hit: false }`, logs a warning on
+     * stderr, and increments {@link CacheStats.embedderFailures} — a cache must not take the request
+     * down with it. A cache that has silently stopped hitting is that counter climbing, not a cold
+     * cache.
+     *
+     * An empty or whitespace-only prompt returns `{ hit: false }` and counts as a MISS. A prompt
+     * matching {@link CacheTTLConfig.exclude} returns `{ hit: false }` and counts as `excluded`.
      */
     consult(prompt: string): Promise<{
         hit: false;
@@ -136,17 +383,51 @@ declare class Cache {
         distance?: number;
     }>;
     /**
-     * Explicit cache store — pair with `consult()` to manually feed the
-     * cache after dispatching the LLM call yourself.
+     * Store a prompt/response pair. Pair it with {@link Cache.consult} after you dispatched the model
+     * call yourself.
+     *
+     * Pass `{ usedTools: true }` when the answer came from a run that invoked tools and replaying it
+     * would lose the side effects — the write is then skipped entirely.
+     *
+     * Silently writes nothing when the prompt is empty/whitespace, the response is empty, the prompt
+     * matches {@link CacheTTLConfig.exclude}, or the embedder fails (that last case increments
+     * {@link CacheStats.embedderFailures}). It resolves in every one of those cases: a resolved
+     * promise is not evidence that an entry exists — read {@link CacheStats.entries} if you need
+     * that.
+     *
+     * Writing beyond `maxEntries` evicts the least-recently-used entry. On the `"json"` backend the
+     * disk write is DEBOUNCED by 200 ms, so a process that exits right after this resolves loses the
+     * entry unless it calls {@link Cache.flush} — which writes the snapshot and keeps every entry.
+     * Nothing flushes on teardown.
      */
     remember(prompt: string, response: string, opts?: {
         usedTools?: boolean;
     }): Promise<void>;
-    /** Stats snapshot — primary observable for dogfood verification. */
+    /**
+     * Counter snapshot for this instance. See {@link CacheStats} for what each counter separates —
+     * in particular `misses` vs `excluded` vs `embedderFailures`, which is how you tell a cold cache
+     * from a too-broad exclude regex from a broken embedder.
+     *
+     * Process-local: the `"json"` backend persists entries, never counters, so a restart reports
+     * zeros against a warm file.
+     */
     stats(): CacheStats;
-    /** Clear all entries (and flush to disk if JSON backend). */
+    /**
+     * Drop every entry. On the `"json"` backend this also forces the debounced snapshot to disk
+     * immediately, so it is the one public call that guarantees the file matches memory.
+     *
+     * Counters are NOT reset — `stats()` keeps reporting the hits and misses accumulated before the
+     * clear, so `entries: 0` alongside a non-zero `kvHits` is expected, not a bug.
+     */
     clear(): Promise<void>;
-    /** Force-evict expired entries. Returns count removed. */
+    /**
+     * Remove every entry whose TTL has elapsed, returning how many were dropped, and add that to
+     * {@link CacheStats.evicted}.
+     *
+     * Optional housekeeping: expired entries are already skipped on lookup and dropped when touched,
+     * so this only reclaims memory for entries nobody asks for. `now` exists to make the sweep
+     * testable; leave it out in production.
+     */
     evictExpired(now?: number): number;
 }
 
@@ -167,6 +448,26 @@ declare class Cache {
  * @public
  */
 
+/**
+ * Build the built-in lexical embedder — a zero-dependency, zero-cost `CacheEmbedderRuntime`.
+ *
+ * ```ts
+ * const cache = Cache.semantic({ embedder: createLexicalEmbedder() });
+ * ```
+ *
+ * Matches on SHARED WORDS, not on meaning. "What is the capital of France?" and "Tell me the
+ * capital of France" land close together; "capital of France" and "French capital" do not. If you
+ * need paraphrase-level hits, wrap a real embedding API instead — that is what
+ * `CacheEmbedderRuntime` is for.
+ *
+ * `dimension` (default 256) is the number of hash buckets. Raising it reduces collisions between
+ * unrelated words, which is the failure mode here: a collision makes two unrelated prompts look
+ * similar and can serve a wrong cached answer. It is also baked into the returned `id`
+ * (`theokit-lexical-v1-d<dimension>`), so CHANGING IT INVALIDATES every entry already stored — the
+ * cache keys on the embedder id and skips vectors of a different length.
+ *
+ * Never rejects, and never calls the network.
+ */
 declare function createLexicalEmbedder(dimension?: number): CacheEmbedderRuntime;
 
-export { Cache, CacheEmbedderError, type CacheEmbedderRuntime, type CacheEntry, CacheInvalidTtlError, type CachePersistenceOptions, type CacheSemanticOptions, type CacheStats, type CacheTTLConfig, createLexicalEmbedder };
+export { Cache, type CacheEmbedderRuntime, type CacheEntry, CacheInvalidTtlError, type CachePersistenceOptions, type CacheSemanticOptions, type CacheStats, type CacheTTLConfig, createLexicalEmbedder };