@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/fallback-Bx46zqky.d.cts

@@ -0,0 +1,243 @@
+import { KvStorageTier } from '@graphrefly/pure-ts/extra';
+import { a as ChatMessage, b as LLMInvokeOptions, L as LLMAdapter, c as LLMResponse, S as StreamDelta } from './types-BB5Lw-pB.cjs';
+
+/**
+ * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
+ *
+ * - Key: sha256 of canonicalized (messages + invoke options minus `signal`).
+ * - `"read-write"` (default): returns cached response if present; on miss,
+ *   passes through and stores the result.
+ * - `"write-only"`: never reads; populates the cache for later runs.
+ * - `"read"`: reads only; on miss, passes through without writing.
+ * - `"read-strict"`: reads only; on miss, **throws `ReplayCacheMissError`**
+ *   instead of passing through. Use for fixture-driven tests or offline
+ *   fallback adapters where any cache miss is a test failure or a signal to
+ *   degrade.
+ *
+ * Reuses the library's existing `KvStorageTier` abstraction — any kv tier
+ * (memoryKv / fileKv / sqliteKv / indexedDbKv / custom).
+ *
+ * **Concurrent cache-miss dedup:** uses `singleFromAny` so two concurrent
+ * calls with the same key share one upstream request. Second caller sees the
+ * same response that the first caller fetched; no duplicate provider spend.
+ *
+ * **Circular-ref safe:** `canonicalJson` uses a seen-set replacer so
+ * user-supplied `ToolDefinition.parameters` with `$ref` cycles don't stack-
+ * overflow the key computation.
+ *
+ * **Stream cadence capture:** when `cacheStreaming: true` AND
+ * `captureStreamCadence: true`, per-chunk delays (ms since previous chunk)
+ * are recorded alongside the content. Replay honors the recorded cadence
+ * unless `replaySpeed` is set, which multiplies the effective per-chunk
+ * delay (`replaySpeed: 2` → 2× faster; `replaySpeed: 0` → instant).
+ * Without `captureStreamCadence`, replay is instant regardless.
+ */
+
+type ReplayCacheMode = "read" | "read-strict" | "write-only" | "read-write";
+declare class ReplayCacheMissError extends Error {
+    readonly key: string;
+    readonly method: "invoke" | "stream";
+    name: string;
+    constructor(key: string, method: "invoke" | "stream");
+}
+/**
+ * Context object passed to {@link WithReplayCacheOptions.keyFn}. Extending
+ * with additional fields is forward-compatible — current implementations
+ * ignoring unknown fields continue to work.
+ */
+interface ReplayCacheKeyContext {
+    readonly messages: readonly ChatMessage[];
+    readonly opts: LLMInvokeOptions | undefined;
+    /** Shortcut to `opts?.keyContext` — avoids an extra guard in callers. */
+    readonly context: unknown;
+}
+interface WithReplayCacheOptions {
+    storage: KvStorageTier;
+    mode?: ReplayCacheMode;
+    /**
+     * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
+     * chat messages, the invoke options, and the caller-supplied
+     * `opts.keyContext`. Defaults to sha256 of canonical JSON over
+     * `(messages, opts without signal/keyContext)`.
+     *
+     * Legacy 2-arg form `(messages, opts?)` also accepted — the adapter
+     * detects arity and dispatches. Prefer the object form for new code.
+     */
+    keyFn?: ((ctx: ReplayCacheKeyContext) => string | Promise<string>) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | Promise<string>);
+    /** Prefix for cached keys (useful when sharing a tier across domains). */
+    keyPrefix?: string;
+    /**
+     * Whether to cache streaming responses (by consuming the full stream
+     * and replaying it as one synthetic token chunk). Default `false`.
+     */
+    cacheStreaming?: boolean;
+    /**
+     * When `cacheStreaming: true`, also record per-chunk delays (ms since
+     * previous chunk) so replay can honor the original streaming cadence.
+     * Default `false` (chunks replay instantly).
+     */
+    captureStreamCadence?: boolean;
+    /**
+     * Stream replay speed multiplier. `1` = original cadence (requires
+     * `captureStreamCadence`). `2` = 2× faster. `0` = instant. Default `1`.
+     */
+    replaySpeed?: number;
+}
+/** Wrap an adapter with a replay cache. */
+declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
+
+/**
+ * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
+ * deterministic tests, and graceful degradation in production.
+ *
+ * A peer of `anthropicAdapter` / `openAICompatAdapter` / `googleAdapter` /
+ * `ollamaAdapter` / `dryRunAdapter`, but whose role is to serve pre-recorded
+ * or canned responses when real providers aren't reachable. Install it as a
+ * tier via the existing routing primitives (no new composer needed):
+ *
+ * ```ts
+ * // Graceful offline fallback for a user app:
+ * resilientAdapter(anthropicAdapter({ ... }), {
+ *   fallback: fallbackAdapter({ fixturesDir: "./fixtures" }),
+ * });
+ *
+ * // Or the general N-tier shape:
+ * cascadingLlmAdapter([
+ *   { name: "primary",  adapter: anthropicAdapter({ ... }) },
+ *   { name: "fallback", adapter: fallbackAdapter({ fixturesDir: "./fixtures" }) },
+ * ]);
+ * ```
+ *
+ * The `provider` field is `"fallback"` so its role is self-documenting in
+ * logs, stats, cost tables, and audit trails.
+ *
+ * ## Three fixture sources (mutually exclusive)
+ *
+ * Pick exactly one of:
+ *
+ * 1. **`fixtures: FallbackFixture[]`** — inline, hand-authored. Supports
+ *    both hash-keyed and messages-keyed shapes; the adapter computes the
+ *    canonical hash for messages-keyed entries at init time. Ideal when you
+ *    want full control in code (tests, small demos).
+ *
+ * 2. **`fixturesStorage: KvStorageTier`** — the escape hatch for any backend.
+ *    Pass a `memoryKv()`, `indexedDbKv(...)`, `sqliteKv(...)`,
+ *    `cascadingCache(...)`, or a custom tier. You own the layout — no
+ *    auto-namespacing.
+ *
+ *    **Filesystem directories (Node only):** the core `fallbackAdapter`
+ *    does NOT import `node:fs` / `node:path` — it's safe to bundle for
+ *    browsers. For a directory convenience, import `fallbackAdapter` from
+ *    `@graphrefly/graphrefly/patterns/ai/node` (node subpath);
+ *    that variant adds `fixturesDir: string` (auto-namespaced to
+ *    `join(dir, keyPrefix)`, cache-format validated at init).
+ *
+ * ## Record mode
+ *
+ * `record: { adapter: real, storage }` proxies every call to `real` AND
+ * persists the response through the provided tier. Use the node subpath's
+ * `fallbackAdapter` for `record.dir` (auto-namespaced + `record.dir` defaults
+ * to `fixturesDir` when both are file-backed).
+ *
+ * ## Three use cases, one implementation
+ *
+ * | Use case | Config |
+ * |---|---|
+ * | **User apps** — degrade when the cloud provider errors or network is down | `fallbackAdapter({ fixturesStorage: ... })` installed as a fallback tier |
+ * | **Tests** — deterministic replays, fail loudly on miss | `fallbackAdapter({ fixturesStorage: ..., onMiss: "throw" })` |
+ * | **Eval offline replay** — zero-spend repeat runs | `fallbackAdapter({ fixturesStorage: ... })` as the only adapter |
+ *
+ * ## Implementation
+ *
+ * Thin sugar over {@link withReplayCache}. Key shape comes from its
+ * `canonicalJson` — fixtures written by either tool are interchangeable.
+ *
+ * @module
+ */
+
+type FallbackMissPolicy = "throw" | "respond";
+/**
+ * Thrown when `fallbackAdapter({ onMiss: "throw" })` receives a request that
+ * has no matching fixture. Alias of `ReplayCacheMissError` for now — the
+ * adapter is a thin sugar over `withReplayCache` and shares its miss-error.
+ */
+declare const FallbackMissError: typeof ReplayCacheMissError;
+type FallbackMissError = ReplayCacheMissError;
+/**
+ * One recorded fixture. Two authoring shapes:
+ * - **Hash-keyed** — `{ key, response, stream? }`. Key is `sha256(canonicalJson({messages, opts}))`
+ *   with `fallback:` prefix. This is what `record` mode writes.
+ * - **Messages-keyed** — `{ messages, invokeOpts?, response }`. The adapter
+ *   computes the key at init time. Ergonomic for hand-authored fixtures.
+ */
+type FallbackFixture = {
+    readonly key: string;
+    readonly response: LLMResponse;
+    readonly stream?: {
+        readonly chunks: readonly StreamDelta[];
+        readonly delaysMs?: readonly number[];
+    };
+} | {
+    readonly messages: readonly ChatMessage[];
+    readonly invokeOpts?: Omit<LLMInvokeOptions, "signal">;
+    readonly response: LLMResponse;
+};
+interface FallbackAdapterOptions {
+    /** Adapter provider label. Default `"fallback"`. */
+    readonly provider?: string;
+    /** Adapter model label. Default `"fallback"`. */
+    readonly model?: string;
+    /**
+     * Inline hand-authored fixtures. Supports both hash-keyed (`{key, response, stream?}`)
+     * and messages-keyed (`{messages, invokeOpts?, response}`) shapes — the adapter
+     * computes the canonical hash for messages-keyed entries at init time. Held in
+     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
+     * `fixturesStorage`.
+     */
+    readonly fixtures?: readonly FallbackFixture[];
+    /**
+     * Bring-your-own `KvStorageTier` (`memoryKv`, `sqliteKv`,
+     * `indexedDbKv`, `cascadingCache`, or a custom tier). You own the
+     * layout — no auto-namespacing. Mutually exclusive with `fixtures`.
+     *
+     * For filesystem directories, use the node subpath's `fallbackAdapter`
+     * with its `fixturesDir` option (auto-namespaced + validated).
+     */
+    readonly fixturesStorage?: KvStorageTier;
+    /**
+     * Called on fixture miss when `onMiss === "respond"`. If not provided and
+     * `onMiss === "respond"`, a canned "service unavailable" response is
+     * returned (marked with `metadata.degraded: true`).
+     */
+    readonly respond?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | LLMResponse;
+    /** Miss policy. Default `"respond"`. */
+    readonly onMiss?: FallbackMissPolicy;
+    /**
+     * Record mode. Proxies every call to `record.adapter` AND persists the
+     * result through `record.storage`. For filesystem `record.dir` convenience,
+     * use the node subpath's `fallbackAdapter`.
+     */
+    readonly record?: {
+        readonly adapter: LLMAdapter;
+        readonly storage?: KvStorageTier;
+    };
+    /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
+    readonly replaySpeed?: number;
+    /** Key prefix. Kept compatible with `withReplayCache` defaults. Default `"fallback"`. */
+    readonly keyPrefix?: string;
+    /**
+     * Custom key function — forwarded directly to the underlying
+     * {@link withReplayCache}. Use to shard fixtures by `invokeOpts.keyContext`
+     * (tenant, session, feature flag). Accepts either the new
+     * {@link ReplayCacheKeyContext} object form or the legacy 2-arg
+     * `(messages, opts?)` form.
+     */
+    readonly keyFn?: ((ctx: ReplayCacheKeyContext) => string) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string);
+}
+/**
+ * Build a fixture-backed {@link LLMAdapter}. See module docs for use cases
+ * (offline demo, tests, degraded-mode) and recipe snippets.
+ */
+declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
+
+export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, fallbackAdapter as f, withReplayCache as w };

package/dist/fallback-pIWW8A2d.d.ts

@@ -0,0 +1,243 @@
+import { KvStorageTier } from '@graphrefly/pure-ts/extra';
+import { a as ChatMessage, b as LLMInvokeOptions, L as LLMAdapter, c as LLMResponse, S as StreamDelta } from './types-BB5Lw-pB.js';
+
+/**
+ * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
+ *
+ * - Key: sha256 of canonicalized (messages + invoke options minus `signal`).
+ * - `"read-write"` (default): returns cached response if present; on miss,
+ *   passes through and stores the result.
+ * - `"write-only"`: never reads; populates the cache for later runs.
+ * - `"read"`: reads only; on miss, passes through without writing.
+ * - `"read-strict"`: reads only; on miss, **throws `ReplayCacheMissError`**
+ *   instead of passing through. Use for fixture-driven tests or offline
+ *   fallback adapters where any cache miss is a test failure or a signal to
+ *   degrade.
+ *
+ * Reuses the library's existing `KvStorageTier` abstraction — any kv tier
+ * (memoryKv / fileKv / sqliteKv / indexedDbKv / custom).
+ *
+ * **Concurrent cache-miss dedup:** uses `singleFromAny` so two concurrent
+ * calls with the same key share one upstream request. Second caller sees the
+ * same response that the first caller fetched; no duplicate provider spend.
+ *
+ * **Circular-ref safe:** `canonicalJson` uses a seen-set replacer so
+ * user-supplied `ToolDefinition.parameters` with `$ref` cycles don't stack-
+ * overflow the key computation.
+ *
+ * **Stream cadence capture:** when `cacheStreaming: true` AND
+ * `captureStreamCadence: true`, per-chunk delays (ms since previous chunk)
+ * are recorded alongside the content. Replay honors the recorded cadence
+ * unless `replaySpeed` is set, which multiplies the effective per-chunk
+ * delay (`replaySpeed: 2` → 2× faster; `replaySpeed: 0` → instant).
+ * Without `captureStreamCadence`, replay is instant regardless.
+ */
+
+type ReplayCacheMode = "read" | "read-strict" | "write-only" | "read-write";
+declare class ReplayCacheMissError extends Error {
+    readonly key: string;
+    readonly method: "invoke" | "stream";
+    name: string;
+    constructor(key: string, method: "invoke" | "stream");
+}
+/**
+ * Context object passed to {@link WithReplayCacheOptions.keyFn}. Extending
+ * with additional fields is forward-compatible — current implementations
+ * ignoring unknown fields continue to work.
+ */
+interface ReplayCacheKeyContext {
+    readonly messages: readonly ChatMessage[];
+    readonly opts: LLMInvokeOptions | undefined;
+    /** Shortcut to `opts?.keyContext` — avoids an extra guard in callers. */
+    readonly context: unknown;
+}
+interface WithReplayCacheOptions {
+    storage: KvStorageTier;
+    mode?: ReplayCacheMode;
+    /**
+     * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
+     * chat messages, the invoke options, and the caller-supplied
+     * `opts.keyContext`. Defaults to sha256 of canonical JSON over
+     * `(messages, opts without signal/keyContext)`.
+     *
+     * Legacy 2-arg form `(messages, opts?)` also accepted — the adapter
+     * detects arity and dispatches. Prefer the object form for new code.
+     */
+    keyFn?: ((ctx: ReplayCacheKeyContext) => string | Promise<string>) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | Promise<string>);
+    /** Prefix for cached keys (useful when sharing a tier across domains). */
+    keyPrefix?: string;
+    /**
+     * Whether to cache streaming responses (by consuming the full stream
+     * and replaying it as one synthetic token chunk). Default `false`.
+     */
+    cacheStreaming?: boolean;
+    /**
+     * When `cacheStreaming: true`, also record per-chunk delays (ms since
+     * previous chunk) so replay can honor the original streaming cadence.
+     * Default `false` (chunks replay instantly).
+     */
+    captureStreamCadence?: boolean;
+    /**
+     * Stream replay speed multiplier. `1` = original cadence (requires
+     * `captureStreamCadence`). `2` = 2× faster. `0` = instant. Default `1`.
+     */
+    replaySpeed?: number;
+}
+/** Wrap an adapter with a replay cache. */
+declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
+
+/**
+ * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
+ * deterministic tests, and graceful degradation in production.
+ *
+ * A peer of `anthropicAdapter` / `openAICompatAdapter` / `googleAdapter` /
+ * `ollamaAdapter` / `dryRunAdapter`, but whose role is to serve pre-recorded
+ * or canned responses when real providers aren't reachable. Install it as a
+ * tier via the existing routing primitives (no new composer needed):
+ *
+ * ```ts
+ * // Graceful offline fallback for a user app:
+ * resilientAdapter(anthropicAdapter({ ... }), {
+ *   fallback: fallbackAdapter({ fixturesDir: "./fixtures" }),
+ * });
+ *
+ * // Or the general N-tier shape:
+ * cascadingLlmAdapter([
+ *   { name: "primary",  adapter: anthropicAdapter({ ... }) },
+ *   { name: "fallback", adapter: fallbackAdapter({ fixturesDir: "./fixtures" }) },
+ * ]);
+ * ```
+ *
+ * The `provider` field is `"fallback"` so its role is self-documenting in
+ * logs, stats, cost tables, and audit trails.
+ *
+ * ## Three fixture sources (mutually exclusive)
+ *
+ * Pick exactly one of:
+ *
+ * 1. **`fixtures: FallbackFixture[]`** — inline, hand-authored. Supports
+ *    both hash-keyed and messages-keyed shapes; the adapter computes the
+ *    canonical hash for messages-keyed entries at init time. Ideal when you
+ *    want full control in code (tests, small demos).
+ *
+ * 2. **`fixturesStorage: KvStorageTier`** — the escape hatch for any backend.
+ *    Pass a `memoryKv()`, `indexedDbKv(...)`, `sqliteKv(...)`,
+ *    `cascadingCache(...)`, or a custom tier. You own the layout — no
+ *    auto-namespacing.
+ *
+ *    **Filesystem directories (Node only):** the core `fallbackAdapter`
+ *    does NOT import `node:fs` / `node:path` — it's safe to bundle for
+ *    browsers. For a directory convenience, import `fallbackAdapter` from
+ *    `@graphrefly/graphrefly/patterns/ai/node` (node subpath);
+ *    that variant adds `fixturesDir: string` (auto-namespaced to
+ *    `join(dir, keyPrefix)`, cache-format validated at init).
+ *
+ * ## Record mode
+ *
+ * `record: { adapter: real, storage }` proxies every call to `real` AND
+ * persists the response through the provided tier. Use the node subpath's
+ * `fallbackAdapter` for `record.dir` (auto-namespaced + `record.dir` defaults
+ * to `fixturesDir` when both are file-backed).
+ *
+ * ## Three use cases, one implementation
+ *
+ * | Use case | Config |
+ * |---|---|
+ * | **User apps** — degrade when the cloud provider errors or network is down | `fallbackAdapter({ fixturesStorage: ... })` installed as a fallback tier |
+ * | **Tests** — deterministic replays, fail loudly on miss | `fallbackAdapter({ fixturesStorage: ..., onMiss: "throw" })` |
+ * | **Eval offline replay** — zero-spend repeat runs | `fallbackAdapter({ fixturesStorage: ... })` as the only adapter |
+ *
+ * ## Implementation
+ *
+ * Thin sugar over {@link withReplayCache}. Key shape comes from its
+ * `canonicalJson` — fixtures written by either tool are interchangeable.
+ *
+ * @module
+ */
+
+type FallbackMissPolicy = "throw" | "respond";
+/**
+ * Thrown when `fallbackAdapter({ onMiss: "throw" })` receives a request that
+ * has no matching fixture. Alias of `ReplayCacheMissError` for now — the
+ * adapter is a thin sugar over `withReplayCache` and shares its miss-error.
+ */
+declare const FallbackMissError: typeof ReplayCacheMissError;
+type FallbackMissError = ReplayCacheMissError;
+/**
+ * One recorded fixture. Two authoring shapes:
+ * - **Hash-keyed** — `{ key, response, stream? }`. Key is `sha256(canonicalJson({messages, opts}))`
+ *   with `fallback:` prefix. This is what `record` mode writes.
+ * - **Messages-keyed** — `{ messages, invokeOpts?, response }`. The adapter
+ *   computes the key at init time. Ergonomic for hand-authored fixtures.
+ */
+type FallbackFixture = {
+    readonly key: string;
+    readonly response: LLMResponse;
+    readonly stream?: {
+        readonly chunks: readonly StreamDelta[];
+        readonly delaysMs?: readonly number[];
+    };
+} | {
+    readonly messages: readonly ChatMessage[];
+    readonly invokeOpts?: Omit<LLMInvokeOptions, "signal">;
+    readonly response: LLMResponse;
+};
+interface FallbackAdapterOptions {
+    /** Adapter provider label. Default `"fallback"`. */
+    readonly provider?: string;
+    /** Adapter model label. Default `"fallback"`. */
+    readonly model?: string;
+    /**
+     * Inline hand-authored fixtures. Supports both hash-keyed (`{key, response, stream?}`)
+     * and messages-keyed (`{messages, invokeOpts?, response}`) shapes — the adapter
+     * computes the canonical hash for messages-keyed entries at init time. Held in
+     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
+     * `fixturesStorage`.
+     */
+    readonly fixtures?: readonly FallbackFixture[];
+    /**
+     * Bring-your-own `KvStorageTier` (`memoryKv`, `sqliteKv`,
+     * `indexedDbKv`, `cascadingCache`, or a custom tier). You own the
+     * layout — no auto-namespacing. Mutually exclusive with `fixtures`.
+     *
+     * For filesystem directories, use the node subpath's `fallbackAdapter`
+     * with its `fixturesDir` option (auto-namespaced + validated).
+     */
+    readonly fixturesStorage?: KvStorageTier;
+    /**
+     * Called on fixture miss when `onMiss === "respond"`. If not provided and
+     * `onMiss === "respond"`, a canned "service unavailable" response is
+     * returned (marked with `metadata.degraded: true`).
+     */
+    readonly respond?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | LLMResponse;
+    /** Miss policy. Default `"respond"`. */
+    readonly onMiss?: FallbackMissPolicy;
+    /**
+     * Record mode. Proxies every call to `record.adapter` AND persists the
+     * result through `record.storage`. For filesystem `record.dir` convenience,
+     * use the node subpath's `fallbackAdapter`.
+     */
+    readonly record?: {
+        readonly adapter: LLMAdapter;
+        readonly storage?: KvStorageTier;
+    };
+    /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
+    readonly replaySpeed?: number;
+    /** Key prefix. Kept compatible with `withReplayCache` defaults. Default `"fallback"`. */
+    readonly keyPrefix?: string;
+    /**
+     * Custom key function — forwarded directly to the underlying
+     * {@link withReplayCache}. Use to shard fixtures by `invokeOpts.keyContext`
+     * (tenant, session, feature flag). Accepts either the new
+     * {@link ReplayCacheKeyContext} object form or the legacy 2-arg
+     * `(messages, opts?)` form.
+     */
+    readonly keyFn?: ((ctx: ReplayCacheKeyContext) => string) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string);
+}
+/**
+ * Build a fixture-backed {@link LLMAdapter}. See module docs for use cases
+ * (offline demo, tests, degraded-mode) and recipe snippets.
+ */
+declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
+
+export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, fallbackAdapter as f, withReplayCache as w };