@xberg-io/liter-llm 1.11.3 → 1.17.3

package/index.d.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by alef — DO NOT EDIT.
-// alef:hash:7944d9976ed5e784d58bb60b20a64df43c6faa98460b1282aa94dfadc636b045
+// alef:hash:6bae00d6b31bd5ec9e80699322018c3a78359cee1f06b9e2b7ffbdc6f1d4bc21
 // To regenerate: alef generate
-// To verify freshness: alef verify --exit-code
+// To verify freshness: alef verify
 /* eslint-disable */
 
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
@@ -10,8 +10,8 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | { [key:
  * Return all provider configs from the registry.
  *
  * Useful for tooling, documentation generation, or runtime enumeration.
- * Returns the public [`ProviderConfig`] slice (without capability flags).
- * To query capability flags for a specific provider use [`capabilities`].
+ * Returns the public `ProviderConfig` slice (without capability flags).
+ * To query capability flags for a specific provider use `capabilities`.
  */
 export declare function allProviders(): Array<ProviderConfig>;
 
@@ -31,8 +31,8 @@ export declare function capabilities(providerName: string): ProviderCapabilities
  * Assert that `current_len + incoming` does not exceed `limit`.
  *
  * Call this before appending `incoming` bytes to any buffer that must
- * stay below `limit`.  Returns `Err(LiterLlmError::Streaming)` on overflow
- * and emits a `tracing::warn!` with context.
+ * stay below `limit`.  Returns `Err(LiterLlmError.Streaming)` on overflow
+ * and emits a `tracing.warn!` with context.
  */
 export declare function checkBound(context: string, currentLen: number, incoming: number, limit: number): void;
 
@@ -40,6 +40,9 @@ export declare function checkBound(context: string, currentLen: number, incoming
  * Remove all guardrails from the global registry.
  *
  * Primarily useful in tests to reset state between test cases.
+ *
+ * If the lock was poisoned by a panicking guardrail on a previous access,
+ * the poisoned state is recovered rather than propagating the panic.
  */
 export declare function clear(): void;
 
@@ -48,7 +51,7 @@ export declare function clear(): void;
  * `completion_cost_with_cache`, and `model_info` to the
  * embedded catalog.
  *
- * Primarily a test seam (see [`install_catalog_overlay_from_str`]); also
+ * Primarily a test seam (see `install_catalog_overlay_from_str`); also
  * usable by long-running processes that want to abandon a runtime refresh.
  */
 export declare function clearCatalogOverlay(): void;
@@ -78,9 +81,9 @@ export declare function completionCost(model: string, promptTokens: number, comp
  * input rate.
  *
  * Returns `None` if the model is not present in the embedded pricing
- * registry, mirroring [`completion_cost`].
+ * registry, mirroring `completion_cost`.
  *
- * When the model has [`ModelPricing::tiers`], the tier whose
+ * When the model has `ModelPricing.tiers`, the tier whose
  * `min_context_tokens` is the highest value `<= prompt_tokens` supplies the
  * input/output/cache rates for the whole call; models without tiers (or
  * when `prompt_tokens` is below every tier threshold) use the base rates
@@ -99,13 +102,13 @@ export declare function completionCostWithCache(model: string, promptTokens: num
 export declare function complexProviderNames(): Array<string>;
 
 /**
- * Count tokens for a full [`ChatCompletionRequest`].
+ * Count tokens for a full `ChatCompletionRequest`.
  *
  * Sums tokens across all message text contents plus a per-message overhead
  * of ~4 tokens (for role, separators, and formatting metadata). Tool
  * definitions and multimodal content parts (images, audio, documents) are
  * not counted — only textual content contributes to the token total.
- * @throws Returns [`LiterLlmError::BadRequest`] if the tokenizer cannot be loaded or
+ * @throws Returns `LiterLlmError.BadRequest` if the tokenizer cannot be loaded or
  * if tokenization fails for any message.
  */
 export declare function countRequestTokens(model: string, req?: ChatCompletionRequest | undefined | null): number;
@@ -116,7 +119,7 @@ export declare function countRequestTokens(model: string, req?: ChatCompletionRe
  * The tokenizer is resolved from the model name prefix (e.g. `"gpt-4o"` maps
  * to the `Xenova/gpt-4o` HuggingFace tokenizer). Tokenizers are cached after
  * first load.
- * @throws Returns [`LiterLlmError::BadRequest`] if the tokenizer cannot be loaded
+ * @throws Returns `LiterLlmError.BadRequest` if the tokenizer cannot be loaded
  * (e.g. network failure on first use) or if tokenization itself fails.
  */
 export declare function countTokens(model: string, text: string): number;
@@ -126,8 +129,8 @@ export declare function countTokens(model: string, text: string): number;
  *
  * This is the primary binding entry-point. All parameters except `api_key`
  * are optional — omitting them uses the same defaults as
- * [`ClientConfigBuilder`].
- * @throws Returns [`LiterLlmError`] if the underlying HTTP client cannot be
+ * `ClientConfigBuilder`.
+ * @throws Returns `LiterLlmError` if the underlying HTTP client cannot be
  * constructed, or if the resolved provider configuration is invalid.
  */
 export declare function createClient(apiKey: string, baseUrl?: string | undefined | null, timeoutSecs?: number | undefined | null, maxRetries?: number | undefined | null, modelHint?: string | undefined | null): DefaultClient;
@@ -136,13 +139,13 @@ export declare function createClient(apiKey: string, baseUrl?: string | undefine
  * Create a new LLM client from a JSON string.
  *
  * The JSON object accepts the same fields as `liter-llm.toml` (snake_case).
- * @throws Returns [`LiterLlmError::BadRequest`] if `json` is not valid JSON or
+ * @throws Returns `LiterLlmError.BadRequest` if `json` is not valid JSON or
  * contains unknown fields.
  */
 export declare function createClientFromJson(json: string): DefaultClient;
 
 /**
- * Decode a base64 data URL into [`DecodedDataUrl`].
+ * Decode a base64 data URL into `DecodedDataUrl`.
  *
  * Returns `None` for:
  * - Non-data URLs (strings that do not start with `"data:"`).
@@ -157,7 +160,7 @@ export declare function decodeDataUrl(url: string): DecodedDataUrl | null;
 /**
  * Encode bytes as a base64 data URL: `data:<mime>;base64,<b64>`.
  *
- * `mime` defaults to [`IMAGE_PNG`] when `None`.
+ * `mime` defaults to `IMAGE_PNG` when `None`.
  */
 export declare function encodeDataUrl(bytes: Uint8Array, mime?: string | undefined | null): string;
 
@@ -169,7 +172,7 @@ export declare function encodeDataUrl(bytes: Uint8Array, mime?: string | undefin
  * another rustls crypto provider has already been installed is safe: the
  * `Err` from `install_default()` is silently ignored.
  *
- * Called automatically by every internal `reqwest::Client` constructor
+ * Called automatically by every internal `reqwest.Client` constructor
  * (auth providers, default HTTP client). Bindings and downstream consumers
  * reach those constructors transitively, so no manual init is required.
  *
@@ -186,9 +189,9 @@ export declare function ensureCryptoProvider(): void;
  * the network and disk cache entirely.
  *
  * Parses and flattens `catalog_json` with the same
- * [`registry_from_catalog_str`] logic used for the embedded catalog and the
+ * `registry_from_catalog_str` logic used for the embedded catalog and the
  * network refresh path, then atomically swaps it in as the active overlay.
- * A parse failure returns [`CatalogRefreshError::Parse`] and leaves any
+ * A parse failure returns `CatalogRefreshError.Parse` and leaves any
  * existing overlay untouched.
  *
  * This is primarily a testable seam: it lets tests exercise overlay
@@ -202,16 +205,13 @@ export declare function installCatalogOverlayFromStr(catalogJson: string): void;
  * Content shape for assistant messages.
  *
  * `#[serde(untagged)]` means providers returning a plain scalar string for the
- * `content` field still deserialise correctly into `AssistantContent::Text(_)`.
+ * `content` field still deserialise correctly into `AssistantContent.Text(_)`.
  * Providers returning an array of typed parts (e.g. after an image-generation
- * or audio-synthesis request) deserialise into `AssistantContent::Parts(_)`.
+ * or audio-synthesis request) deserialise into `AssistantContent.Parts(_)`.
  */
-export declare enum AssistantContent {
-  /** Plain text response (the common case for text-only models). */
-  Text = "Text",
-  /** Structured parts — text, refusals, output images, output audio. */
-  Parts = "Parts",
-}
+export type AssistantContent =
+  | string
+  | Array<AssistantPart>
 
 /** Assistant's response to a user message. */
 export interface AssistantMessage {
@@ -225,7 +225,12 @@ export interface AssistantMessage {
   readonly name?: string
   /** Tool calls the model wants to execute, if any. */
   readonly toolCalls?: Array<ToolCall>
-  /** Refusal reason, if the model declined to respond per safety policies. */
+  /**
+   * Refusal reason, if the model declined to respond per safety policies.
+   *
+   * OpenAI's response schema requires this key to be present even when null,
+   * so it is deliberately not `skip_serializing_if`.
+   */
   readonly refusal?: string
   /** Deprecated legacy function_call field; retained for API compatibility. */
   readonly functionCall?: FunctionCall
@@ -248,7 +253,12 @@ export type AssistantPart =
   | { type: 'output_image'; imageUrl: ImageUrl }
   | { type: 'output_audio'; audio: AudioContent }
 
-/** Audio content part for speech-capable models. */
+/**
+ * Audio content part for speech-capable models.
+ *
+ * No `deny_unknown_fields`: shared with the response side (see
+ * `AssistantPart.OutputAudio`), same rationale as `ImageUrl` (#51).
+ */
 export interface AudioContent {
   /** Base64-encoded audio data. */
   readonly data?: string
@@ -373,6 +383,30 @@ export declare enum BatchStatus {
   Cancelled = "cancelled",
 }
 
+/**
+ * AWS Bedrock configuration.
+ *
+ * All fields are optional; anything left unset falls back to the standard
+ * AWS environment variables (`AWS_DEFAULT_REGION` / `AWS_REGION`,
+ * `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`,
+ * `BEDROCK_CROSS_REGION`).
+ *
+ * Implements `Debug` manually (see below) so the AWS credential fields are
+ * redacted rather than printed in full.
+ */
+export interface BedrockConfig {
+  /** AWS region (e.g. `"us-east-1"`). */
+  readonly region?: string
+  /** Cross-region inference profile prefix (e.g. `"us"`). */
+  readonly crossRegionPrefix?: string
+  /** Explicit AWS access key ID. */
+  readonly accessKeyId?: string
+  /** Explicit AWS secret access key. */
+  readonly secretAccessKey?: string
+  /** Explicit AWS session token (temporary credentials). */
+  readonly sessionToken?: string
+}
+
 /** Configuration for budget enforcement. */
 export interface BudgetConfig {
   /** Maximum total spend across all models, in USD.  `None` means unlimited. */
@@ -402,7 +436,7 @@ export interface CacheConfig {
 }
 
 /**
- * Plain-data configuration for [`refresh_catalog`].
+ * Plain-data configuration for `refresh_catalog`.
  *
  * Deliberately FFI/binding-friendly: no `Duration` or `PathBuf`, just
  * primitives that translate directly across language boundaries.
@@ -410,14 +444,14 @@ export interface CacheConfig {
 export interface CatalogRefreshConfig {
   /**
    * Runtime catalog refresh is entirely opt-in: when `false`,
-   * [`refresh_catalog`] is a no-op that returns
-   * `Ok(`[`RefreshOutcome::Disabled`]`)` without touching the network,
+   * `refresh_catalog` is a no-op that returns
+   * `Ok(``RefreshOutcome.Disabled``)` without touching the network,
    * the filesystem, or the overlay registry.
    */
   readonly enabled?: boolean
   /**
    * Source URL to fetch `catalog.json` from. Must be `https`. Defaults to
-   * [`DEFAULT_CATALOG_URL`]; configurable so self-hosted mirrors work.
+   * `DEFAULT_CATALOG_URL`; configurable so self-hosted mirrors work.
    */
   readonly sourceUrl?: string
   /**
@@ -427,7 +461,7 @@ export interface CatalogRefreshConfig {
   readonly ttlSeconds?: number
   /**
    * Filesystem path for the on-disk cache. `None` uses a default path
-   * under `std::env::temp_dir()`.
+   * under `std.env.temp_dir()`.
    */
   readonly cachePath?: string
 }
@@ -461,9 +495,26 @@ export interface ChatCompletionRequest {
   readonly model?: string
   /** Conversation history from oldest to newest. */
   readonly messages?: Array<Message>
-  /** Sampling temperature in `[0.0, 2.0]`. Higher increases randomness. Defaults to 1.0. */
+  /**
+   * Sampling temperature. Higher increases randomness, lower is more deterministic.
+   * Defaults to 1.0.
+   *
+   * The accepted range depends on the provider the request is routed to. OpenAI-compatible
+   * providers accept `[0.0, 2.0]`; Anthropic and Amazon Bedrock both cap it at `1.0`, and
+   * for those two a value above the cap is rejected with a `BadRequest` error before the
+   * request is sent, rather than being silently clamped or left for the provider to reject.
+   *
+   * No range is enforced for providers whose own documentation does not state one — the
+   * value is forwarded and the provider decides. Consult the target provider's reference
+   * rather than assuming `[0.0, 2.0]` is portable.
+   */
   readonly temperature?: number
-  /** Nucleus sampling parameter in `[0.0, 1.0]`. Lower is more focused. */
+  /**
+   * Nucleus sampling parameter. Lower is more focused.
+   *
+   * Accepted ranges vary by provider (most document `[0.0, 1.0]`, but this is not
+   * universal — check the target provider's own documentation for its exact bounds).
+   */
   readonly topP?: number
   /** Number of chat completions to generate. Defaults to 1. */
   readonly n?: number
@@ -500,7 +551,7 @@ export interface ChatCompletionRequest {
   readonly streamOptions?: StreamOptions
   /** Random seed for reproducible outputs. Provider support varies. */
   readonly seed?: number
-  /** Reasoning effort level (low, medium, high) for extended-thinking models. */
+  /** Reasoning effort level (minimal, low, medium, high, max) for extended-thinking models. */
   readonly reasoningEffort?: ReasoningEffort
   /**
    * Output modalities to request from the model.
@@ -509,6 +560,49 @@ export interface ChatCompletionRequest {
    * translates these to `generationConfig.responseModalities` (uppercase).
    */
   readonly modalities?: Array<Modality>
+  /** Whether to return log probabilities of the output tokens. */
+  readonly logprobs?: boolean
+  /**
+   * Number of most-likely tokens to return log probabilities for, `0..=20`.
+   * Requires `logprobs` to be `true`.
+   */
+  readonly topLogprobs?: number
+  /**
+   * Upper bound on generated tokens, including reasoning tokens.
+   *
+   * Supersedes `max_tokens` on OpenAI reasoning models, which reject
+   * `max_tokens` outright.
+   */
+  readonly maxCompletionTokens?: number
+  /**
+   * Latency tier to process the request under (e.g. `"auto"`, `"default"`,
+   * `"flex"`).
+   */
+  readonly serviceTier?: string
+  /** Whether to store the completion for later retrieval by the provider. */
+  readonly store?: boolean
+  /** Developer-defined tags attached to the completion. */
+  readonly metadata?: Record<string, string>
+  /**
+   * Predicted output, for latency reduction when much of the response is
+   * known ahead of time.
+   *
+   * Untyped: the shape is provider-defined and still evolving, and the
+   * value is forwarded verbatim.
+   */
+  readonly prediction?: JsonValue
+  /**
+   * Audio output parameters, required when `modalities` includes `audio`.
+   *
+   * Untyped for the same reason as `prediction`.
+   */
+  readonly audio?: JsonValue
+  /**
+   * Web-search tool configuration for search-enabled models.
+   *
+   * Untyped for the same reason as `prediction`.
+   */
+  readonly webSearchOptions?: JsonValue
   /**
    * Provider-specific extra parameters merged into the request body.
    * Use for guardrails, safety settings, grounding config, etc.
@@ -551,21 +645,35 @@ export interface ChatCompletionTool {
 export interface Choice {
   /** Index of this choice in the choices array. */
   readonly index?: number
-  /** The assistant's message response. */
+  /**
+   * The assistant's message response.
+   *
+   * Serialized with an explicit `role: "assistant"`. The field is not stored
+   * on `AssistantMessage` because `Message` is an internally-tagged enum
+   * keyed on `role`, so a stored field would emit the key twice inside a
+   * request. OpenAI's response schema requires it here.
+   */
   readonly message?: AssistantMessage
   /** Why the model stopped generating (stop, length, tool_calls, content_filter, etc.). */
   readonly finishReason?: FinishReason
+  /**
+   * Per-token log probabilities, when the request asked for them.
+   *
+   * Required by OpenAI's response schema as an always-present, nullable key,
+   * so this is deliberately not `skip_serializing_if`.
+   */
+  readonly logprobs?: JsonValue
 }
 
 /**
- * A per-chunk transformation in the [`StreamPipeline`].
+ * A per-chunk transformation in the `StreamPipeline`.
  *
  * Each middleware receives a typed chunk and returns `Ok(Some(chunk))`
  * to pass it through (optionally modified), `Ok(None)` to drop the chunk,
  * or `Err(e)` to propagate a stream error.
  *
  * The trait is object-safe so multiple middleware implementations can be
- * chained inside [`StreamPipeline`].
+ * chained inside `StreamPipeline`.
  */
 export interface ChunkMiddleware {
   /**
@@ -637,9 +745,35 @@ export interface CreateImageRequest {
   readonly user?: string
 }
 
-/** Request to create a structured response. */
+/**
+ * Request to create a response via the OpenAI Responses API (`POST /responses`).
+ *
+ * # Provider support
+ *
+ * **The Responses API path is OpenAI-only.** This type models the OpenAI Responses
+ * wire format, and unlike `ChatCompletionRequest` the body is sent to the provider
+ * verbatim: neither `Provider.transform_request` nor `Provider.transform_response`
+ * runs for Responses calls, and no provider in `schemas/providers.json` declares a
+ * `responses` endpoint.
+ *
+ * Pointing a Responses call at a provider that does not natively serve the OpenAI
+ * `/responses` contract (Anthropic, Vertex, Bedrock, Cohere, Google AI, Azure) is not
+ * supported: the request goes out unmodified, so the provider rejects it or returns a
+ * body that cannot be deserialized into `ResponseObject`. Use
+ * `ChatCompletionRequest` for cross-provider work — that path applies the
+ * per-provider request and response normalization this one does not.
+ *
+ * `ChatCompletionRequest`: crate.types.ChatCompletionRequest
+ */
 export interface CreateResponseRequest {
-  /** Model ID. */
+  /**
+   * Model ID, as named by the OpenAI Responses API (e.g. `"gpt-5"`).
+   *
+   * Sent to the wire exactly as given. The Responses path performs none of the
+   * chat path's model handling: a `provider/model` routing prefix is **not**
+   * stripped and does **not** re-route the request, which stays pinned to the
+   * provider the client was constructed with.
+   */
   readonly model?: string
   /** Input data to process (e.g., a document to extract from). */
   readonly input?: JsonValue
@@ -653,6 +787,27 @@ export interface CreateResponseRequest {
   readonly maxOutputTokens?: number
   /** Optional metadata. */
   readonly metadata?: JsonValue
+  /**
+   * Extra top-level parameters shallow-merged into the request body, OpenAI-Python
+   * style (`{**body, **extra_body}`) — keys here override identically named fields
+   * above. Use it for OpenAI Responses fields this struct does not model directly,
+   * such as the top-level `reasoning.effort`.
+   *
+   * This is an OpenAI escape hatch, not a cross-provider one. On the chat path the
+   * providers that consume `extra_body` natively (Anthropic, Vertex, Bedrock) claim
+   * it inside their own `transform_request`; here no provider transform runs, so the
+   * merged keys always travel to the wire as literal OpenAI Responses fields.
+   *
+   * A non-object value cannot be merged into the body root and is dropped with a
+   * warning rather than sent.
+   */
+  readonly extraBody?: JsonValue
+  /**
+   * Whether to stream the response.
+   *
+   * Managed by the client layer — do not set directly.
+   */
+  readonly stream?: boolean
 }
 
 /** Request to generate speech audio from text. */
@@ -723,7 +878,7 @@ export interface DecodedDataUrl {
  * provider is used as the fallback. This enables seamless migration between
  * providers by changing only the model name.
  *
- * The provider is stored behind an [`Arc`] so it can be shared cheaply into
+ * The provider is stored behind an `Arc` so it can be shared cheaply into
  * async closures and streaming tasks. Pre-computed auth headers and extra
  * headers are cached at construction to avoid redundant encoding on every request.
  */
@@ -754,9 +909,9 @@ export declare class DefaultClient {
    *
    * Uses exponential backoff with configurable initial interval, maximum interval, and backoff multiplier.
    * Optionally supports a timeout that aborts polling if exceeded.
-   * @throws Returns `BatchWaitError::Failed` if the batch reaches a failure terminal status.
-   * Returns `BatchWaitError::Timeout` if the configured timeout is exceeded.
-   * Returns `BatchWaitError::Client` for underlying client errors.
+   * @throws Returns `BatchWaitError.Failed` if the batch reaches a failure terminal status.
+   * Returns `BatchWaitError.Timeout` if the configured timeout is exceeded.
+   * Returns `BatchWaitError.Client` for underlying client errors.
    */
   waitForBatch(batchId: string, config?: WaitForBatchConfig | undefined | null): Promise<BatchObject>
   createResponse(req?: CreateResponseRequest | undefined | null): Promise<ResponseObject>
@@ -799,12 +954,9 @@ export declare enum EmbeddingFormat {
 }
 
 /** Text or texts to embed. */
-export declare enum EmbeddingInput {
-  /** Single text string. */
-  Single = "Single",
-  /** Multiple text strings (batch embedding). */
-  Multiple = "Multiple",
-}
+export type EmbeddingInput =
+  | string
+  | Array<string>
 
 /** A single embedding vector. */
 export interface EmbeddingObject {
@@ -859,11 +1011,11 @@ export interface EmbeddingResponse {
 export declare enum Enforcement {
   /**
    * Reject requests that would exceed the budget with
-   * [`LiterLlmError::BudgetExceeded`].
+   * `LiterLlmError.BudgetExceeded`.
    */
   Hard = "Hard",
   /**
-   * Allow requests through but emit a `tracing::warn!` when the budget is
+   * Allow requests through but emit a `tracing.warn!` when the budget is
    * exceeded.
    */
   Soft = "Soft",
@@ -943,7 +1095,7 @@ export declare enum FinishReason {
 export interface FunctionCall {
   /** Function name. */
   readonly name: string
-  /** Arguments as a JSON string (parse with serde_json::from_str). */
+  /** Arguments as a JSON string (parse with serde_json.from_str). */
   readonly arguments: string
 }
 
@@ -969,11 +1121,11 @@ export interface FunctionMessage {
  * Abstraction over a health probe strategy.
  *
  * Implementors issue a lightweight probe against `upstream` (typically a
- * provider base URL or named identifier) and report [`HealthStatus`].
+ * provider base URL or named identifier) and report `HealthStatus`.
  */
 export interface HealthChecker {
   /**
-   * Probe `upstream` and return its current [`HealthStatus`].
+   * Probe `upstream` and return its current `HealthStatus`.
    *
    * The parameter is taken by value (`String`) so that implementations can
    * move it into the returned future without a clone, making the
@@ -1018,7 +1170,15 @@ export interface ImagesResponse {
   readonly data?: Array<Image>
 }
 
-/** An image URL reference with optional detail level for processing. */
+/**
+ * An image URL reference with optional detail level for processing.
+ *
+ * No `deny_unknown_fields`: this type is shared with the response side
+ * (see `AssistantPart.OutputImage`) where it is deserialized from
+ * provider output, not just constructed as request input (see #51). A
+ * provider adding a new field to its image-output object must not hard-fail
+ * the whole response.
+ */
 export interface ImageUrl {
   /** URL of the image (data URI or HTTP/HTTPS URL). */
   readonly url?: string
@@ -1048,14 +1208,119 @@ export interface JsonSchemaFormat {
   readonly strict?: boolean
 }
 
+/** Budget enforcement configuration. */
+export interface LlmBudgetConfig {
+  /** Global spend limit in USD. */
+  readonly globalLimit?: number
+  /** Per-model spend limits in USD, keyed by model name. */
+  readonly modelLimits?: Record<string, number>
+  /** Enforcement mode: `"hard"` (reject over-budget requests) or `"soft"` (log only). */
+  readonly enforcement?: string
+}
+
+/** Response cache configuration. */
+export interface LlmCacheConfig {
+  /** Maximum number of cached entries. */
+  readonly maxEntries?: number
+  /** Cache entry time-to-live, in seconds. */
+  readonly ttlSeconds?: number
+  /** Cache backend name (e.g. `"memory"`, or an `opendal` scheme). */
+  readonly backend?: string
+  /** Backend-specific configuration key/value pairs. */
+  readonly backendConfig?: Record<string, string>
+}
+
+/**
+ * Canonical configuration for an LLM client.
+ *
+ * All fields except `model` are optional so that partially-specified
+ * configs (e.g. from environment-driven defaults) round-trip cleanly.
+ * Convert to a runtime client configuration via
+ * `LlmConfig.into_client_builder`.
+ *
+ * `temperature` and `max_tokens` are request-time parameters rather than
+ * client-level settings; they are carried on this struct for callers to
+ * read when building individual requests, and are intentionally **not**
+ * mapped by `LlmConfig.into_client_builder`.
+ *
+ * Implements `Debug` manually (see below) so `api_key` and header values are
+ * redacted rather than printed in full.
+ */
+export interface LlmConfig {
+  /** Model identifier (e.g. `"gpt-4o"`, `"bedrock/anthropic.claude-3-sonnet-20240229-v1:0"`). */
+  readonly model?: string
+  /** API key for authentication. */
+  readonly apiKey?: string
+  /**
+   * Override base URL. When set, all requests go here and provider
+   * auto-detection is skipped.
+   */
+  readonly baseUrl?: string
+  /** Request timeout, in seconds. */
+  readonly timeoutSecs?: number
+  /** Maximum number of retries on 429 / 5xx responses. */
+  readonly maxRetries?: number
+  /** Sampling temperature for requests built from this config. */
+  readonly temperature?: number
+  /** Maximum number of tokens to generate for requests built from this config. */
+  readonly maxTokens?: number
+  /**
+   * Automatically load the API key from the provider's environment variable
+   * when no explicit key is provided (default: `true`).
+   */
+  readonly loadEnv?: boolean
+  /** Extra headers sent on every request. */
+  readonly headers?: Record<string, string>
+  /** Custom provider configurations, in addition to the built-in providers. */
+  readonly providers?: Array<LlmProviderConfig>
+  /** Response cache configuration. */
+  readonly cache?: LlmCacheConfig
+  /** Budget enforcement configuration. */
+  readonly budget?: LlmBudgetConfig
+  /** Per-model rate limiting configuration. */
+  readonly rateLimit?: LlmRateLimitConfig
+  /** Enable per-request cost tracking. */
+  readonly costTracking?: boolean
+  /** Enable OpenTelemetry-compatible tracing spans. */
+  readonly tracing?: boolean
+  /** Cooldown duration after transient errors, in seconds. */
+  readonly cooldownSecs?: number
+  /** Background health check interval, in seconds. */
+  readonly healthCheckSecs?: number
+  /** AWS Bedrock configuration (region, credentials, cross-region routing). */
+  readonly bedrock?: BedrockConfig
+}
+
+/** A custom provider configuration entry. */
+export interface LlmProviderConfig {
+  /** Provider name, used to key model prefix matching. */
+  readonly name?: string
+  /** Base URL for the provider's OpenAI-compatible API. */
+  readonly baseUrl?: string
+  /** Header name used to carry the API key (defaults to `Authorization` when unset). */
+  readonly authHeader?: string
+  /** Model name prefixes routed to this provider (e.g. `["my-provider/"]`). */
+  readonly modelPrefixes?: Array<string>
+}
+
+/** Per-model rate limiting configuration. */
+export interface LlmRateLimitConfig {
+  /** Requests per minute limit. */
+  readonly rpm?: number
+  /** Tokens per minute limit. */
+  readonly tpm?: number
+  /** Rate limit window, in seconds. */
+  readonly windowSeconds?: number
+}
+
 /** A chat message in a conversation. */
 export type Message =
-  | { role: 'system'; 0: SystemMessage }
-  | { role: 'user'; 0: UserMessage }
-  | { role: 'assistant'; 0: AssistantMessage }
-  | { role: 'tool'; 0: ToolMessage }
-  | { role: 'developer'; 0: DeveloperMessage }
-  | { role: 'function'; 0: FunctionMessage }
+  | { role: 'system'; system: SystemMessage }
+  | { role: 'user'; user: UserMessage }
+  | { role: 'assistant'; assistant: AssistantMessage }
+  | { role: 'tool'; tool: ToolMessage }
+  | { role: 'developer'; developer: DeveloperMessage }
+  | { role: 'function'; function: FunctionMessage }
 
 /**
  * Output modality requested from the model.
@@ -1074,11 +1339,11 @@ export declare enum Modality {
 
 /**
  * Public, FFI-friendly snapshot of a model's pricing and capability
- * metadata, projected from [`ModelPricing`].
+ * metadata, projected from `ModelPricing`.
  *
- * Unlike [`ModelPricing`] (which is excluded from binding generation),
+ * Unlike `ModelPricing` (which is excluded from binding generation),
  * `ModelInfo` is an owned plain-data DTO safe to hand across the FFI
- * boundary — see [`model_info`].
+ * boundary — see `model_info`.
  */
 export interface ModelInfo {
   /** Cost in USD per input (prompt) token. */
@@ -1162,7 +1427,7 @@ export interface ModelsListResponse {
 
 /**
  * Public, FFI-friendly snapshot of a single context-window pricing tier,
- * projected from [`PricingTier`].
+ * projected from `PricingTier`.
  */
 export interface ModelTier {
   /**
@@ -1239,12 +1504,9 @@ export interface ModerationCategoryScores {
 }
 
 /** Input to the moderation endpoint — a single string or multiple strings. */
-export declare enum ModerationInput {
-  /** Single text string. */
-  Single = "Single",
-  /** Multiple text strings (batch moderation). */
-  Multiple = "Multiple",
-}
+export type ModerationInput =
+  | string
+  | Array<string>
 
 /** Request to classify content for policy violations. */
 export interface ModerationRequest {
@@ -1332,7 +1594,7 @@ export interface PageDimensions {
 /**
  * Breakdown of tokens used in the prompt portion of a request.
  *
- * `cached_tokens` is included in `Usage::prompt_tokens` — it is *not* an
+ * `cached_tokens` is included in `Usage.prompt_tokens` — it is *not* an
  * additional charge on top of the prompt token count. When pricing supports
  * a `cache_read_input_token_cost`, the cached portion is billed at the
  * discounted rate and the remainder at the regular input rate.
@@ -1355,19 +1617,7 @@ export interface PromptTokensDetails {
  *
  * All flags default to `false` so that newly added providers are safe.
  *
- * Access via the crate-level [`capabilities`] function:
- *
- * ```rust
- * use liter_llm::capabilities;
- *
- * let caps = capabilities("openai");
- * assert!(caps.function_calling);
- * assert!(caps.vision);
- *
- * // Unknown providers return a default-all-false reference.
- * let unknown = capabilities("my-private-model");
- * assert!(!unknown.function_calling);
- * ```
+ * Access via the crate-level `capabilities` function:
  */
 export interface ProviderCapabilities {
   /** The provider accepts image input in chat messages. */
@@ -1390,7 +1640,7 @@ export interface ProviderCapabilities {
  * Static configuration for a single provider entry in providers.json.
  *
  * This struct deliberately does not include capability flags or streaming
- * format, which are accessed via the [`capabilities`] function.
+ * format, which are accessed via the `capabilities` function.
  */
 export interface ProviderConfig {
   /** Provider identifier (matches the entry key in providers.json). */
@@ -1410,7 +1660,7 @@ export interface ProviderConfig {
    *
    * Each entry maps an OpenAI-spec field name (e.g. `"max_completion_tokens"`)
    * to the name this provider expects (e.g. `"max_tokens"`).  Applied
-   * automatically by `ConfigDrivenProvider::transform_request`.
+   * automatically by `ConfigDrivenProvider.transform_request`.
    */
   readonly paramMappings?: Record<string, string>
 }
@@ -1430,9 +1680,11 @@ export declare enum ReasoningEffort {
   Low = "low",
   Medium = "medium",
   High = "high",
+  Minimal = "minimal",
+  Max = "max",
 }
 
-/** Result of a [`refresh_catalog`] call. */
+/** Result of a `refresh_catalog` call. */
 export declare enum RefreshOutcome {
   /**
    * `config.enabled` was `false`; no network, filesystem, or overlay
@@ -1453,12 +1705,9 @@ export declare enum RefreshOutcome {
 }
 
 /** A document to be reranked — either a plain string or an object with a text field. */
-export declare enum RerankDocument {
-  /** Plain text document content. */
-  Text = "Text",
-  /** Document with explicit text field (may include metadata). */
-  Object = "Object",
-}
+export type RerankDocument =
+  | string
+  | { text: string }
 
 /** Request to rerank documents by relevance to a query. */
 export interface RerankRequest {
@@ -1627,12 +1876,9 @@ export interface SpecificToolChoice {
 }
 
 /** Stop sequence(s) that cause the model to stop generating. */
-export declare enum StopSequence {
-  /** Single stop sequence. */
-  Single = "Single",
-  /** Multiple stop sequences. */
-  Multiple = "Multiple",
-}
+export type StopSequence =
+  | string
+  | Array<string>
 
 /** A streaming choice with incremental delta. */
 export interface StreamChoice {
@@ -1666,7 +1912,7 @@ export interface StreamDelta {
  * Most providers use standard Server-Sent Events (SSE).  AWS Bedrock uses
  * a proprietary binary EventStream framing.
  *
- * Deserialized from the `streaming_format` JSON field via [`serde`].
+ * Deserialized from the `streaming_format` JSON field via `serde`.
  */
 export declare enum StreamFormat {
   /** Standard Server-Sent Events (text/event-stream). */
@@ -1707,7 +1953,7 @@ export interface SystemMessage {
    * Instructions or context that apply throughout the conversation.
    *
    * Accepts either a plain text string or an array of content parts,
-   * mirroring [`UserContent`] so that `Message::system_with_parts` works.
+   * mirroring `UserContent` so that `Message.system_with_parts` works.
    */
   readonly content?: UserContent
   /** Optional name for the system message source. */
@@ -1725,12 +1971,9 @@ export interface ToolCall {
 }
 
 /** Tool usage mode or a specific tool to call. */
-export declare enum ToolChoice {
-  /** Predefined mode: auto, required, or none. */
-  Mode = "Mode",
-  /** Force a specific tool to be called. */
-  Specific = "Specific",
-}
+export type ToolChoice =
+  | ToolChoiceMode
+  | SpecificToolChoice
 
 /** Tool choice mode. */
 export declare enum ToolChoiceMode {
@@ -1744,8 +1987,15 @@ export declare enum ToolChoiceMode {
 
 /** Tool execution result returned to the model. */
 export interface ToolMessage {
-  /** Result of the tool execution. */
-  readonly content?: string
+  /**
+   * Result of the tool execution as plain text or an array of content parts
+   * (text, images, documents, audio), mirroring `UserMessage.content`.
+   *
+   * `#[serde(untagged)]` on `UserContent` means a bare JSON string still
+   * deserialises into `Text`, so tool results persisted before this field
+   * carried structured content continue to round-trip.
+   */
+  readonly content?: UserContent
   /** ID of the tool call this result responds to. */
   readonly toolCallId?: string
   /** Optional tool/function name. */
@@ -1804,12 +2054,9 @@ export interface Usage {
 }
 
 /** User message content as either plain text or a list of multimodal parts. */
-export declare enum UserContent {
-  /** Plain text content. */
-  Text = "Text",
-  /** Array of content parts (text, images, documents, audio). */
-  Parts = "Parts",
-}
+export type UserContent =
+  | string
+  | Array<ContentPart>
 
 /** User message in the conversation. */
 export interface UserMessage {
@@ -1841,30 +2088,39 @@ export interface WaitForBatchConfig {
  *
  * Returns `None` if the model is not present in the active pricing
  * registry. Uses the same exact-match-then-prefix-fallback resolution as
- * [`model_pricing`]; unlike `model_pricing`, the result is an owned
- * [`ModelInfo`] value safe to hand across the FFI boundary.
+ * `model_pricing`; unlike `model_pricing`, the result is an owned
+ * `ModelInfo` value safe to hand across the FFI boundary.
  *
  * When a runtime catalog refresh has succeeded, this reflects the refreshed
  * (overlay) catalog; otherwise it reflects the embedded catalog. See
- * [`model_pricing`] for the embedded-only alternative.
+ * `model_pricing` for the embedded-only alternative.
  */
 export declare function modelInfo(model: string): ModelInfo | null;
 
+/**
+ * Record the estimated USD cost of a completion.
+ *
+ * Call from `CostTrackingService` once a
+ * completion's cost has been computed. Emits `gen_ai.client.cost.usd`.
+ * If the meter has not been initialized, this call is a no-op.
+ */
+export declare function recordCostUsd(system: string, model: string, operation: string, costUsd: number): void;
+
 /**
  * Refresh the runtime catalog overlay per `config`.
  *
- * - `config.enabled == false`: returns `Ok(`[`RefreshOutcome::Disabled`]`)`
+ * - `config.enabled == false`: returns `Ok(``RefreshOutcome.Disabled``)`
  *   immediately. No network, filesystem, or overlay activity.
  * - A fresh on-disk cache (age < `config.ttl_seconds`) exists at the
  *   resolved cache path (`config.cache_path`, or a default under
- *   `std::env::temp_dir()`): read + flatten it and install the overlay,
- *   returning `Ok(`[`RefreshOutcome::FromCache`]`)`. No network request is
+ *   `std.env.temp_dir()`): read + flatten it and install the overlay,
+ *   returning `Ok(``RefreshOutcome.FromCache``)`. No network request is
  *   made.
  * - Otherwise: validate `config.source_url` uses `https`
- *   ([`CatalogRefreshError::InsecureUrl`] otherwise), fetch it, flatten it,
+ *   (`CatalogRefreshError.InsecureUrl` otherwise), fetch it, flatten it,
  *   install the overlay, best-effort write the raw JSON to the cache path
  *   (a cache write failure does not fail the refresh), and return
- *   `Ok(`[`RefreshOutcome::Fetched`]`)`.
+ *   `Ok(``RefreshOutcome.Fetched``)`.
  *
  * On any error return, the overlay is left untouched: the previously
  * active registry (a prior successful overlay, or the embedded catalog if
@@ -1900,6 +2156,7 @@ export declare class ChatStreamIterator {
 }
 
 export declare class LiterLlmErrorInfo {
+  code(): number
   statusCode(): number
   isTransient(): boolean
   errorType(): string