@latimer-woods-tech/llm 0.2.0 → 0.4.1

package/CHANGELOG.md

@@ -1,16 +1,164 @@
-## [Unreleased]
+# Changelog
 
-## [0.2.0] - 2026-04-29
+## 0.4.1 — 2026-06-03
+
+### Added (no breaking changes)
+
+- Export `MODEL_PRICE_PER_1M` — the canonical USD-per-1M-tokens rate table. This
+  makes it the single source of truth for pricing across the platform;
+  `@latimer-woods-tech/llm-meter` now derives its cents table from it and enforces
+  parity with a drift-guard test. Make all rate changes here.
+
+---
+
+## 0.3.4 — 2026-05-28
+
+### Added (no breaking changes)
+
+- **`workbench` tier** routes to `deepseek-chat` with Groq fallback for boring,
+  reviewable, non-sensitive internal batch work.
+- **`DEEPSEEK_API_KEY`** added as an optional `LLMEnv` binding. It is required only
+  for `tier: 'workbench'` or explicit `deepseek-*` model overrides.
+- **DeepSeek pricing entries** for `deepseek-chat` and `deepseek-reasoner` so cost
+  caps and ledger rows use known rates instead of the conservative Opus fallback.
+
+### Guardrail
+
+- `workbench` is for docs summaries, changelog drafts, issue triage, and classification.
+  Do not route secrets, customer PII, billing data, production ops, or final
+  customer-facing answers through DeepSeek.
+
+---
+
+## 0.3.3 — 2026-05-27
+
+### Changed (no breaking changes)
+
+- **`fast` tier now routes to Grok 4.3 (primary) → Anthropic Haiku (fallback).**
+  When `GROK_API_KEY` is present in `LLMEnv`, the `fast` tier sends completions to
+  `grok-4.3` first and falls back to `claude-haiku-4-20250514` if Grok is unavailable
+  or returns an error. When `GROK_API_KEY` is absent, the request goes directly to
+  Anthropic Haiku (same behaviour as before). Callers that already set `tier: 'fast'`
+  pick up Grok routing automatically; no code change needed.
 
 ### Added
-- Multi-provider LLM completion chain with Anthropic primary, Grok fallback, and Groq tertiary fallback.
-- Streaming support through the Anthropic-compatible provider path.
-- `withSystem()` helper for consistently applying system prompts at call sites.
-- Quality-gated package build with lint, typecheck, coverage, and ESM output.
 
-### Fixed
-- Restored `@latimer-woods-tech/errors` and `@latimer-woods-tech/logger` as runtime dependencies so published consumers resolve package imports correctly.
+- **`LLMOptions.reasoningEffort`** — `'none' | 'low' | 'medium' | 'high'`
+  (optional, defaults to `'none'`). Forwarded to the Grok `reasoning_effort` parameter
+  for `grok-4.3`; ignored for all other providers.
+- **`MODELS.grok.fast`** updated from `'grok-4-fast'` to `'grok-4.3'`. Old alias
+  `'grok-4-fast'` retained as deprecated with updated pricing so historical ledger
+  rows remain accurate.
+- **Grok pricing update**: `grok-4.3` at $1.25/$2.50 per MTok (in/out).
+  Old `grok-4-fast` and `grok-3-mini-latest` re-priced to the same $1.25/$2.50 rate.
+- **`for (const [legIndex, leg] of routeLegs.entries())`** — renamed loop variable so
+  `legIndex` is accessible for the last-leg 429 rate-limit short-circuit.
+
+### Consumers
+
+- To opt-in to Grok 4.3: add `GROK_API_KEY` to your `LLMEnv` binding. No other code
+  change required for `tier: 'fast'` callers.
+- `GROK_API_KEY` is optional. If absent, fast-tier routing is identical to 0.3.2
+  (Anthropic Haiku only).
+
+---
+
+## 0.3.2 — 2026-05-27
+
+### Added (no breaking changes)
+
+- **`LLMOptions.workload`** — optional string label (`'insights'`, `'copy'`, `'lead-qualification'`, …)
+  forwarded to cost-recording calls for per-workload cost attribution in dashboards.
+- **Missing model pricing entries** in `MODEL_PRICE_PER_1M`:
+  `claude-haiku-4-5-20251001`, `claude-sonnet-4-20250514`, `claude-opus-4-20250514`
+  (aliases for variants that share pricing with their shorthand names; prevents
+  `estimateCostUsd` from silently returning `$0` for these model IDs).
+- **`workload` forwarded** to `recordOrgCostUsage` so per-workload breakdowns appear
+  in the cost-tracking KV store.
+
+### Consumers
+
+- Existing callers do not need to set `workload`; it is optional and defaults to `undefined`.
+- The `recordOrgCostUsage` signature is unchanged; `workload` is an additive internal field.
+
+---
+
+## 0.3.1 — 2026-05-02 PM
+
+### Added (no breaking changes)
+
+- **Grok opt-in provider.** `LLMProvider` now includes `'grok'`. Call with `{ model: 'grok-4-fast' }` or `{ model: 'grok-3-mini-latest' }` to route to xAI. Not in default tier routing — explicit model override only.
+- `LLMEnv.GROK_API_KEY` is **optional**; required only when a caller opts in via a `grok-*` model override.
+- `MODELS.grok.{fast, mini}` added to the catalogue.
+
+### Rationale
+
+Reversal of the 0.3.0 partial decision (D1 in `docs/supervisor/DECISIONS.md`): Grok stays available for workloads that benefit from its quirks — cheap experimental prompting in the xico-city user economy, artist-platform surface, etc. It does not compete with Anthropic / Gemini / Groq for the tier slots; it sits alongside as a per-call opt-in.
+
+### Consumers
+
+- Downstream packages do not need to declare `GROK_API_KEY` unless a route explicitly sends Grok model overrides. Existing code that dropped the key on 0.3.0 migration continues to work.
+
+
+## 0.3.0 — 2026-05-02
+
+### Breaking
+
+- **Grok removed.** `LLMProvider` no longer includes `grok`; `LLMEnv.GROK_API_KEY` removed.
+- **AI Gateway mandatory.** `LLMEnv.AI_GATEWAY_BASE_URL` is required. All provider traffic flows through
+  Cloudflare AI Gateway for unified logging, rate limiting, and cost telemetry.
+- **Tier-based routing.** `LLMOptions.tier` (`fast | balanced | smart | verifier`) replaces the
+  flat Anthropic → Grok → Groq failover chain. Routing is workload-split:
+  - `fast` → Anthropic Haiku (latency-sensitive, short completions)
+  - `balanced` → Anthropic Sonnet (default)
+  - `smart` → Anthropic Opus; Gemini 2.5 Pro for long-context (>150k tokens est.)
+  - `verifier` → Groq Llama 3.3 70B (cheap second opinion, no fallback)
+- **Dependency declarations fixed.** `@latimer-woods-tech/errors` and `@latimer-woods-tech/logger`
+  now declared as `^0.2.0` instead of `file:../*` so external consumers can install the package.
+
+### Added
+
+- Gemini 2.5 Pro via Vertex AI as long-context fallback (`VERTEX_ACCESS_TOKEN`, `VERTEX_PROJECT`, `VERTEX_LOCATION`).
+- Anthropic prompt caching (auto-enabled for system prompts ≥ 4096 chars; override via `LLMOptions.promptCache`).
+- Per-call cancellation via `LLMOptions.signal: AbortSignal`.
+- 3-attempt exponential backoff (250ms · 2^n + jitter) on retryable status (408, 425, 429, 5xx).
+- Ledger stamping: `LLMOptions.{runId, project, actor}` propagated to logger for downstream
+  consumption by `@latimer-woods-tech/llm-meter`.
+- `LLMResult.{model, tier, attempts, gatewayRequestId, tokens.cacheRead, tokens.cacheWrite}` for
+  observability and budget accounting.
+
+### Changed
+
+- Default model constants renamed and grouped under exported `MODELS` catalogue. Kept in sync with
+  `docs/architecture/FACTORY_V1.md § LLM substrate`.
+- Empty provider responses now surface as leg failures and trigger fallback rather than returning
+  an empty `LLMResult`.
+
+### Migration
+
+Replace:
+
+```ts
+const res = await complete(msgs, { ANTHROPIC_API_KEY, GROK_API_KEY, GROQ_API_KEY }, { model: 'claude-sonnet-4-...' });
+```
+
+With:
+
+```ts
+const res = await complete(
+  msgs,
+  {
+    AI_GATEWAY_BASE_URL: env.AI_GATEWAY_BASE_URL,
+    ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+    GROQ_API_KEY: env.GROQ_API_KEY,
+    VERTEX_ACCESS_TOKEN: env.VERTEX_ACCESS_TOKEN, // minted via JWT-bearer flow
+    VERTEX_PROJECT: env.VERTEX_PROJECT,
+    VERTEX_LOCATION: env.VERTEX_LOCATION,
+  },
+  { tier: 'balanced', runId, project: 'prime-self', actor: 'worker' },
+);
+```
+
+## 0.2.0
 
-### Verification
-- `npm install` regenerated the package lock and ran the package prepublish gate on Apr 29, 2026.
-- `npm run lint`, `npm run typecheck`, `npm test -- --coverage`, and `npm run build` passed during the prepublish gate.
+Initial public release of the failover orchestrator.

package/README.md

@@ -1,3 +1,67 @@
-# @factory/llm
+# @latimer-woods-tech/llm
 
-LLM failover orchestration across Factory AI providers.
+Tier-routed LLM orchestration for the Factory platform, with Cloudflare AI Gateway, Anthropic
+primary, Gemini 2.5 Pro long-context fallback, Groq verifier, and DeepSeek workbench routing.
+
+## Routing (0.3.0)
+
+| Tier | Primary | Fallback | Notes |
+|---|---|---|---|
+| `fast` | Claude Haiku 4 | — | latency-sensitive, short completions |
+| `balanced` *(default)* | Claude Sonnet 4 | Gemini 2.5 Pro | swaps to Gemini when est. tokens ≥ 150k |
+| `smart` | Claude Opus 4 | Gemini 2.5 Pro | ditto; tools, long reasoning |
+| `verifier` | Groq Llama 3.3 70B | — | cheap second opinion; no fallback |
+| `workbench` | DeepSeek Chat | Groq Llama | boring, reviewable, non-sensitive batch work |
+
+All traffic flows through `AI_GATEWAY_BASE_URL`. The gateway handles caching, rate-limit shedding,
+and per-project cost telemetry.
+
+## Usage
+
+```ts
+import { complete } from '@latimer-woods-tech/llm';
+
+const ctl = new AbortController();
+setTimeout(() => ctl.abort(), 30_000);
+
+const res = await complete(
+  [{ role: 'user', content: 'Draft a release note for llm@0.3.0.' }],
+  {
+    AI_GATEWAY_BASE_URL: env.AI_GATEWAY_BASE_URL,
+    ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+    GROQ_API_KEY: env.GROQ_API_KEY,
+    DEEPSEEK_API_KEY: env.DEEPSEEK_API_KEY,
+    VERTEX_ACCESS_TOKEN: env.VERTEX_ACCESS_TOKEN,
+    VERTEX_PROJECT: env.VERTEX_PROJECT,
+    VERTEX_LOCATION: env.VERTEX_LOCATION,
+  },
+  {
+    tier: 'balanced',
+    signal: ctl.signal,
+    runId: 'sup-run-0042',
+    project: 'prime-self',
+    actor: 'supervisor',
+  },
+);
+
+if (res.ok) {
+  console.log(res.data.content, res.data.provider, res.data.tokens);
+}
+```
+
+Use `tier: 'workbench'` only for low-risk internal jobs: docs summaries, changelog drafts,
+classification, issue triage, and other outputs a human or higher-trust model can review. Do not
+send secrets, customer PII, production ops requests, billing data, or final customer-facing answers
+through this lane.
+
+## Vertex access token
+
+Minted via the JWT-bearer flow from a GCP service account. See
+`docs/runbooks/rotate-gcp-sa.md` for the mint procedure. Tokens are short-lived (1h); callers
+should refresh before every cold start or every 50 minutes, whichever comes first.
+
+## Budget
+
+Every call emits a `llm.complete` log line with `{ provider, model, tier, tokens, runId, project,
+actor }`. `@latimer-woods-tech/llm-meter` (0.1.0+) consumes these lines to enforce the per-run
+$5 hard cap and the per-project steady-state budget.

package/dist/index.d.mts

@@ -8,38 +8,165 @@ interface LLMMessage {
     role: 'user' | 'assistant' | 'system';
     content: string;
 }
+/**
+ * Quality tier selected by the caller. Routing is workload-split:
+ *  - `fast`      → Grok 4.3 with Anthropic Haiku fallback (routine drafts/small jobs)
+ *  - `balanced`  → Anthropic Sonnet (default)
+ *  - `smart`     → Anthropic Opus OR Gemini 2.5 Pro if input is long-context (>150k tokens estimated)
+ *  - `verifier`  → Groq Llama (cheap second opinion; only used from verifier code path)
+ *  - `workbench` → DeepSeek Chat with Groq fallback (boring, reviewable, non-sensitive batch work)
+ */
+type LLMTier = 'fast' | 'balanced' | 'smart' | 'verifier' | 'workbench';
 /**
  * Options that influence LLM completion behaviour.
  */
 interface LLMOptions {
+    /** Quality tier; see {@link LLMTier}. Defaults to `balanced`. */
+    tier?: LLMTier;
+    /** Explicit model override. Takes precedence over tier. */
     model?: string;
     maxTokens?: number;
     temperature?: number;
     system?: string;
+    /** Token budget above which we force long-context routing (Gemini). */
+    longContextThreshold?: number;
+    /** Per-call cancellation signal. Aborts the in-flight provider request. */
+    signal?: AbortSignal;
+    /** Optional run identifier stamped on ledger rows + logs. */
+    runId?: string;
+    /** Optional project identifier stamped on ledger rows + logs. */
+    project?: string;
+    /** Optional actor identifier (supervisor / worker / human). */
+    actor?: string;
+    /** Optional workload label used in logs and cost-policy call sites. */
+    workload?: string;
+    /** Grok reasoning effort. Defaults to `none` for cost-controlled fast/draft calls. */
+    reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
+    /** Anthropic prompt-cache control. Defaults to `true` for `system` prompts ≥ 1024 tokens. */
+    promptCache?: boolean;
+    /**
+     * Maximum estimated cost in USD for this completion.
+     * This cap is enforced after the provider returns because it uses actual
+     * response token counts to compute the final cost.
+     * If the post-call estimated cost exceeds this cap, `complete` returns a
+     * {@link RateLimitError} with code `LLM_COST_CAP_EXCEEDED` and
+     * `completionStream` throws the same error.
+     * Pricing is based on {@link MODEL_PRICE_PER_1M}; unknown models default to
+     * Opus rates (conservative upper bound).
+     */
+    maxCostUsd?: number;
+    /**
+     * Org-level daily cost cap in USD. Requires `env.LLM_COST_KV` to be set.
+     * When today's cumulative spend read from KV is >= this value, `complete`
+     * returns a {@link RateLimitError} with code `LLM_DAILY_CAP_EXCEEDED`
+     * without making any provider call. After a successful call the daily
+     * accumulator is updated in KV (TTL: 48 h).
+     */
+    dailyCapUsd?: number;
+    /**
+     * Org-level monthly cost cap in USD. Requires `env.LLM_COST_KV` to be set.
+     * Same enforcement pattern as {@link dailyCapUsd} but keyed by YYYY-MM.
+     * KV TTL: 40 days.
+     */
+    monthlyCapUsd?: number;
+    /**
+     * Metering context. When supplied and `deps.onRecord` is set, a {@link LLMRecordRow}
+     * is emitted after every successful completion. Errors are swallowed.
+     */
+    ledger?: LLMRecordContext;
 }
 /**
  * Provider that produced an LLM response.
  */
-type LLMProvider = 'anthropic' | 'grok' | 'groq';
+type LLMProvider = 'anthropic' | 'gemini' | 'groq' | 'grok' | 'deepseek';
 /**
  * Result returned by a successful completion.
  */
 interface LLMResult {
     content: string;
     provider: LLMProvider;
+    model: string;
+    tier: LLMTier;
     tokens: {
         input: number;
         output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
     latency: number;
+    /** Number of attempts before success (1 = primary succeeded). */
+    attempts: number;
+    /** Monotonic request id from AI Gateway, if present in headers. */
+    gatewayRequestId?: string;
 }
 /**
  * Environment bindings required by {@link complete}.
+ *
+ * `AI_GATEWAY_BASE_URL` is REQUIRED in 0.3.0. All provider calls flow through the
+ * Cloudflare AI Gateway for unified logging, rate limiting, and cost telemetry.
+ * In test/dev the caller may pass a custom fetch impl that short-circuits this.
  */
 interface LLMEnv {
+    AI_GATEWAY_BASE_URL: string;
     ANTHROPIC_API_KEY: string;
-    GROK_API_KEY: string;
     GROQ_API_KEY: string;
+    /** Optional — only required for `{ tier: 'workbench' }` or `deepseek-*` model overrides. */
+    DEEPSEEK_API_KEY?: string;
+    /** Optional — only required when caller passes `{ model: 'grok-*' }` override. */
+    GROK_API_KEY?: string;
+    /**
+     * Google Cloud short-lived access token with `aiplatform.endpoints.predict`.
+     * Callers mint this via the JWT-bearer flow (service account → token exchange);
+     * see `docs/runbooks/rotate-gcp-sa.md`. Token must be valid for ≥ 5 minutes.
+     */
+    VERTEX_ACCESS_TOKEN: string;
+    VERTEX_PROJECT: string;
+    VERTEX_LOCATION: string;
+    /**
+     * Optional KV store for org-level daily/monthly cost tracking and enforcement.
+     * When provided alongside {@link LLMOptions.dailyCapUsd} or {@link LLMOptions.monthlyCapUsd},
+     * `complete` will block calls that would exceed the declared cap.
+     * Any KV-like store satisfying `get`/`put` works (e.g. Cloudflare KV, in-memory stub).
+     */
+    LLM_COST_KV?: CostKvStore;
+}
+/**
+ * Minimal KV store interface for org-level LLM cost tracking.
+ * Cloudflare KV satisfies this. An in-memory stub is sufficient for tests.
+ */
+interface CostKvStore {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+/**
+ * Caller-supplied context stamped on every metering row.
+ * Mirrors the `LLMRecordContext` in `@latimer-woods-tech/llm-meter`; kept inline
+ * to avoid a circular dependency (llm-meter imports llm).
+ */
+interface LLMRecordContext {
+    project: string;
+    actor: string;
+    runId?: string;
+    workload?: string;
+    tenantId?: string;
+}
+/**
+ * Row shape passed to the optional {@link LLMDeps.onRecord} callback.
+ * Callers can wire this directly to `recordCall` from `@latimer-woods-tech/llm-meter`.
+ */
+interface LLMRecordRow extends LLMRecordContext {
+    model: string;
+    provider: LLMProvider;
+    tier: LLMTier;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    latencyMs: number;
+    costUsd: number;
+    yyyyMm: string;
 }
 /**
  * Optional dependencies for {@link complete}.
@@ -48,40 +175,138 @@ interface LLMDeps {
     fetch?: typeof fetch;
     logger?: Logger;
     now?: () => number;
+    /**
+     * Optional metering callback. Called after every successful completion.
+     * Errors are swallowed so metering never blocks the caller.
+     * Wire to `recordCall` from `@latimer-woods-tech/llm-meter`.
+     */
+    onRecord?: (row: LLMRecordRow) => Promise<void>;
 }
+declare const MODELS: {
+    readonly anthropic: {
+        readonly fast: "claude-haiku-4-20250514";
+        readonly balanced: "claude-sonnet-4-6";
+        readonly smart: "claude-opus-4-7";
+    };
+    readonly gemini: {
+        readonly smart: "gemini-2.5-pro";
+    };
+    readonly groq: {
+        readonly verifier: "llama-4-maverick";
+    };
+    readonly grok: {
+        readonly fast: "grok-4.3";
+    };
+    readonly deepseek: {
+        readonly workbench: "deepseek-chat";
+    };
+};
+/** Cooldown duration in ms after a provider exhausts all retries. */
+declare const PROVIDER_COOLDOWN_MS = 30000;
 /**
- * Runs a completion through the Anthropic → Grok → Groq failover chain.
+ * Returns `true` if the provider is currently in its cooldown window.
+ * Uses the injected `now` function (or `Date.now`) for testability.
+ */
+declare function isProviderCoolingDown(provider: LLMProvider, now?: () => number): boolean;
+/**
+ * USD cost per 1 million tokens for each model.
+ * Source: Anthropic / Google / xAI pricing pages as of 2026-05.
+ * Keep these model names in sync with the default routing constants in
+ * {@link MODELS}; unknown models fall back to Opus rates (conservative upper bound).
+ *
+ * CANONICAL pricing source for the platform. `@latimer-woods-tech/llm-meter`
+ * derives its cents-denominated rates from this table and a drift-guard test
+ * there fails CI if they diverge — make all rate changes here.
+ */
+declare const MODEL_PRICE_PER_1M: Record<string, {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}>;
+/**
+ * Marks a provider as cooling down for {@link PROVIDER_COOLDOWN_MS} milliseconds.
+ */
+declare function markProviderCoolingDown(provider: LLMProvider, now?: () => number): void;
+/**
+ * Clears the cooldown state for a provider after a successful call.
+ */
+declare function clearProviderCooldown(provider: LLMProvider): void;
+declare const BASE_BACKOFF_MS = 250;
+/**
+ * Run a completion through the routing plan for the requested tier.
+ *
+ * Routing summary (0.3.0):
+ *   - `fast`     → Grok 4.3; Anthropic Haiku fallback when Grok is unavailable
+ *   - `balanced` → Anthropic Sonnet; Gemini 2.5 Pro if `longContextThreshold` exceeded
+ *   - `smart`    → Anthropic Opus; Gemini 2.5 Pro if long-context
+ *   - `verifier` → Groq Llama 3.3 70B (no fallback — verifier is inherently cheap/best-effort)
+ *   - `workbench` → DeepSeek Chat; Groq fallback for boring/reviewable internal batch jobs
+ *
+ * All provider traffic flows through Cloudflare AI Gateway at `AI_GATEWAY_BASE_URL`.
+ *
+ * Per-provider reliability guarantees (0.4.0):
+ *   - Exponential backoff with jitter on 429 / 5xx (base 500ms, cap 8s, up to 2 retries).
+ *   - Provider cooldown: after exhausting retries the provider is marked cooling down
+ *     for 30 seconds; subsequent calls skip it and go straight to the fallback leg.
  *
  * @param messages - Ordered chat history.
- * @param env - API key bindings.
- * @param opts - Optional model/parameters override.
+ * @param env - API key + gateway bindings.
+ * @param opts - Optional tier/model/parameters override.
  * @param deps - Optional fetch/logger/clock injection (for testing).
  * @returns A {@link FactoryResponse} carrying either an {@link LLMResult} or
- *   an `LLM_ALL_PROVIDERS_FAILED` error.
+ *   an error (`LLM_ALL_PROVIDERS_FAILED`, `LLM_RATE_LIMITED`, or `INTERNAL_ERROR`).
  */
 declare function complete(messages: LLMMessage[], env: LLMEnv, opts?: LLMOptions, deps?: LLMDeps): Promise<FactoryResponse<LLMResult>>;
 /**
- * Streams a completion from Anthropic. No failover is performed for streaming
- * responses; callers should fall back to {@link complete} on failure.
+ * Streams a completion from the primary Anthropic provider, yielding text chunks
+ * as they arrive. Falls back to the non-streaming {@link complete} function when
+ * the provider does not support streaming (i.e. a non-Anthropic primary is selected).
+ *
+ * The generator's **return value** (accessible via `gen.return()` or by consuming
+ * the full iteration) is an {@link LLMResult} with the same shape as {@link complete}.
+ *
+ * Usage pattern:
+ * ```ts
+ * const gen = completionStream(messages, env, opts);
+ * for await (const chunk of gen) {
+ *   // stream chunk to client
+ * }
+ * const result = (await gen.return(undefined)).value; // LLMResult
+ * ```
  *
  * @param messages - Ordered chat history.
- * @param env - Anthropic API key binding.
- * @param opts - Optional model/parameters override.
- * @param deps - Optional fetch override (for testing).
- * @returns The raw Anthropic streaming response body.
+ * @param env - API key + gateway bindings.
+ * @param opts - Optional tier/model/parameters override. Accepts `deps` as nested field.
+ * @returns An async generator that yields `string` chunks and returns an {@link LLMResult}.
  */
-declare function stream(messages: LLMMessage[], env: {
-    ANTHROPIC_API_KEY: string;
-}, opts?: LLMOptions, deps?: {
-    fetch?: typeof fetch;
-}): Promise<ReadableStream<Uint8Array>>;
+declare function completionStream(messages: LLMMessage[], env: LLMEnv, opts?: LLMOptions & {
+    deps?: LLMDeps;
+}): AsyncGenerator<string, LLMResult, unknown>;
 /**
- * Returns a {@link complete}-compatible function with a system prompt
- * pre-bound, so callers can hand around a domain-specific shortcut.
+ * Returns `true` if `response` contains at least one verbatim phrase of at
+ * least 5 consecutive whitespace-delimited tokens that also appears in one of
+ * the `sources` strings.
+ *
+ * Returns `true` unconditionally when `sources` is empty (no grounding
+ * documents means grounding cannot be violated).
+ *
+ * This is a lightweight guard for RAG pipelines — it detects obvious
+ * hallucinations where the model generates content not present in any
+ * retrieved source. It is NOT a semantic similarity check.
+ *
+ * @param response - The LLM-generated text to inspect.
+ * @param sources - Retrieved source documents to check against.
+ * @returns `true` if the response is grounded, `false` if hallucination detected.
  *
- * @param system - System prompt to prepend to every call.
- * @returns A function that invokes {@link complete} with `system` injected.
+ * @example
+ * ```ts
+ * const grounded = assertGrounding(llmAnswer, retrievedDocs);
+ * if (!grounded) {
+ *   // flag or re-rank the response
+ * }
+ * ```
  */
-declare function withSystem(system: string): (messages: LLMMessage[], env: LLMEnv, opts?: LLMOptions, deps?: LLMDeps) => Promise<FactoryResponse<LLMResult>>;
+declare function assertGrounding(response: string, sources: string[]): boolean;
 
-export { type LLMDeps, type LLMEnv, type LLMMessage, type LLMOptions, type LLMProvider, type LLMResult, complete, stream, withSystem };
+export { BASE_BACKOFF_MS, type CostKvStore, type LLMDeps, type LLMEnv, type LLMMessage, type LLMOptions, type LLMProvider, type LLMRecordContext, type LLMRecordRow, type LLMResult, type LLMTier, MODELS, MODEL_PRICE_PER_1M, PROVIDER_COOLDOWN_MS, assertGrounding, clearProviderCooldown, complete, completionStream, isProviderCoolingDown, markProviderCoolingDown };