@broberg/ai-sdk 0.55.3 → 0.56.1

package/dist/registry-U66vzTm0.d.ts

@@ -0,0 +1,874 @@
+type FailureKind = "auth" | "not_found" | "rate_limit" | "server" | "timeout" | "network" | "other";
+interface CallFailure {
+    provider: string;
+    /** The model we ASKED for (the route that failed). */
+    model: string;
+    transport: string;
+    capability: Capability;
+    tier?: Tier;
+    purpose?: string;
+    labels?: Record<string, string>;
+    latencyMs: number;
+    ts: string;
+    /** HTTP status as a string ("401", "503"), or "timeout" | "network" | "unknown". */
+    errorCode: string;
+    errorKind: FailureKind;
+}
+
+/** Coarse data-residency of the endpoint a call went to.
+ *
+ *  - `"eu"`  — EU/EEA. **The only positive residency claim.** Nothing else is folded
+ *              in: an adequacy decision is not EU residency, so the UK, Switzerland
+ *              and Canada are deliberately NOT `"eu"` here.
+ *  - `"us"`  — United States.
+ *  - `"cn"`  — China.
+ *  - `"unknown"` — we genuinely cannot say: an aggregator that picks its own upstream,
+ *              or a region string we do not recognise.
+ *
+ *  **`"unknown"` is NOT a synonym for safe.** `region !== "us"` is not an EU check —
+ *  it passes every OpenRouter call. Only `region === "eu"` may be treated as EU-resident.
+ */
+type Region = "eu" | "us" | "cn" | "unknown";
+/** Region of the endpoint a call will actually hit. Never throws — a residency
+ *  reading must not be able to break a call that already succeeded. */
+declare function regionOfHost(hostOrUrl: string | undefined): Region;
+/** Classify a provider REGION STRING — a Vertex/GCP location like `europe-west1`, or
+ *  an Azure region like `westeurope`. Anything unrecognised is `"unknown"`: a region
+ *  name we have never seen is exactly the case where guessing is most tempting and
+ *  least defensible. Never throws — a residency reading must not be able to break a
+ *  call that already succeeded. */
+declare function classifyRegionName(name: string | undefined): Region;
+/** Region for an adapter whose endpoint is fixed. Unknown provider → `"unknown"`.
+ *
+ *  **DO NOT BUILD A RESIDENCY GUARD ON THIS.** Use {@link regionOfHost} on the base URL
+ *  the call will actually use. Found by a consumer building exactly that guard (super,
+ *  2026-08-30): `regionOfProvider("mistral")` is `"unknown"` — correct, because Mistral
+ *  takes a `baseUrl` and a name cannot answer for residency — but a guard written as
+ *  `regionOfProvider(p) === "eu"` therefore REJECTS Mistral, which is the only EU route
+ *  we have. It fails closed and is useless: it filters out the thing it exists to allow.
+ *
+ *  The trap is invisible from the signature, which is why it is written here rather than
+ *  only in the docs. This function answers "is this provider's endpoint fixed, and where
+ *  is it?" — a narrower question than "where will my call go?". */
+declare function regionOfProvider(provider: string): Region;
+
+/** One dictionary entry. `alias` says it differently; `ipa` says it in phonemes.
+ *
+ *  **`ipa` is NOT the "more precise" option for a FOREIGN word — measured 2026-09-04.**
+ *  Christian listened to `workflow` as `ˈwɜːkfloʊ` through the da-DK voices jeppe and
+ *  christel and reported: *"ikke korrekt engelsk med et sjovt mix"*. A Danish neural
+ *  voice renders English phonemes through Danish phonology, so foreign IPA comes out a
+ *  hybrid rather than English. The symbols are honoured; the accent is not.
+ *
+ *  So pick by what the word IS, not by which field sounds more exact:
+ *  - a DANISH word the voice mispronounces → `ipa` does what you want.
+ *  - an ENGLISH word inside Danish text → neither field is right yet. `alias` (spell it
+ *    the way a Dane would say it) is the honest workaround today; a real engine switch
+ *    is F051.2, and it is blocked on a listening test, not on code.
+ *
+ *  Dated on purpose. This is a measurement of two specific voices on one date, not a
+ *  permanent property of IPA — Azure ships new voices, and the next reader deserves to
+ *  see that it may have moved. */
+interface Pronunciation {
+    /** The word as it appears in the text. Matched whole-word, case-insensitively. */
+    word: string;
+    /** Say this instead. Azure `<sub alias>`; ElevenLabs plain substitution. */
+    alias?: string;
+    /** Also match INSIDE a hyphenated compound — `AI` in `AI-agenter` (F051.3).
+     *
+     *  Danish puts abbreviations there constantly. cms measured their own articles:
+     *  "AI-agenter" 13 times, "AI-native" 12, 60+ occurrences in all, every one read aloud
+     *  as one mangled word. Christian heard it as "HTLM" and asked why AI was not spelled
+     *  out too — it WAS, just never in a compound.
+     *
+     *  **Per entry, and defaulting to `false`, because the right answer depends on the
+     *  word.** `AI` yes; `mail` no — a rule for `mail` must not fire inside `e-mail`.
+     *  Measured rather than reasoned: `@broberg/speech-dictionary` ships the general
+     *  loosening and pays exactly that price today. A single global answer is wrong for
+     *  one of the two classes whichever way it is set, so the person who wrote the entry
+     *  decides.
+     *
+     *  Default `false` is also the safe direction to be wrong in: flipping it would change
+     *  the audio for every existing consumer IN SOUND, where there is no compile error, no
+     *  red test and no log line to notice it by. */
+    matchInCompounds?: boolean;
+    /** IPA phonemes. Azure `<phoneme alphabet="ipa" ph>`. ElevenLabs cannot do this
+     *  (it THROWS rather than silently skipping). See the type doc above before reaching
+     *  for this on a foreign word. */
+    ipa?: string;
+    /** Reserved for a future per-entry language switch; carried but not yet emitted. */
+    lang?: string;
+}
+
+/** One entry of Azure's `[nnnn].word.json`, verbatim field names. */
+interface AzureWordBoundary {
+    Text: string;
+    /** Milliseconds into the audio. */
+    AudioOffset: number;
+    /** Milliseconds. */
+    Duration: number;
+}
+interface WordTiming {
+    /** The spoken word, as Azure reported it. */
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** Character span in the SOURCE text. Several spoken words share one span when they
+     *  came from one substituted manuscript word. */
+    sourceStart: number;
+    sourceEnd: number;
+}
+interface AlignedWordTimings {
+    /** Every word we could place in the source, in audio order. */
+    words: WordTiming[];
+    /** Spoken words we could NOT place, in order, verbatim.
+     *
+     *  Named rather than dropped, and never given a guessed offset. "I could not place
+     *  this" and "it was here" must not be the same answer — the same discipline as
+     *  `rerank.unscored` (F052). A highlighter that treats `words` as complete must look
+     *  here. */
+    unaligned: string[];
+}
+/** A pronunciation entry, narrowed to what alignment needs. */
+interface AliasEntry {
+    word: string;
+    alias?: string;
+}
+/**
+ * Map Azure's spoken word list onto positions in the SOURCE text.
+ *
+ * Two rules carry the whole function:
+ *
+ * **The walk only moves FORWARD.** That is what puts a repeated word on its own
+ * occurrence — "AI er AI" must not place the second on the first. Searching from 0 each
+ * time passes every test with distinct words and fails silently on real prose.
+ *
+ * **A substitution is matched as a RUN, not word by word.** Azure speaks SSML, so
+ * `<sub alias='broberg punktum a i'>broberg.ai</sub>` puts four words in the list where
+ * the manuscript has one. Matching them individually is not merely imprecise, it is
+ * wrong in a way that bites every Danish text: MEASURED on cms's own dictionary entry,
+ * a per-word map made the alias's "i" swallow the next real Danish word "i" in
+ * "broberg.ai i dag". An alias's parts are often ordinary words ("a", "i", "punktum"),
+ * so a lookup table cannot be the mechanism — the run has to be consumed positionally.
+ */
+declare function alignWordTimings(text: string, words: AzureWordBoundary[], opts?: {
+    pronunciations?: AliasEntry[];
+}): AlignedWordTimings;
+
+/** How a call reaches the model. `http` = provider REST API; `subprocess` = local
+ *  `claude -p` CLI (Max plan, costUsd 0). */
+type Transport = "http" | "subprocess";
+/** Named capability tier. Resolves to a (provider, model, transport) triple via
+ *  the tier map, overridable per call. */
+type Tier = "fast" | "smart" | "powerful" | "cheap" | "vision" | "video" | "embedding";
+/** The concrete routing target a Tier (or a per-call override) resolves to. */
+interface TierSpec {
+    provider: string;
+    model: string;
+    transport: Transport;
+}
+/** High-level capability a call exercises. Mirrors the capability layer (F5). */
+type Capability = "chat" | "vision" | "video" | "translate" | "image" | "animate" | "embedding" | "transcribe" | "ocr" | "moderation" | "podcast" | "tts" | "trainStyle" | "mockup" | "design" | "extract" | "classify" | "rerank" | "judge";
+type Role = "system" | "user" | "assistant" | "tool";
+/** A piece of message content. Text everywhere; image parts feed vision. */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    image: string | Uint8Array;
+    mimeType?: string;
+} | {
+    type: "video";
+    video: string | Uint8Array;
+    mimeType?: string;
+};
+interface Message {
+    role: Role;
+    content: string | ContentPart[];
+    /** Set on assistant messages that called tools. Accepts either spelling of the
+     *  arguments field — see ToolCallLike. */
+    toolCalls?: ToolCallLike[];
+    /** Set on `tool` role messages — which call this result answers. */
+    toolCallId?: string;
+    /** F049 — Mistral's `prefix`: start the model's reply with this text instead of
+     *  asking it to. Only valid on the LAST message, and only when that message is an
+     *  `assistant` one; anything else throws rather than being sent, because Mistral
+     *  documents no behaviour for it elsewhere.
+     *
+     *  Mistral's own first-listed use case is Language Adherence, and it pairs with a
+     *  system instruction rather than replacing one — they warn that a prefix alone
+     *  gives "noisy and unpredictable answers". Measured on this repo's own data: an
+     *  explicit language rule in the system prompt already took 5/15 wrong answers to
+     *  0/15, and every leak began in the FIRST words ("Tak for din henvendelse"), which
+     *  is exactly what a prefix pins.
+     *
+     *  **The SDK strips the prefix back off the response**, in `chat` and `chatStream`
+     *  alike, so a caller never has to. Mistral's own example does
+     *  `content[len(prefix):]` by hand; forgetting it puts "Here is the answer in
+     *  Norwegian:" at the top of a real customer's email — a defect that reads as
+     *  formatting rather than as a bug. */
+    prefix?: boolean;
+}
+/** SDK-level tool definition. Adapters convert this to each provider's format
+ *  (F4.5). `parameters` is a JSON Schema object. */
+interface Tool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** A model's request to invoke a tool, normalized across providers (F4.5).
+ *  This is what we EMIT — `arguments` is always present on a ToolCall we return. */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** What we ACCEPT when a tool call is handed BACK to us in a message history.
+ *
+ *  F043. `@broberg/chat` spells the same field `args`, consistently across its
+ *  ModelEvent / ChatFrame / ChatTool.run. Two packages describing the same thing
+ *  with two names cost cms a production outage: a rename living in a workaround was
+ *  deleted along with the workaround, and the next call failed with
+ *  `messages.1.toolCalls.0.arguments — Required`.
+ *
+ *  So we read both and keep emitting `arguments`. Accepting is cheap and cannot
+ *  break anyone; renaming would have broken a consumer who adopted the same day, and
+ *  asking every consumer that bridges the two packages to remember a translation is
+ *  how this happens again. Precedence is `arguments` when both are set. */
+type ToolCallLike = {
+    id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+    args?: Record<string, unknown>;
+};
+/** Per-call usage. Fields mirror the upmetrics `agent_runs` schema 1:1 so the
+ *  upmetricsSink (F3.7) forwards without re-mapping. `costUsd` is 0 for
+ *  subprocess (Max plan); `subprocess:true` lets dashboards split free vs paid. */
+interface Usage {
+    provider: string;
+    /** The model we ASKED for — the pricing key and the stable grouping. */
+    model: string;
+    /** F077.3 — true when `model` was a floating "-latest" alias the caller chose
+     *  without allowFloating: the provider can move it to another model and price. */
+    floating?: boolean;
+    /** F071.2 — the model that ANSWERED, as the provider reported it. Differs from `model`
+     *  when an alias like "mistral-large-latest" resolves to a dated model; that is how a
+     *  silent overnight move becomes visible. Unset when the provider does not say. */
+    servedModel?: string;
+    tier?: Tier;
+    /** Data-residency of the endpoint that ACTUALLY answered (F042). Derived from the
+     *  host/region the request used, not from the provider's name — vertex, azure and
+     *  bfl are EU by default but a consumer can point them elsewhere.
+     *
+     *  **Only `"eu"` is a positive residency claim.** `"unknown"` means we cannot say
+     *  (an aggregator picked its own upstream, or the region string is one we do not
+     *  recognise) — it is NOT a synonym for safe, so `region !== "us"` is not an EU check. */
+    region: Region;
+    transport: Transport;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    /** How `costUsd` was arrived at (F050). Absent means the same as `"computed"`;
+     *  it is optional only so that adding it could not break a consumer building a
+     *  Usage by hand.
+     *
+     *  - `"reported"` — the PROVIDER told us what the call cost (BFL returns credits).
+     *  - `"computed"` — a price table rate × a quantity we actually measured (tokens).
+     *  - `"estimated"` — a quantity or a rate was ASSUMED. A video call with no
+     *    `durationSec` is billed at {@link DEFAULT_CLIP_SEC} seconds regardless of the
+     *    clip that came back, and fal's per-image rates are fal's own estimates.
+     *  - `"unpriced"` — we have NO price for this model, so `costUsd` is 0 because we
+     *    could not answer, not because the call was free. Those two were the same
+     *    number, and the free one is much rarer than the unknown one.
+     *
+     *  This is a DATA field on purpose. upmetrics distinguishes reported / computed /
+     *  unpriced / untokened, and it reads fields — a JSDoc note saying "this one is a
+     *  guess" never reaches it, so an assumed number arrived there indistinguishable
+     *  from a measured one. super did exactly that and passed it on as measured. */
+    costBasis?: "reported" | "computed" | "estimated" | "unpriced";
+    toolCalls?: {
+        name: string;
+        count: number;
+        errorCount?: number;
+    }[];
+    latencyMs: number;
+    capability: Capability;
+    purpose?: string;
+    /** Consumer-defined attribution dimensions (e.g. {tenantId}) for per-tenant
+     *  cost breakdown — the sink forwards these (F011). */
+    labels?: Record<string, string>;
+    ts: string;
+    subprocess?: true;
+}
+/** A cost reporter. Fans `Usage` out to Upmetrics / Discord / sqlite / etc.
+ *  Implementations must never throw into the caller (F3.3). */
+interface CostSink {
+    record(usage: Usage): void | Promise<void>;
+    /** F071.1 — optional: a FAILED call attempt (no cost). Sinks that sum spend (sqlite,
+     *  budget, your own) may ignore it; leaving it out means they never see failures. */
+    recordFailure?(failure: CallFailure): void | Promise<void>;
+}
+/** Backing store for a BudgetGuard's rolling total. Default is in-memory
+ *  (per createAI instance). A persistent store (e.g. sqliteBudgetStore) makes
+ *  the rolling budget survive restarts + shared across processes (F7.1). */
+interface BudgetStore {
+    getSpent(): number | Promise<number>;
+    addSpent(usd: number): void | Promise<void>;
+}
+/** Pre-flight budget ceilings, enforced before a call fires (F3.2). */
+interface BudgetConfig {
+    /** Reject a single call whose estimated cost exceeds this many USD. */
+    perCallUsd?: number;
+    /** Reject once cumulative spend exceeds this many USD. */
+    rollingUsd?: number;
+    /** Where the rolling total lives. Omit for in-memory (per instance). */
+    store?: BudgetStore;
+}
+/** Per-call options shared by every capability: which tier, optional routing
+ *  override, optional fallback chain, and a free-text purpose for cost reports. */
+interface CallOptions {
+    tier?: Tier;
+    /** Override any part of the resolved TierSpec for this call only. */
+    override?: Partial<TierSpec>;
+    /** Ordered fallbacks tried if the primary route errors (inventory finding:
+     *  cms/trail/sanne/xrt81 all hand-roll this — make it first-class). */
+    fallback?: (Tier | TierSpec)[];
+    purpose?: string;
+    /** Consumer-defined attribution dimensions (e.g. {tenantId}) carried onto
+     *  Usage and forwarded by the cost sink for per-tenant cost breakdown (F011). */
+    labels?: Record<string, string>;
+}
+interface ChatRequest {
+    messages: Message[];
+    spec: TierSpec;
+    tools?: Tool[];
+    maxTokens?: number;
+    /** F039 — Mistral prompt caching. A stable application-level id for "the same
+     *  conversation" (a conversation id, a session id). Requests sharing a prefix AND
+     *  this key reuse the cached prefix at 10% of the input rate. Not auto-generated:
+     *  only the caller knows what "the same conversation" means, and an SDK-invented
+     *  key would either collide across tenants or never hit.
+     *
+     *  BIND IT TO THE TENANT, not only to the conversation. This key IS a shared-prefix
+     *  identity: two callers passing the same key can be served each other's cached
+     *  prefix. So two tenants with identical transcripts must still get DIFFERENT keys
+     *  — derive it from (tenant, conversation), never from the conversation alone.
+     *  (components' requirement while building @broberg/chat, 2026-08-27, where two
+     *  knowledge bases are written for readers with different permissions.) */
+    promptCacheKey?: string;
+    /** F039.2 — prompt caching is ON by default where the provider supports it.
+     *  Set false to opt out (e.g. a one-shot call whose prefix will never repeat).
+     *  Off has no cost benefit and no penalty; a cache MISS was measured to cost
+     *  exactly the same as a call with no key at all. */
+    promptCache?: boolean;
+    temperature?: number;
+    /** F074.3 — Mistral's `reasoning_effort`. Undefined = the SDK's default: "none" for
+     *  models that think by default (Large 4), nothing for the rest. */
+    reasoningEffort?: "none" | "high";
+    /** "json" → request JSON-object output where the provider supports it (F009). */
+    responseFormat?: "json" | "text";
+}
+interface ChatResult {
+    text: string;
+    toolCalls?: ToolCall[];
+    usage: Usage;
+}
+/** A single event from `ai.chatStream` / `adapter.chatStream` (F8). A streamed
+ *  turn yields `text`/`tool_call` events as they arrive, one `usage` event when
+ *  the provider reports totals, and a terminal `finish` (or `error`). Tool calls
+ *  are emitted COMPLETE — accumulated across wire fragments, never partial. */
+type ChatStreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "usage";
+    costUsd: number;
+    model: string;
+    usage: Usage;
+} | {
+    type: "finish";
+    reason: "end_turn" | "tool_calls" | "length" | "stop";
+} | {
+    type: "error";
+    message: string;
+    status?: number;
+};
+/** A trained LoRA to merge at inference time (F021). */
+interface LoraWeight {
+    /** URL (or fal path) to the LoRA weights. */
+    path: string;
+    /** Scales the LoRA before merging (default 1). */
+    scale?: number;
+}
+interface ImageRequest {
+    prompt: string;
+    spec: TierSpec;
+    width?: number;
+    height?: number;
+    /** LoRAs to merge at inference (F021) — e.g. a trained brand/style LoRA. */
+    loras?: LoraWeight[];
+    /** F023 — a BFL finetune id (a subject trained in the BFL dashboard). Routes to the
+     *  EU-resident BFL finetuned-portrait endpoint. */
+    finetune?: string;
+    /** F023 — how strongly the finetune is applied (BFL finetune_strength, ~0–2). */
+    finetuneStrength?: number;
+    /** F023.5 — 1–8 reference photos of a subject (URL or raw bytes). Routes to the
+     *  EU-resident BFL FLUX 2 multi-reference endpoint — generate a likeness with NO
+     *  training step. Bytes are base64-inlined into the EU call (no cross-region fetch). */
+    referenceImages?: (string | Uint8Array)[];
+    /** F023.5 — fixed seed for reproducible output (BFL). */
+    seed?: number;
+    /** F023.5 — output container (BFL FLUX 2): "jpeg" | "png" | "webp". Default jpeg. */
+    outputFormat?: "jpeg" | "png" | "webp";
+    /** F023.5 — BFL content-moderation strictness, 0 (strict) … 6 (lax). Default 2. */
+    safetyTolerance?: number;
+    /** F021.4 — re-roll once with a fresh seed if fal's safety-checker false-positives
+     *  and returns a black image (has_nsfw_concepts). fal only. */
+    retryOnBlack?: boolean;
+}
+interface ImageResult {
+    url: string;
+    usage: Usage;
+}
+/** Image-to-video generation (F024) — animate a still into a short clip. */
+interface AnimateRequest {
+    /** Input image: a URL (passed through) or raw bytes. Where bytes are uploaded is
+     *  the ADAPTER's business — fal uses fal storage, the Gemini/Veo default inlines
+     *  them — so do not read a storage provider out of this field. */
+    image: string | Uint8Array;
+    /** Motion/scene prompt, e.g. "the subject turns and smiles". */
+    prompt?: string;
+    /** Clip length in seconds (provider-dependent; Veo ≤ 8s). */
+    durationSec?: number;
+    /** e.g. "720p" / "1080p" (provider-dependent). */
+    resolution?: string;
+    spec: TierSpec;
+}
+interface AnimateResult {
+    /** URL to the generated video. For fal this is a public hosted URL; for the
+     *  Gemini/Veo route it is Google's file URI (needs the API key to fetch — the
+     *  bytes are also returned below, already downloaded). */
+    url: string;
+    /** The downloaded video bytes — set by providers whose result URL is auth-gated
+     *  or short-lived (Gemini/Veo). Absent for providers that return a public URL (fal). */
+    bytes?: Uint8Array;
+    /** MIME type of `bytes` (e.g. "video/mp4"). */
+    mimeType?: string;
+    usage: Usage;
+}
+/** Style/brand LoRA training (F021) — fal fal-ai/flux-lora-fast-training. */
+interface TrainStyleRequest {
+    /** A hosted archive URL, or an array of image URLs the SDK zips in-memory. */
+    images: string | string[];
+    spec: TierSpec;
+    /** Style LoRA (disables captioning/masks). Default true. */
+    isStyle?: boolean;
+    triggerWord?: string;
+    /** Training steps (~1000 typical). */
+    steps?: number;
+    createMasks?: boolean;
+}
+interface TrainStyleResult {
+    /** URL to the trained LoRA weights — pass to ai.image({ lora }). */
+    loraUrl: string;
+    /** URL to the training config file. */
+    configUrl: string;
+    usage: Usage;
+}
+interface EmbeddingRequest {
+    input: string[];
+    spec: TierSpec;
+}
+interface EmbeddingResult {
+    vectors: number[][];
+    usage: Usage;
+}
+/** Timestamp granularity a caller can request from `ai.transcribe` (F036). */
+type TimestampGranularity = "word" | "segment";
+/** A single word with its start/end offset in seconds. */
+interface WordTimestamp {
+    word: string;
+    start: number;
+    end: number;
+}
+/** A phrase/sentence segment with its start/end offset in seconds. */
+interface SegmentTimestamp {
+    text: string;
+    start: number;
+    end: number;
+}
+interface TranscribeRequest {
+    /** Raw audio bytes (the client resolves a URL to bytes before calling). */
+    audio: Uint8Array;
+    language?: string;
+    /** Audio length in seconds — enables per-minute cost (Whisper). Omit → cost 0. */
+    durationSec?: number;
+    /** Bias recognition toward these brand/jargon terms (Azure phraseList, F029.3).
+     *  Providers without biasing support (Voxtral/Whisper) ignore it. */
+    phrases?: string[];
+    /** Request timestamps (F036). The client normalizes the input to this array.
+     *  Adapters without timestamp support ignore it (result omits words/segments). */
+    timestamps?: TimestampGranularity[];
+    spec: TierSpec;
+}
+interface TranscribeResult {
+    text: string;
+    /** Word-level timing — present only when "word" timestamps were requested. */
+    words?: WordTimestamp[];
+    /** Segment (phrase/sentence) timing — present when any timestamps were requested. */
+    segments?: SegmentTimestamp[];
+    usage: Usage;
+}
+interface OcrRequest {
+    /** A URL, data-URL, or raw bytes of the document/image. */
+    document: string | Uint8Array;
+    mimeType?: string;
+    spec: TierSpec;
+}
+interface OcrPage {
+    index: number;
+    markdown: string;
+}
+interface OcrResult {
+    pages: OcrPage[];
+    usage: Usage;
+}
+interface ModerationRequest {
+    input: string[];
+    spec: TierSpec;
+}
+interface ModerationItem {
+    /** True if any category tripped. */
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    categoryScores: Record<string, number>;
+}
+interface ModerationResult {
+    results: ModerationItem[];
+    usage: Usage;
+}
+/** TypeSafe's EntryType: plain text OR JSON structure. Instructions, choice option
+ *  descriptions, score levels and noul criteria all accept it — and TypeSafe's own
+ *  headline patterns (walking a taxonomy, a JSON rubric that sharpens the boundary
+ *  between options) depend on it. Measured live 2026-10-01: structured instructions and
+ *  object-valued choice options → 200. */
+type JudgeEntry = string | null | unknown[] | {
+    [key: string]: unknown;
+};
+type JudgeQuestion = 
+/** `criteria` is an OBJECT with `true`/`false`, not a string — measured live: a string
+ *  is a 422 from TypeSafe. The first version of this type had it as a string, which
+ *  let through exactly the shape the server refuses. */
+{
+    type: "noul";
+    instructions: JudgeEntry;
+    criteria?: {
+        true?: JudgeEntry;
+        false?: JudgeEntry;
+    };
+} | {
+    type: "choice";
+    instructions: JudgeEntry;
+    criteria: Record<string, JudgeEntry>;
+} | {
+    type: "score";
+    instructions: JudgeEntry;
+    criteria: JudgeEntry[];
+};
+interface JudgeNoulAnswer {
+    type: "noul";
+    /** Probability 0–1 that the answer is yes. */
+    noul: number;
+}
+interface JudgeChoiceAnswer {
+    type: "choice";
+    /** The key of the most probable option. ALWAYS one of yours — Jev cannot answer
+     *  "none of these". Read `confidence` to decide whether to act on it. */
+    choice: string;
+    probabilities: Record<string, number>;
+    /** How peaked the distribution is, 0–1. NOT the same as the winning probability. */
+    confidence: number;
+}
+interface JudgeScoreAnswer {
+    type: "score";
+    /** Probability-weighted level; can fall BETWEEN levels (1.5). */
+    score: number;
+    probabilities: Record<string, number>;
+    /** Level number → the level as you DESCRIBED it. If you passed structured levels,
+     *  the legend echoes structure, not text — measured live: {"0":{"level":"minor"}}. */
+    legend: Record<string, JudgeEntry>;
+    confidence: number;
+}
+type JudgeAnswer = JudgeNoulAnswer | JudgeChoiceAnswer | JudgeScoreAnswer;
+interface JudgeRequest {
+    state: string | string[] | Record<string, unknown>;
+    questions: Record<string, JudgeQuestion>;
+    spec: TierSpec;
+}
+interface JudgeResult {
+    answers: Record<string, JudgeAnswer>;
+    usage: Usage;
+}
+interface DialogueTurn {
+    text: string;
+    voiceId: string;
+}
+interface DialogueRequest {
+    inputs: DialogueTurn[];
+    /** F051.4 — the pronunciation dictionary, applied to EACH line. cms measured the
+     *  gap: a two-host podcast could not get a dictionary at all, so "broberg.ai" was
+     *  said wrong in every episode — they could fix the sponsor read and the host's
+     *  hand-off (both `ai.tts`) and not the conversation, which is 95% of the audio. */
+    pronunciations?: Pronunciation[];
+    /** Output container, e.g. "mp3" (default). */
+    format?: string;
+    spec: TierSpec;
+}
+interface PodcastResult {
+    /** Episode audio bytes. */
+    audio: Uint8Array;
+    mimeType: string;
+    /** F055 — per-word timings, present only when `wordTimings` was asked for AND the
+     *  route produces them. Its ABSENCE says "not available here"; an empty `words` array
+     *  would say "the text had no words", which is a different claim.
+     *
+     *  `sourceStart`/`sourceEnd` index the ORIGINAL text you passed, not the SSML we sent
+     *  — Azure reports only audio time, so the link back to the manuscript is derived
+     *  here. `unaligned` names any spoken word that could not be placed. */
+    wordTimings?: AlignedWordTimings;
+    /** F055.4 — the EXACT markup we sent the provider, verbatim, not rebuilt.
+     *
+     *  Why it exists: the text you passed is not what was spoken. A pronunciation
+     *  dictionary rewrites it, so `text` is a RETELLING of the audio — and without this
+     *  field a consumer cannot check our retelling any more than we could check theirs.
+     *  cms filed exactly that (11 September 2026) while we were asking them for markup
+     *  only we could produce.
+     *
+     *  UNDEFINED when the route builds no markup (ElevenLabs routes by voice, not SSML).
+     *  An empty string would say "we sent empty markup", which is a different claim. */
+    ssml?: string;
+    usage: Usage;
+}
+
+interface TtsRequest {
+    text: string;
+    voiceId: string;
+    /** BCP-47 locale (e.g. "da-DK"). Azure uses it for SSML xml:lang; ElevenLabs ignores it. */
+    lang?: string;
+    /** Provider output-format hint (e.g. an Azure X-Microsoft-OutputFormat); ElevenLabs ignores it. */
+    format?: string;
+    /** Speaking-rate multiplier (Azure): 1 = normal, 0.9 = 10% slower, 1.1 = faster. ElevenLabs ignores it. */
+    rate?: number;
+    /** F051 — pronunciation dictionary. A Danish voice says English jargon wrongly:
+     *  measured on da-DK, "AI" comes out as the word "aj", "native" as "nativ".
+     *
+     *  Azure renders these as SSML (`<sub alias>` / `<phoneme alphabet="ipa" ph>`);
+     *  ElevenLabs has no SSML and can only apply `alias`. **This is the CONTROLLED DOOR
+     *  into SSML** — the substitution happens adapter-side AFTER the text is escaped, so
+     *  `text` can never inject markup, and `alias`/`ipa` are escaped too. */
+    pronunciations?: Pronunciation[];
+    /** F055 — ask for per-word timings so a reader can highlight each word as it is
+     *  spoken. Azure only. Absent from the result means "this route does not produce
+     *  them", which is a different answer from an empty list.
+     *
+     *  **This changes the ROUTE, not just the payload.** The real-time endpoint returns
+     *  audio only; word boundaries exist solely on Azure's asynchronous batch synthesis
+     *  API, so the call becomes submit → poll → fetch. Microsoft quotes 10–20s for half
+     *  of all jobs and up to 120s for 95%. Worth it for a pre-generated, cached reading;
+     *  wrong for anything a user is waiting on. */
+    wordTimings?: boolean;
+    spec: TierSpec;
+}
+interface BatchRequestItem {
+    customId: string;
+    prompt: string;
+}
+interface BatchJob {
+    jobId: string;
+    status: string;
+    total?: number;
+    completed?: number;
+}
+interface BatchResultItem {
+    customId: string;
+    text: string;
+}
+/** The thin contract every provider implements (F4). A provider need only
+ *  support the capabilities it offers — `chat` is the baseline; vision/image/
+ *  embedding are optional and absence is a typed capability gap. */
+interface ProviderAdapter {
+    readonly name: string;
+    /** Every capability is optional — an adapter implements only what it supports
+     *  (e.g. fal does image only). The client guards each call and throws a clear
+     *  "provider X does not support Y" when a capability is absent. */
+    chat?(req: ChatRequest): Promise<ChatResult>;
+    /** Streaming chat (F8). Optional — absence is a typed "no streaming support".
+     *  Same request shape as chat; yields ChatStreamEvents as the turn unfolds. */
+    chatStream?(req: ChatRequest): AsyncIterable<ChatStreamEvent>;
+    /** Dedicated translation engine (F032) — e.g. DeepL. When absent, `ai.translate`
+     *  falls back to a chat prompt-contract (the historical default for every
+     *  other provider). `to`/`from` are provider-specific: a chat-routed call
+     *  accepts free-form names ("Danish"); DeepL requires real codes ("DA"). */
+    translate?(req: TranslateRequest): Promise<TranslateResult>;
+    vision?(req: ChatRequest): Promise<ChatResult>;
+    image?(req: ImageRequest): Promise<ImageResult>;
+    /** Image-to-video generation (F024) — animate a still into a short clip. gemini
+     *  (Veo 3.1) by default; override to fal for Kling/Seedance. Name only the DEFAULT
+     *  route here — provider-doc-drift.test.ts fails if this and DEFAULT_ANIMATE_SPEC
+     *  disagree, because this sentence is the editor tooltip a consumer reads when
+     *  deciding which API key to buy. */
+    animate?(req: AnimateRequest): Promise<AnimateResult>;
+    /** Train a style/brand LoRA from images (F021). fal. */
+    trainStyle?(req: TrainStyleRequest): Promise<TrainStyleResult>;
+    embedding?(req: EmbeddingRequest): Promise<EmbeddingResult>;
+    transcribe?(req: TranscribeRequest): Promise<TranscribeResult>;
+    ocr?(req: OcrRequest): Promise<OcrResult>;
+    moderate?(req: ModerationRequest): Promise<ModerationResult>;
+    /** F066 — typed decisions with calibrated probabilities (TypeSafe Jev). */
+    judge?(req: JudgeRequest): Promise<JudgeResult>;
+    /** Multi-voice dialogue → one audio episode (F020). ElevenLabs. */
+    dialogue?(req: DialogueRequest): Promise<PodcastResult>;
+    /** Single-voice TTS (F020.4) → audio. ElevenLabs. */
+    tts?(req: TtsRequest): Promise<PodcastResult>;
+    /** Batch (F016.1) — async chat-request processing at 50% cost. Mistral. */
+    batchSubmit?(req: {
+        items: BatchRequestItem[];
+        spec: TierSpec;
+    }): Promise<BatchJob>;
+    batchStatus?(req: {
+        jobId: string;
+        spec: TierSpec;
+    }): Promise<BatchJob>;
+    batchResults?(req: {
+        jobId: string;
+        spec: TierSpec;
+    }): Promise<BatchResultItem[]>;
+}
+interface TranslateResult {
+    text: string;
+    usage: Usage;
+}
+/** Dedicated-engine translation request (F032) — used only by adapters that
+ *  implement `ProviderAdapter.translate` directly (e.g. DeepL); chat-routed
+ *  providers never see this shape, they get a built prompt instead. */
+interface TranslateRequest {
+    text: string;
+    to: string;
+    from?: string;
+    spec: TierSpec;
+}
+
+type AvailabilityStatus = "available" | "suspended" | "unknown";
+/** Where a model's current availability came from: the curated default seed,
+ *  or a live provider refresh (Anthropic GET /v1/models). */
+type AvailabilitySource = "default" | "refresh";
+/** One row of the shared status read — what a UI model-picker renders. */
+interface ModelStatus {
+    /** Canonical provider model id, e.g. "claude-fable-5". */
+    id: string;
+    /** Short/tier alias, e.g. "fable" (the first registered alias). */
+    alias?: string;
+    /** "anthropic" | "openai" | "gemini" | "mistral" | … */
+    provider: string;
+    available: boolean;
+    status: AvailabilityStatus;
+    /** Friendly reason, e.g. "suspended — US export-control directive (2026-06-12)". */
+    note?: string;
+    source: AvailabilitySource;
+}
+/** Result of resolveModel — the spawn / call path consumes this synchronously. */
+interface ResolveResult {
+    /** True when the requested model itself is available. */
+    ok: boolean;
+    /** The id to actually use: `requested` when ok, else the first available fallback. */
+    model: string;
+    /** What the caller asked for (id or alias, normalized to the canonical id). */
+    requested: string;
+    provider?: string;
+    /** True when `model` differs from `requested` because we fell back. */
+    fellBack: boolean;
+    status: AvailabilityStatus;
+    /** Why it degraded / why it is unavailable. */
+    reason?: string;
+    /** The registry row's caveat, surfaced on the SUCCESS path too (F057.2).
+     *
+     *  `reason` only ever appears when a model is unavailable, so a caveat written
+     *  on an AVAILABLE row — "documented to deprecate 2026-07-24", "preview", a
+     *  known rate limit — was reachable through listModels() and invisible to the
+     *  one caller who most needs it: the gate. A consumer passing requireKnown got
+     *  a clean green with the warning sitting one call away, unread. Carrying it
+     *  here costs an optional field and makes `ok:true` able to say "yes, but". */
+    note?: string;
+}
+/** Thrown by resolveModel when the requested model is unavailable, no usable
+ *  fallback exists, and the caller passed `throwIfUnavailable`. Callers flag on
+ *  `.code === "model_unavailable"`. */
+declare class ModelUnavailableError extends Error {
+    readonly code = "model_unavailable";
+    readonly requested: string;
+    readonly provider?: string;
+    readonly note?: string;
+    constructor(requested: string, note?: string, provider?: string);
+}
+
+interface ResolveOptions {
+    /** One id/alias or an ordered chain to try when `requested` is unavailable. */
+    fallback?: string | string[];
+    /** Scope hint (passed through to the result); does not gate lookup. */
+    provider?: string;
+    /** Throw ModelUnavailableError instead of returning ok:false when there is no
+     *  usable fallback. For callers that want to flag rather than degrade. */
+    throwIfUnavailable?: boolean;
+    /** Treat an id we do not track as UNUSABLE instead of fail-open.
+     *
+     *  Default is fail-open: we never block a model we simply do not track. That is
+     *  right for liveness, and wrong for a caller who is GATING — cms measured the
+     *  consequence: resolveModel("cheap") answered {ok:true, model:"cheap"}, so a
+     *  consumer following our own instruction to gate on `ok` passed the gate and
+     *  then sent the literal string "cheap" to a provider as a model id. A
+     *  success-shaped non-answer is worse than an error, because an error gets
+     *  handled and a shape does not.
+     *
+     *  Set this when you need "a model you actually know about". Off by default so
+     *  no existing caller changes behaviour. */
+    requireKnown?: boolean;
+}
+/** The shared status read — UI pickers grey out `available:false` rows. */
+declare function listModels(opts?: {
+    provider?: string;
+}): ModelStatus[];
+/**
+ * Resolve a requested model (id or alias) to one that is actually usable.
+ * Synchronous + offline by contract (cardmem #4842) — reads the registry only.
+ *
+ * - Available → pass through ({ ok:true, fellBack:false }).
+ * - Unavailable + a fallback that IS available → swap ({ ok:false, fellBack:true }).
+ * - Unavailable + no usable fallback → throw (throwIfUnavailable) or return ok:false.
+ * - Unknown id → treated available (never block a model we do not track).
+ */
+declare function resolveModel(requested: string, opts?: ResolveOptions): ResolveResult;
+
+interface TierDescription {
+    tier: Tier;
+    provider: string;
+    model: string;
+    /** false when the model is a "-latest" alias the provider can move under us. */
+    pinned: boolean;
+    /** USD per 1M tokens from the pricing table; undefined when the model is unpriced. */
+    inputPer1M?: number;
+    outputPer1M?: number;
+    cacheReadPer1M?: number;
+}
+/** The built-in default for a tier. A client's own `defaults` or a per-call
+ *  `override` can route elsewhere — read usage.model off the response for that. */
+declare function describeTier(tier: Tier): TierDescription;
+
+export { type Role as $, type AnimateResult as A, type BatchRequestItem as B, type ChatResult as C, type DialogueRequest as D, type EmbeddingResult as E, type JudgeChoiceAnswer as F, type JudgeNoulAnswer as G, type JudgeQuestion as H, type ImageResult as I, type JudgeResult as J, type JudgeScoreAnswer as K, type LoraWeight as L, type ModerationResult as M, type Message as N, type OcrResult as O, type PodcastResult as P, type ModelStatus as Q, type Region as R, ModelUnavailableError as S, type Tier as T, type Usage as U, type ModerationItem as V, type ModerationRequest as W, type OcrPage as X, type OcrRequest as Y, type ResolveOptions as Z, type ResolveResult as _, type ChatStreamEvent as a, type TierDescription as a0, type TrainStyleRequest as a1, type TranscribeRequest as a2, type TtsRequest as a3, type WordTiming as a4, alignWordTimings as a5, classifyRegionName as a6, describeTier as a7, listModels as a8, regionOfHost as a9, regionOfProvider as aa, resolveModel as ab, type TranslateResult as b, type TrainStyleResult as c, type TranscribeResult as d, type TierSpec as e, type BatchJob as f, type BatchResultItem as g, type ProviderAdapter as h, type CostSink as i, type ToolCall as j, type Tool as k, type Transport as l, type Capability as m, type BudgetConfig as n, type BudgetStore as o, type AlignedWordTimings as p, type AvailabilitySource as q, type AvailabilityStatus as r, type AzureWordBoundary as s, type CallOptions as t, type ChatRequest as u, type ContentPart as v, type DialogueTurn as w, type EmbeddingRequest as x, type ImageRequest as y, type JudgeAnswer as z };