@xberg-io/liter-llm 1.16.0 → 1.18.0

package/index.d.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by alef — DO NOT EDIT.
-// alef:hash:938b8ffd93c3e30d74875f875188c728addee9d4b80a97a7ac22716b3154c7c5
+// alef:hash:5b669b2bae32edc478385d1c565e973c2b54c440018dc4506eccb2bec6078845
 // 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
@@ -380,6 +390,9 @@ export declare enum BatchStatus {
  * 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"`). */
@@ -423,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.
@@ -431,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
   /**
@@ -448,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
 }
@@ -482,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
@@ -530,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.
@@ -572,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 {
   /**
@@ -658,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
@@ -674,6 +787,21 @@ 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.
    *
@@ -750,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.
  */
@@ -781,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>
@@ -817,6 +945,12 @@ export interface DocumentContent {
   readonly mediaType?: string
 }
 
+/** A content part in a multimodal embedding input. */
+export type EmbeddingContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; imageUrl: ImageUrl }
+  | { type: 'image_base64'; imageBase64: string }
+
 /** The format in which the embedding vectors are returned. */
 export declare enum EmbeddingFormat {
   /** 32-bit floating-point numbers (default). */
@@ -825,13 +959,11 @@ export declare enum EmbeddingFormat {
   Base64 = "base64",
 }
 
-/** Text or texts to embed. */
-export declare enum EmbeddingInput {
-  /** Single text string. */
-  Single = "Single",
-  /** Multiple text strings (batch embedding). */
-  Multiple = "Multiple",
-}
+/** Text, texts, or multimodal content to embed. */
+export type EmbeddingInput =
+  | string
+  | Array<string>
+  | Array<EmbeddingContentPart>
 
 /** A single embedding vector. */
 export interface EmbeddingObject {
@@ -857,7 +989,7 @@ export interface EmbeddingObject {
 export interface EmbeddingRequest {
   /** Model ID (e.g., `"text-embedding-3-small"`). */
   readonly model?: string
-  /** Text or texts to embed. */
+  /** Text, texts, or multimodal content to embed. */
   readonly input?: EmbeddingInput
   /** Output format: float (native) or base64. */
   readonly encodingFormat?: EmbeddingFormat
@@ -886,11 +1018,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",
@@ -970,7 +1102,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
 }
 
@@ -996,11 +1128,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
@@ -1045,7 +1177,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
@@ -1053,6 +1193,12 @@ export interface ImageUrl {
   readonly detail?: ImageDetail
 }
 
+/** Configuration for the global per-client in-flight request limit. */
+export interface InFlightLimitConfig {
+  /** Maximum simultaneously outstanding provider requests. `None` means unlimited. */
+  readonly maxInFlight?: number
+}
+
 /** An intent prototype: `(intent_name, prototype_embedding, target_model_id)`. */
 export interface IntentPrototype {
   /** Human-readable name for the intent (used in logs/metrics). */
@@ -1103,12 +1249,15 @@ export interface LlmCacheConfig {
  * 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`].
+ * `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`].
+ * 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"`). */
@@ -1143,6 +1292,8 @@ export interface LlmConfig {
   readonly budget?: LlmBudgetConfig
   /** Per-model rate limiting configuration. */
   readonly rateLimit?: LlmRateLimitConfig
+  /** Global per-client in-flight provider request limit. */
+  readonly inFlightLimit?: LlmInFlightLimitConfig
   /** Enable per-request cost tracking. */
   readonly costTracking?: boolean
   /** Enable OpenTelemetry-compatible tracing spans. */
@@ -1155,6 +1306,12 @@ export interface LlmConfig {
   readonly bedrock?: BedrockConfig
 }
 
+/** Global per-client in-flight provider request limit. */
+export interface LlmInFlightLimitConfig {
+  /** Maximum simultaneously outstanding provider requests. `None` means unlimited. */
+  readonly maxInFlight?: number
+}
+
 /** A custom provider configuration entry. */
 export interface LlmProviderConfig {
   /** Provider name, used to key model prefix matching. */
@@ -1179,12 +1336,12 @@ export interface LlmRateLimitConfig {
 
 /** 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.
@@ -1203,11 +1360,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. */
@@ -1291,7 +1448,7 @@ export interface ModelsListResponse {
 
 /**
  * Public, FFI-friendly snapshot of a single context-window pricing tier,
- * projected from [`PricingTier`].
+ * projected from `PricingTier`.
  */
 export interface ModelTier {
   /**
@@ -1368,12 +1525,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 {
@@ -1461,7 +1615,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.
@@ -1484,19 +1638,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. */
@@ -1519,7 +1661,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). */
@@ -1539,7 +1681,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>
 }
@@ -1563,7 +1705,7 @@ export declare enum ReasoningEffort {
   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
@@ -1584,12 +1726,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 {
@@ -1758,12 +1897,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 {
@@ -1797,7 +1933,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). */
@@ -1838,7 +1974,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. */
@@ -1856,12 +1992,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 {
@@ -1877,9 +2010,9 @@ export declare enum ToolChoiceMode {
 export interface ToolMessage {
   /**
    * Result of the tool execution as plain text or an array of content parts
-   * (text, images, documents, audio), mirroring [`UserMessage::content`].
+   * (text, images, documents, audio), mirroring `UserMessage.content`.
    *
-   * `#[serde(untagged)]` on [`UserContent`] means a bare JSON string still
+   * `#[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.
    */
@@ -1942,12 +2075,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 {
@@ -1979,30 +2109,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
@@ -2038,6 +2177,7 @@ export declare class ChatStreamIterator {
 }
 
 export declare class LiterLlmErrorInfo {
+  code(): number
   statusCode(): number
   isTransient(): boolean
   errorType(): string