@kreuzberg/liter-llm-node 1.6.0 → 1.6.2

package/index.d.ts

@@ -1,139 +1,215 @@
-/* auto-generated by NAPI-RS */
+// This file is auto-generated by alef — DO NOT EDIT.
+// alef:hash:797e09398ae0b95dd0e3de94d7374eedafcd20d08532c7cf378cbcd09e3083a7
+// To regenerate: alef generate
+// To verify freshness: alef verify --exit-code
 /* eslint-disable */
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
 /**
- * This type implements JavaScript's async iterable protocol.
- * It can be used with `for await...of` loops.
+ * Return all provider configs from the registry.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+ * 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`].
  */
-export declare class ChatStreamIterator {}
+export declare function allProviders(): Array<ProviderConfig>;
 
 /**
- * Default client implementation backed by `reqwest`.
+ * Return the capability flags for a named provider.
  *
- * Sends requests to 140+ LLM providers with automatic provider detection
- * and per-request routing. The provider is resolved at construction time
- * from `model_hint` (or defaults to OpenAI), but individual requests can
- * override the provider via model name prefix (e.g. `"anthropic/claude-3-5-sonnet"`
- * routes to Anthropic regardless of construction-time setting).
+ * Performs an O(n) linear scan over the embedded registry (143 entries).
+ * Returns an owned value so that bindings can box/copy it across the FFI
+ * boundary without dealing with lifetimes. `ProviderCapabilities` is `Copy`,
+ * so this is a cheap memcpy of seven `bool` fields.
  *
- * When the model prefix does not match any known provider, the construction-time
- * provider is used as the fallback. This enables seamless migration between
- * providers by changing only the model name.
+ * For unknown `provider_name` values the function returns an all-`false`
+ * sentinel so callers never need to handle `Option`.
+ */
+export declare function capabilities(providerName: string): ProviderCapabilities;
+
+/**
+ * Assert that `current_len + incoming` does not exceed `limit`.
  *
- * 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.
+ * 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.
  */
-export declare class DefaultClient {
-  chat(req: ChatCompletionRequest): Promise<ChatCompletionResponse>;
-  chatStream(req: ChatCompletionRequest): Promise<ChatStreamIterator>;
-  embed(req: EmbeddingRequest): Promise<EmbeddingResponse>;
-  listModels(): Promise<ModelsListResponse>;
-  imageGenerate(req: CreateImageRequest): Promise<ImagesResponse>;
-  speech(req: CreateSpeechRequest): Promise<Buffer>;
-  transcribe(req: CreateTranscriptionRequest): Promise<TranscriptionResponse>;
-  moderate(req: ModerationRequest): Promise<ModerationResponse>;
-  rerank(req: RerankRequest): Promise<RerankResponse>;
-  search(req: SearchRequest): Promise<SearchResponse>;
-  ocr(req: OcrRequest): Promise<OcrResponse>;
-  createFile(req: CreateFileRequest): Promise<FileObject>;
-  retrieveFile(fileId: string): Promise<FileObject>;
-  deleteFile(fileId: string): Promise<DeleteResponse>;
-  listFiles(query?: FileListQuery | undefined | null): Promise<FileListResponse>;
-  fileContent(fileId: string): Promise<Buffer>;
-  createBatch(req: CreateBatchRequest): Promise<BatchObject>;
-  retrieveBatch(batchId: string): Promise<BatchObject>;
-  listBatches(query?: BatchListQuery | undefined | null): Promise<BatchListResponse>;
-  cancelBatch(batchId: string): Promise<BatchObject>;
-  fetchBatchForPolling(batchId: string): Promise<BatchObject>;
-  /**
-   * Poll a batch until it reaches a terminal status (Completed, Failed, Expired, Cancelled).
-   *
-   * Uses exponential backoff with configurable initial interval, maximum interval, and backoff multiplier.
-   * Optionally supports a timeout that aborts polling if exceeded.
-   *
-   * # Errors
-   *
-   * 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.
-   *
-   * # Example
-   */
-  waitForBatch(batchId: string, config: WaitForBatchConfig): Promise<BatchObject>;
-  createResponse(req: CreateResponseRequest): Promise<ResponseObject>;
-  retrieveResponse(responseId: string): Promise<ResponseObject>;
-  cancelResponse(responseId: string): Promise<ResponseObject>;
-}
-export type JsDefaultClient = DefaultClient;
+export declare function checkBound(
+  context: string,
+  currentLen: number,
+  incoming: number,
+  limit: number,
+): void;
 
-export declare class JsLiterLlmErrorInfo {
-  statusCode: number;
-  isTransient: boolean;
-  errorType: string;
-  /** HTTP status code for this error (0 means no associated status). */
-  statusCode(): number;
-  /** Returns `true` if the error is transient and a retry may succeed. */
-  isTransient(): boolean;
-  /** Machine-readable error category string for matching and logging. */
-  errorType(): string;
-}
+/**
+ * Remove all guardrails from the global registry.
+ *
+ * Primarily useful in tests to reset state between test cases.
+ */
+export declare function clear(): void;
 
 /**
- * The value broadcast from a singleflight leader to all followers.
+ * Calculate the estimated cost of a completion given a model name and token
+ * counts.
  *
- * `Arc<LiterLlmError>` is used because `LiterLlmError` is not `Clone` and
- * broadcast channels require `T: Clone`.  The `Arc` adds only a reference-count
- * bump per follower, which is negligible under the burst loads this layer targets.
+ * Returns `None` if the model is not present in the embedded pricing registry.
+ * Returns `Some(cost_usd)` otherwise, where the value is in US dollars.
+ *
+ * When an exact model name match is not found, progressively shorter prefixes
+ * are tried by stripping from the last `-` or `.` separator.  For example,
+ * `gpt-4-0613` will match `gpt-4` if no `gpt-4-0613` entry exists.
  */
-export declare class SingleflightResult {}
-export type JsSingleflightResult = SingleflightResult;
+export declare function completionCost(
+  model: string,
+  promptTokens: number,
+  completionTokens: number,
+): number | null;
 
 /**
- * Return all provider configs from the registry.
+ * Calculate the estimated cost of a completion, accounting for cached
+ * (cache-hit) prompt tokens billed at the provider's discounted rate.
  *
- * 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`.
+ * `cached_tokens` is the count of prompt tokens served from the provider's
+ * prompt cache. It must be `<= prompt_tokens` (cached tokens are a subset of
+ * the prompt). The non-cached portion is billed at `input_cost_per_token`
+ * and the cached portion at `cache_read_input_token_cost` when the model
+ * has cache pricing; otherwise the entire prompt is billed at the regular
+ * input rate.
+ *
+ * Returns `None` if the model is not present in the embedded pricing
+ * registry, mirroring [`completion_cost`].
  */
-export declare function allProviders(): Array<ProviderConfig>;
+export declare function completionCostWithCache(
+  model: string,
+  promptTokens: number,
+  cachedTokens: number,
+  completionTokens: number,
+): number | null;
+
+/**
+ * Return the set of complex provider names.
+ *
+ * Complex providers require custom auth/routing logic beyond simple bearer
+ * tokens (e.g. AWS Bedrock SigV4, Vertex AI OAuth2).
+ *
+ * The returned reference points into the static registry — no allocation.
+ */
+export declare function complexProviderNames(): Array<string>;
+
+/**
+ * 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
+ * if tokenization fails for any message.
+ */
+export declare function countRequestTokens(
+  model: string,
+  req?: ChatCompletionRequest | undefined | null,
+): number;
+
+/**
+ * Count tokens in a text string using the tokenizer for the given model.
+ *
+ * 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
+ * (e.g. network failure on first use) or if tokenization itself fails.
+ */
+export declare function countTokens(model: string, text: string): number;
+
+/**
+ * Create a new LLM client with simple scalar configuration.
+ *
+ * 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
+ * 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;
+
+/**
+ * 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
+ * contains unknown fields.
+ */
+export declare function createClientFromJson(json: string): DefaultClient;
+
+/**
+ * Install the `ring` crypto provider as the rustls process default, idempotently.
+ *
+ * rustls 0.23+ removed the implicit default provider. This function installs
+ * `ring` once per process. Subsequent calls are no-ops. Calling it from a
+ * downstream Rust app that has already installed `aws-lc-rs` is safe — the
+ * `Err` from `install_default()` is silently ignored.
+ *
+ * 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.
+ *
+ * WASM builds are exempt — the WASM target uses the browser/Node.js fetch
+ * API instead of rustls, so no crypto provider is needed.
+ *
+ * Windows builds use native-tls (SChannel) via reqwest, so rustls is not
+ * present and no crypto provider installation is needed.
+ */
+export declare function ensureCryptoProvider(): void;
 
 /** Assistant's response to a user message. */
 export interface AssistantMessage {
   /** The assistant's text response. Absent if tool calls are returned instead. */
-  content?: string;
+  readonly content?: string;
   /** Optional name for the assistant. */
-  name?: string;
+  readonly name?: string;
   /** Tool calls the model wants to execute, if any. */
-  toolCalls?: Array<JsToolCall>;
+  readonly toolCalls?: Array<ToolCall>;
   /** Refusal reason, if the model declined to respond per safety policies. */
-  refusal?: string;
+  readonly refusal?: string;
   /** Deprecated legacy function_call field; retained for API compatibility. */
-  functionCall?: JsFunctionCall;
+  readonly functionCall?: FunctionCall;
 }
 
 /** Audio content part for speech-capable models. */
 export interface AudioContent {
   /** Base64-encoded audio data. */
-  data?: string;
+  readonly data?: string;
   /** Audio format (e.g., "wav", "mp3", "ogg"). */
-  format?: string;
+  readonly format?: string;
 }
 
 /** Auth configuration block. */
 export interface AuthConfig {
   /** Auth scheme classification. */
-  type: JsAuthType;
+  readonly authType: AuthType;
   /**
    * Name of the environment variable that holds the API key (e.g. `"OPENAI_API_KEY"`).
    * Holds the variable name, never the secret value.
    */
-  envVar?: string;
+  readonly envVar?: string;
 }
 
 /** How the API key is sent in the HTTP request. */
-export declare const enum AuthHeaderFormat {
+export declare enum AuthHeaderFormat {
   /** Bearer token: `Authorization: Bearer <key>` */
   Bearer = "Bearer",
   /** Custom header: e.g., `X-Api-Key: <key>` */
@@ -143,7 +219,7 @@ export declare const enum AuthHeaderFormat {
 }
 
 /** Auth scheme used by a provider. */
-export declare const enum AuthType {
+export declare enum AuthType {
   /** Standard `Authorization: Bearer <key>` header. */
   Bearer = "bearer",
   /** `x-api-key: <key>` header (also handles `"header"` and `"x-api-key"` aliases). */
@@ -157,69 +233,69 @@ export declare const enum AuthType {
 /** Query parameters for listing batches. */
 export interface BatchListQuery {
   /** Maximum number of results to return. Defaults to 20. */
-  limit?: number;
+  readonly limit?: number;
   /** Pagination cursor: return results after this batch ID. */
-  after?: string;
+  readonly after?: string;
 }
 
 /** Response from listing batches. */
 export interface BatchListResponse {
   /** Object type (always `"list"`). */
-  object?: string;
+  readonly object?: string;
   /** List of batch objects. */
-  data?: Array<BatchObject>;
+  readonly data?: Array<BatchObject>;
   /** Whether more results are available. */
-  hasMore?: boolean;
+  readonly hasMore?: boolean;
   /** First batch ID in the result set (for pagination). */
-  firstId?: string;
+  readonly firstId?: string;
   /** Last batch ID in the result set (for pagination). */
-  lastId?: string;
+  readonly lastId?: string;
 }
 
 /** A batch job object. */
 export interface BatchObject {
   /** Unique batch ID. */
-  id?: string;
+  readonly id?: string;
   /** Object type (always `"batch"`). */
-  object?: string;
+  readonly object?: string;
   /** API endpoint (e.g., `"/v1/chat/completions"`). */
-  endpoint?: string;
+  readonly endpoint?: string;
   /** ID of the input file. */
-  inputFileId?: string;
+  readonly inputFileId?: string;
   /** Completion window (e.g., `"24h"`). */
-  completionWindow?: string;
+  readonly completionWindow?: string;
   /** Current job status. */
-  status?: JsBatchStatus;
+  readonly status?: BatchStatus;
   /** ID of the output file (present when completed). */
-  outputFileId?: string;
+  readonly outputFileId?: string;
   /** ID of the error file (present if some requests failed). */
-  errorFileId?: string;
+  readonly errorFileId?: string;
   /** Unix timestamp of batch creation. */
-  createdAt?: number;
+  readonly createdAt?: number;
   /** Unix timestamp of completion (if completed). */
-  completedAt?: number;
+  readonly completedAt?: number;
   /** Unix timestamp of failure (if failed). */
-  failedAt?: number;
+  readonly failedAt?: number;
   /** Unix timestamp of expiration (if expired). */
-  expiredAt?: number;
+  readonly expiredAt?: number;
   /** Request processing counts. */
-  requestCounts?: JsBatchRequestCounts;
+  readonly requestCounts?: BatchRequestCounts;
   /** Metadata attached to the batch. */
-  metadata?: any;
+  readonly metadata?: JsonValue;
 }
 
 /** Request processing counts for a batch. */
 export interface BatchRequestCounts {
   /** Total requests in the batch. */
-  total?: number;
+  readonly total?: number;
   /** Completed requests. */
-  completed?: number;
+  readonly completed?: number;
   /** Failed requests. */
-  failed?: number;
+  readonly failed?: number;
 }
 
 /** Status of a batch job. */
-export declare const enum BatchStatus {
+export declare enum BatchStatus {
   /** Validating the input file. */
   Validating = "validating",
   /** Job failed. */
@@ -241,191 +317,172 @@ export declare const enum BatchStatus {
 /** Configuration for budget enforcement. */
 export interface BudgetConfig {
   /** Maximum total spend across all models, in USD.  `None` means unlimited. */
-  globalLimit?: number;
+  readonly globalLimit?: number;
   /**
    * Per-model spending limits in USD.  Models not listed here are only
    * constrained by `global_limit`.
    */
-  modelLimits?: Record<string, number>;
+  readonly modelLimits?: Record<string, number>;
   /** Whether to reject requests or merely warn when a limit is exceeded. */
-  enforcement?: JsEnforcement;
+  readonly enforcement?: Enforcement;
 }
 
-export declare function budgetConfigDefault(): BudgetConfig;
-
 /** Storage backend for the response cache. */
-export interface CacheBackend {
-  type: string;
-  scheme?: string;
-  config?: Record<string, string>;
-}
+export type CacheBackend =
+  | { type: "memory" }
+  | { type: "open_dal"; scheme: string; config: Record<string, string> };
 
 /** Configuration for the response cache. */
 export interface CacheConfig {
   /** Maximum number of cached entries. */
-  maxEntries?: number;
+  readonly maxEntries?: number;
   /** Time-to-live for each cached entry. */
-  ttl?: number;
+  readonly ttl?: number;
   /** Storage backend to use. */
-  backend?: JsCacheBackend;
+  readonly backend?: CacheBackend;
 }
 
-export declare function cacheConfigDefault(): CacheConfig;
-
-/**
- * Return the capability flags for a named provider.
- *
- * Performs an O(n) linear scan over the embedded registry (142 entries).
- * Returns an owned value so that bindings can box/copy it across the FFI
- * boundary without dealing with lifetimes. `ProviderCapabilities` is `Copy`,
- * so this is a cheap memcpy of seven `bool` fields.
- *
- * For unknown `provider_name` values the function returns an all-`false`
- * sentinel so callers never need to handle `Option`.
- */
-export declare function capabilities(providerName: string): ProviderCapabilities;
-
 /** A streamed chunk of a chat completion response. */
 export interface ChatCompletionChunk {
   /** Unique identifier for this stream. */
-  id?: string;
+  readonly id?: string;
   /**
    * Always `"chat.completion.chunk"` from OpenAI-compatible APIs.  Stored
    * as a plain `String` so non-standard provider values do not fail parsing.
    */
-  object?: string;
+  readonly object?: string;
   /** Unix timestamp of chunk creation. */
-  created?: number;
+  readonly created?: number;
   /** Model used to generate the chunk. */
-  model?: string;
+  readonly model?: string;
   /** Streaming choices (delta updates). */
-  choices?: Array<JsStreamChoice>;
+  readonly choices?: Array<StreamChoice>;
   /** Token usage (typically only in the final chunk). */
-  usage?: Usage;
+  readonly usage?: Usage;
   /** Fingerprint of the system configuration (OpenAI-specific). */
-  systemFingerprint?: string;
+  readonly systemFingerprint?: string;
   /** Service tier used (OpenAI-specific). */
-  serviceTier?: string;
+  readonly serviceTier?: string;
 }
 
 /** Chat completion request (compatible with OpenAI and similar APIs). */
 export interface ChatCompletionRequest {
   /** Model ID (e.g., `"gpt-4o-mini"`, `"claude-3-5-sonnet"`). */
-  model?: string;
+  readonly model?: string;
   /** Conversation history from oldest to newest. */
-  messages?: Array<JsMessage>;
+  readonly messages?: Array<Message>;
   /** Sampling temperature in `[0.0, 2.0]`. Higher increases randomness. Defaults to 1.0. */
-  temperature?: number;
+  readonly temperature?: number;
   /** Nucleus sampling parameter in `[0.0, 1.0]`. Lower is more focused. */
-  topP?: number;
+  readonly topP?: number;
   /** Number of chat completions to generate. Defaults to 1. */
-  n?: number;
+  readonly n?: number;
   /**
    * Whether to stream the response.
    *
    * Managed by the client layer — do not set directly.
    */
-  stream?: boolean;
+  readonly stream?: boolean;
   /** Stop sequence(s) that halt token generation. */
-  stop?: JsStopSequence;
+  readonly stop?: StopSequence;
   /** Max output tokens. Different from max_completion_tokens in some providers. */
-  maxTokens?: number;
+  readonly maxTokens?: number;
   /** Presence penalty in `[-2.0, 2.0]`. Positive discourages repeated topics. */
-  presencePenalty?: number;
+  readonly presencePenalty?: number;
   /** Frequency penalty in `[-2.0, 2.0]`. Positive discourages repeated tokens. */
-  frequencyPenalty?: number;
+  readonly frequencyPenalty?: number;
   /**
    * Token bias map.  Uses `BTreeMap` (sorted keys) for deterministic
    * serialization order — important when hashing or signing requests.
    */
-  logitBias?: Record<string, number>;
+  readonly logitBias?: Record<string, number>;
   /** User identifier for request tracking and abuse detection. */
-  user?: string;
+  readonly user?: string;
   /** Tools the model can invoke. */
-  tools?: Array<ChatCompletionTool>;
+  readonly tools?: Array<ChatCompletionTool>;
   /** Tool usage mode (auto, required, none, or specific tool). */
-  toolChoice?: JsToolChoice;
+  readonly toolChoice?: ToolChoice;
   /** Whether the model can call multiple tools in parallel. Defaults to true. */
-  parallelToolCalls?: boolean;
+  readonly parallelToolCalls?: boolean;
   /** Output format constraint (text, JSON, JSON schema). */
-  responseFormat?: JsResponseFormat;
+  readonly responseFormat?: ResponseFormat;
   /** Streaming options (e.g., include_usage). */
-  streamOptions?: JsStreamOptions;
+  readonly streamOptions?: StreamOptions;
   /** Random seed for reproducible outputs. Provider support varies. */
-  seed?: number;
+  readonly seed?: number;
   /** Reasoning effort level (low, medium, high) for extended-thinking models. */
-  reasoningEffort?: JsReasoningEffort;
+  readonly reasoningEffort?: ReasoningEffort;
   /**
    * Provider-specific extra parameters merged into the request body.
    * Use for guardrails, safety settings, grounding config, etc.
    */
-  extraBody?: any;
+  readonly extraBody?: JsonValue;
 }
 
 /** Chat completion response from the API. */
 export interface ChatCompletionResponse {
   /** Unique identifier for this response. */
-  id?: string;
+  readonly id?: string;
   /**
    * Always `"chat.completion"` from OpenAI-compatible APIs.  Stored as a
    * plain `String` so non-standard provider values do not break deserialization.
    */
-  object?: string;
+  readonly object?: string;
   /** Unix timestamp of response creation. */
-  created?: number;
+  readonly created?: number;
   /** Model used to generate the response. */
-  model?: string;
+  readonly model?: string;
   /** List of completion choices. */
-  choices?: Array<JsChoice>;
+  readonly choices?: Array<Choice>;
   /** Token usage statistics. */
-  usage?: Usage;
+  readonly usage?: Usage;
   /** Fingerprint of the system configuration (OpenAI-specific). */
-  systemFingerprint?: string;
+  readonly systemFingerprint?: string;
   /** Service tier used (OpenAI-specific). */
-  serviceTier?: string;
+  readonly serviceTier?: string;
 }
 
 /** A tool the model can invoke (currently, all tools are functions). */
 export interface ChatCompletionTool {
   /** Tool type (always "function" in OpenAI spec). */
-  type: JsToolType;
+  readonly toolType: ToolType;
   /** Function definition with name, description, and JSON schema parameters. */
-  function: JsFunctionDefinition;
+  readonly function: FunctionDefinition;
 }
 
-export declare function chatStream(
-  engine: DefaultClient,
-  model: string,
-): Promise<ChatStreamIterator>;
-
-/**
- * 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.
- *
- * # Example
- */
-export declare function checkBound(
-  context: string,
-  currentLen: number,
-  incoming: number,
-  limit: number,
-): void;
-
 /** A single completion choice. */
 export interface Choice {
   /** Index of this choice in the choices array. */
-  index?: number;
+  readonly index?: number;
   /** The assistant's message response. */
-  message?: AssistantMessage;
+  readonly message?: AssistantMessage;
   /** Why the model stopped generating (stop, length, tool_calls, content_filter, etc.). */
-  finishReason?: JsFinishReason;
+  readonly finishReason?: FinishReason;
+}
+
+/**
+ * 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 implementations can be stored in a
+ * `Vec<Box<dyn ChunkMiddleware>>` inside [`StreamPipeline`].
+ */
+export interface ChunkMiddleware {
+  /**
+   * Process a single chunk.
+   *
+   * - `Ok(Some(chunk))` — emit (possibly transformed) chunk.
+   * - `Ok(None)` — drop this chunk silently.
+   * - `Err(e)` — propagate as a stream error.
+   */
+  process(chunk?: ChatCompletionChunk | undefined | null): string;
 }
 
 /** Observable state of a circuit breaker. */
-export declare const enum CircuitState {
+export declare enum CircuitState {
   /** Requests flow through normally. */
   Closed = "Closed",
   /** All requests are rejected; the circuit is waiting for the backoff to elapse. */
@@ -434,301 +491,241 @@ export declare const enum CircuitState {
   HalfOpen = "HalfOpen",
 }
 
-/**
- * Remove all guardrails from the global registry.
- *
- * Primarily useful in tests to reset state between test cases.
- *
- * # Panics
- *
- * Panics if the global registry lock is poisoned.
- */
-export declare function clear(): void;
-
-/**
- * Calculate the estimated cost of a completion given a model name and token
- * counts.
- *
- * Returns `None` if the model is not present in the embedded pricing registry.
- * Returns `Some(cost_usd)` otherwise, where the value is in US dollars.
- *
- * When an exact model name match is not found, progressively shorter prefixes
- * are tried by stripping from the last `-` or `.` separator.  For example,
- * `gpt-4-0613` will match `gpt-4` if no `gpt-4-0613` entry exists.
- *
- * # Example
- */
-export declare function completionCost(
-  model: string,
-  promptTokens: number,
-  completionTokens: number,
-): number | null;
-
-/**
- * Calculate the estimated cost of a completion, accounting for cached
- * (cache-hit) prompt tokens billed at the provider's discounted rate.
- *
- * `cached_tokens` is the count of prompt tokens served from the provider's
- * prompt cache. It must be `<= prompt_tokens` (cached tokens are a subset of
- * the prompt). The non-cached portion is billed at `input_cost_per_token`
- * and the cached portion at `cache_read_input_token_cost` when the model
- * has cache pricing; otherwise the entire prompt is billed at the regular
- * input rate.
- *
- * Returns `None` if the model is not present in the embedded pricing
- * registry, mirroring `completion_cost`.
- */
-export declare function completionCostWithCache(
-  model: string,
-  promptTokens: number,
-  cachedTokens: number,
-  completionTokens: number,
-): number | null;
-
-/**
- * Return the set of complex provider names.
- *
- * Complex providers require custom auth/routing logic beyond simple bearer
- * tokens (e.g. AWS Bedrock SigV4, Vertex AI OAuth2).
- *
- * The returned reference points into the static registry — no allocation.
- */
-export declare function complexProviderNames(): Array<string>;
-
 /** A single content part in a user message — text, image, document, or audio. */
-export interface ContentPart {
-  type: string;
-  text?: string;
-  imageUrl?: ImageUrl;
-  document?: DocumentContent;
-  inputAudio?: AudioContent;
-}
-
-/**
- * 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.
- *
- * # Errors
- *
- * 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;
-
-/**
- * Count tokens in a text string using the tokenizer for the given model.
- *
- * 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.
- *
- * # Errors
- *
- * 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;
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; imageUrl: ImageUrl }
+  | { type: "document"; document: DocumentContent }
+  | { type: "input_audio"; inputAudio: AudioContent };
 
 /** Request to create a batch job. */
 export interface CreateBatchRequest {
   /** ID of the uploaded input file (JSONL format). */
-  inputFileId?: string;
+  readonly inputFileId?: string;
   /** API endpoint (e.g., `"/v1/chat/completions"`). */
-  endpoint?: string;
+  readonly endpoint?: string;
   /** Completion window (e.g., `"24h"`). */
-  completionWindow?: string;
+  readonly completionWindow?: string;
   /** Optional metadata to attach to the batch. */
-  metadata?: any;
+  readonly metadata?: JsonValue;
 }
 
-/**
- * Create a new LLM client with simple scalar configuration.
- *
- * This is the primary binding entry-point. All parameters except `api_key`
- * are optional — omitting them uses the same defaults as
- * `ClientConfigBuilder`.
- *
- * # Errors
- *
- * 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;
-
-/**
- * Create a new LLM client from a JSON string.
- *
- * The JSON object accepts the same fields as `liter-llm.toml` (snake_case).
- *
- * # Errors
- *
- * Returns `LiterLlmError.BadRequest` if `json` is not valid JSON or
- * contains unknown fields.
- */
-export declare function createClientFromJson(json: string): DefaultClient;
-
 /** Request to upload a file. */
 export interface CreateFileRequest {
   /** Base64-encoded file data. */
-  file?: string;
+  readonly file?: string;
   /** Purpose for the file. */
-  purpose?: JsFilePurpose;
+  readonly purpose?: FilePurpose;
   /** Optional filename to associate with the upload. */
-  filename?: string;
+  readonly filename?: string;
 }
 
 /** Request to create images from a text prompt. */
 export interface CreateImageRequest {
   /** Text description of the image to generate. */
-  prompt?: string;
+  readonly prompt?: string;
   /** Model ID (e.g., `"dall-e-3"`). Optional; API may use default if unset. */
-  model?: string;
+  readonly model?: string;
   /** Number of images to generate. Defaults to 1. */
-  n?: number;
+  readonly n?: number;
   /** Image size (e.g., `"1024x1024"`, `"1792x1024"`). */
-  size?: string;
+  readonly size?: string;
   /** Image quality: `"standard"` or `"hd"`. */
-  quality?: string;
+  readonly quality?: string;
   /** Style: `"natural"` or `"vivid"` (DALL-E 3 only). */
-  style?: string;
+  readonly style?: string;
   /** Response format: `"url"` or `"b64_json"`. */
-  responseFormat?: string;
+  readonly responseFormat?: string;
   /** User identifier for request tracking. */
-  user?: string;
+  readonly user?: string;
 }
 
 /** Request to create a structured response. */
 export interface CreateResponseRequest {
   /** Model ID. */
-  model?: string;
+  readonly model?: string;
   /** Input data to process (e.g., a document to extract from). */
-  input?: any;
+  readonly input?: JsonValue;
   /** Instructions for processing the input. */
-  instructions?: string;
+  readonly instructions?: string;
   /** Available tools the model can use. */
-  tools?: Array<JsResponseTool>;
+  readonly tools?: Array<ResponseTool>;
   /** Sampling temperature in `[0.0, 2.0]`. Defaults to 1.0. */
-  temperature?: number;
+  readonly temperature?: number;
   /** Maximum output tokens. */
-  maxOutputTokens?: number;
+  readonly maxOutputTokens?: number;
   /** Optional metadata. */
-  metadata?: any;
+  readonly metadata?: JsonValue;
 }
 
 /** Request to generate speech audio from text. */
 export interface CreateSpeechRequest {
   /** Model ID (e.g., `"tts-1"`, `"tts-1-hd"`). */
-  model?: string;
+  readonly model?: string;
   /** Text to synthesize into speech. */
-  input?: string;
+  readonly input?: string;
   /** Voice name (e.g., `"alloy"`, `"echo"`, `"fable"`, `"onyx"`, `"nova"`, `"shimmer"`). */
-  voice?: string;
+  readonly voice?: string;
   /** Audio format (e.g., `"mp3"`, `"opus"`, `"aac"`, `"flac"`, `"wav"`, `"pcm"`). */
-  responseFormat?: string;
+  readonly responseFormat?: string;
   /** Playback speed in `[0.25, 4.0]`. Defaults to 1.0. */
-  speed?: number;
+  readonly speed?: number;
 }
 
 /** Request to transcribe audio into text. */
 export interface CreateTranscriptionRequest {
   /** Model ID (e.g., `"whisper-1"`). */
-  model?: string;
+  readonly model?: string;
   /** Base64-encoded audio file data. */
-  file?: string;
+  readonly file?: string;
   /** Language ISO-639-1 code (e.g., `"en"`, `"fr"`, `"de"`). Optional; model auto-detects. */
-  language?: string;
+  readonly language?: string;
   /** Optional text to guide the model (improves accuracy for domain-specific terms). */
-  prompt?: string;
+  readonly prompt?: string;
   /** Output format (e.g., `"json"`, `"text"`, `"vtt"`, `"srt"`, `"verbose_json"`). */
-  responseFormat?: string;
+  readonly responseFormat?: string;
   /** Sampling temperature in `[0.0, 1.0]`. Higher increases variability. Defaults to 0. */
-  temperature?: number;
+  readonly temperature?: number;
 }
 
 /** Configuration for registering a custom LLM provider at runtime. */
 export interface CustomProviderConfig {
   /** Unique name for this provider (e.g., "my-provider"). */
-  name: string;
+  readonly name: string;
   /** Base URL for the provider's API (e.g., "https://api.my-provider.com/v1"). */
-  baseUrl: string;
+  readonly baseUrl: string;
   /** Authentication header format. */
-  authHeader: JsAuthHeaderFormat;
+  readonly authHeader: AuthHeaderFormat;
   /** Model name prefixes that route to this provider (e.g., `["my-"]`). */
-  modelPrefixes: Array<string>;
+  readonly modelPrefixes: Array<string>;
+}
+
+/**
+ * Default client implementation backed by `reqwest`.
+ *
+ * Sends requests to 143 LLM providers with automatic provider detection
+ * and per-request routing. The provider is resolved at construction time
+ * from `model_hint` (or defaults to OpenAI), but individual requests can
+ * override the provider via model name prefix (e.g. `"anthropic/claude-3-5-sonnet"`
+ * routes to Anthropic regardless of construction-time setting).
+ *
+ * When the model prefix does not match any known provider, the construction-time
+ * 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
+ * async closures and streaming tasks. Pre-computed auth headers and extra
+ * headers are cached at construction to avoid redundant encoding on every request.
+ */
+export declare class DefaultClient {
+  chat(req?: ChatCompletionRequest | undefined | null): Promise<ChatCompletionResponse>;
+  chatStream(
+    req?: ChatCompletionRequest | undefined | null,
+  ): Promise<AsyncGenerator<ChatCompletionChunk, void, undefined>>;
+  embed(req?: EmbeddingRequest | undefined | null): Promise<EmbeddingResponse>;
+  listModels(): Promise<ModelsListResponse>;
+  imageGenerate(req?: CreateImageRequest | undefined | null): Promise<ImagesResponse>;
+  speech(req?: CreateSpeechRequest | undefined | null): Promise<Uint8Array>;
+  transcribe(req?: CreateTranscriptionRequest | undefined | null): Promise<TranscriptionResponse>;
+  moderate(req?: ModerationRequest | undefined | null): Promise<ModerationResponse>;
+  rerank(req?: RerankRequest | undefined | null): Promise<RerankResponse>;
+  search(req?: SearchRequest | undefined | null): Promise<SearchResponse>;
+  ocr(req?: OcrRequest | undefined | null): Promise<OcrResponse>;
+  createFile(req?: CreateFileRequest | undefined | null): Promise<FileObject>;
+  retrieveFile(fileId: string): Promise<FileObject>;
+  deleteFile(fileId: string): Promise<DeleteResponse>;
+  listFiles(query?: FileListQuery | undefined | null): Promise<FileListResponse>;
+  fileContent(fileId: string): Promise<Uint8Array>;
+  createBatch(req?: CreateBatchRequest | undefined | null): Promise<BatchObject>;
+  retrieveBatch(batchId: string): Promise<BatchObject>;
+  listBatches(query?: BatchListQuery | undefined | null): Promise<BatchListResponse>;
+  cancelBatch(batchId: string): Promise<BatchObject>;
+  fetchBatchForPolling(batchId: string): Promise<BatchObject>;
+  /**
+   * Poll a batch until it reaches a terminal status (Completed, Failed, Expired, Cancelled).
+   *
+   * 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.
+   */
+  waitForBatch(
+    batchId: string,
+    config?: WaitForBatchConfig | undefined | null,
+  ): Promise<BatchObject>;
+  createResponse(req?: CreateResponseRequest | undefined | null): Promise<ResponseObject>;
+  retrieveResponse(responseId: string): Promise<ResponseObject>;
+  cancelResponse(responseId: string): Promise<ResponseObject>;
 }
 
 /** Response from a delete operation. */
 export interface DeleteResponse {
   /** ID of the deleted resource. */
-  id?: string;
+  readonly id?: string;
   /** Object type. */
-  object?: string;
+  readonly object?: string;
   /** Confirmation that the resource was deleted. */
-  deleted?: boolean;
+  readonly deleted?: boolean;
 }
 
 /** Developer message (system-like message for Claude models). */
 export interface DeveloperMessage {
   /** Developer-specific instructions or context. */
-  content?: string;
+  readonly content?: string;
   /** Optional name for the developer message source. */
-  name?: string;
+  readonly name?: string;
 }
 
 /** PDF/document content part for vision-capable models. */
 export interface DocumentContent {
   /** Base64-encoded document data or URL. */
-  data?: string;
+  readonly data?: string;
   /** MIME type (e.g., "application/pdf", "text/csv"). */
-  mediaType?: string;
+  readonly mediaType?: string;
 }
 
 /** The format in which the embedding vectors are returned. */
-export declare const enum EmbeddingFormat {
+export declare enum EmbeddingFormat {
   /** 32-bit floating-point numbers (default). */
   Float = "float",
   /** Base64-encoded string representation of the floats. */
   Base64 = "base64",
 }
 
+/** Text or texts to embed. */
+export declare enum EmbeddingInput {
+  /** Single text string. */
+  Single = "Single",
+  /** Multiple text strings (batch embedding). */
+  Multiple = "Multiple",
+}
+
 /** A single embedding vector. */
 export interface EmbeddingObject {
   /**
    * Always `"embedding"` from OpenAI-compatible APIs.  Stored as a plain
    * `String` so non-standard provider values do not break deserialization.
    */
-  object: string;
+  readonly object: string;
   /** The embedding vector. */
-  embedding: Array<number>;
+  readonly embedding: Array<number>;
   /** Index in the batch (corresponds to input order). */
-  index: number;
+  readonly index: number;
 }
 
 /** Embedding request. */
 export interface EmbeddingRequest {
   /** Model ID (e.g., `"text-embedding-3-small"`). */
-  model?: string;
+  readonly model?: string;
   /** Text or texts to embed. */
-  input?: JsEmbeddingInput;
+  readonly input?: EmbeddingInput;
   /** Output format: float (native) or base64. */
-  encodingFormat?: JsEmbeddingFormat;
+  readonly encodingFormat?: EmbeddingFormat;
   /** Requested embedding dimensions (if supported by the model). */
-  dimensions?: number;
+  readonly dimensions?: number;
   /** User identifier for request tracking. */
-  user?: string;
+  readonly user?: string;
 }
 
 /** Embedding response. */
@@ -737,89 +734,69 @@ export interface EmbeddingResponse {
    * Always `"list"` from OpenAI-compatible APIs.  Stored as a plain
    * `String` so non-standard provider values do not break deserialization.
    */
-  object: string;
+  readonly object: string;
   /** List of embeddings. */
-  data: Array<JsEmbeddingObject>;
+  readonly data: Array<EmbeddingObject>;
   /** Model used to generate embeddings. */
-  model: string;
+  readonly model: string;
   /** Token usage (input tokens only; embeddings have zero output tokens). */
-  usage?: Usage;
+  readonly usage?: Usage;
 }
 
 /** How budget limits are enforced. */
-export declare const enum Enforcement {
+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",
 }
 
-/**
- * Install the `ring` crypto provider as the rustls process default, idempotently.
- *
- * rustls 0.23+ removed the implicit default provider. This function installs
- * `ring` once per process. Subsequent calls are no-ops. Calling it from a
- * downstream Rust app that has already installed `aws-lc-rs` is safe — the
- * `Err` from `install_default()` is silently ignored.
- *
- * 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.
- *
- * WASM builds are exempt — the WASM target uses the browser/Node.js fetch
- * API instead of rustls, so no crypto provider is needed.
- *
- * Windows builds use native-tls (SChannel) via reqwest, so rustls is not
- * present and no crypto provider installation is needed.
- */
-export declare function ensureCryptoProvider(): void;
-
 /** Query parameters for listing files. */
 export interface FileListQuery {
   /** Filter by file purpose (e.g., `"batch"`, `"fine-tune"`). */
-  purpose?: string;
+  readonly purpose?: string;
   /** Maximum number of results to return. Defaults to 20. */
-  limit?: number;
+  readonly limit?: number;
   /** Pagination cursor: return results after this file ID. */
-  after?: string;
+  readonly after?: string;
 }
 
 /** Response from listing files. */
 export interface FileListResponse {
   /** Object type (always `"list"`). */
-  object?: string;
+  readonly object?: string;
   /** List of file objects. */
-  data?: Array<FileObject>;
+  readonly data?: Array<FileObject>;
   /** Whether more results are available. */
-  hasMore?: boolean;
+  readonly hasMore?: boolean;
 }
 
 /** An uploaded file object. */
 export interface FileObject {
   /** Unique file ID. */
-  id?: string;
+  readonly id?: string;
   /** Object type (always `"file"`). */
-  object?: string;
+  readonly object?: string;
   /** File size in bytes. */
-  bytes?: number;
+  readonly bytes?: number;
   /** Unix timestamp of file creation. */
-  createdAt?: number;
+  readonly createdAt?: number;
   /** Filename. */
-  filename?: string;
+  readonly filename?: string;
   /** File purpose. */
-  purpose?: string;
+  readonly purpose?: string;
   /** Processing status (e.g., `"uploaded"`, `"processed"`). */
-  status?: string;
+  readonly status?: string;
 }
 
 /** Purpose of an uploaded file. */
-export declare const enum FilePurpose {
+export declare enum FilePurpose {
   /** File for use with Assistants API. */
   Assistants = "assistants",
   /** File for batch processing. */
@@ -831,7 +808,7 @@ export declare const enum FilePurpose {
 }
 
 /** Why a choice stopped generating tokens. */
-export declare const enum FinishReason {
+export declare enum FinishReason {
   Stop = "stop",
   Length = "length",
   ToolCalls = "tool_calls",
@@ -853,31 +830,48 @@ export declare const enum FinishReason {
 /** Function call details. */
 export interface FunctionCall {
   /** Function name. */
-  name: string;
-  /** Arguments as a JSON string (parse with serde_json.from_str). */
-  arguments: string;
+  readonly name: string;
+  /** Arguments as a JSON string (parse with serde_json::from_str). */
+  readonly arguments: string;
 }
 
 /** Function definition exposed to the model. */
 export interface FunctionDefinition {
   /** Name of the function. Required and must be alphanumeric + underscores. */
-  name: string;
+  readonly name: string;
   /** Human-readable description explaining what the function does. */
-  description?: string;
+  readonly description?: string;
   /** JSON Schema defining the function's parameters. */
-  parameters?: any;
+  readonly parameters?: JsonValue;
   /** If true, enforce strict JSON schema validation for arguments. */
-  strict?: boolean;
+  readonly strict?: boolean;
 }
 
 /** Deprecated legacy function-role message body. */
 export interface FunctionMessage {
-  content?: string;
-  name?: string;
+  readonly content?: string;
+  readonly name?: string;
+}
+
+/**
+ * Abstraction over a health probe strategy.
+ *
+ * Implementors issue a lightweight probe against `upstream` (typically a
+ * provider base URL or named identifier) and report [`HealthStatus`].
+ */
+export interface HealthChecker {
+  /**
+   * 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
+   * `'static + Send` bound on the future trivially satisfiable.
+   */
+  check(upstream: string): Promise<string>;
 }
 
 /** The result of a single health probe. */
-export declare const enum HealthStatus {
+export declare enum HealthStatus {
   /** The probe succeeded; the upstream is reachable. */
   Healthy = "Healthy",
   /** The probe failed; the upstream may be down. */
@@ -887,15 +881,15 @@ export declare const enum HealthStatus {
 /** A single generated image, returned as either a URL or base64 data. */
 export interface Image {
   /** Image URL (if response_format was "url"). */
-  url?: string;
+  readonly url?: string;
   /** Base64-encoded image data (if response_format was "b64_json"). */
-  b64Json?: string;
+  readonly b64Json?: string;
   /** The final prompt used to generate the image (DALL-E 3). */
-  revisedPrompt?: string;
+  readonly revisedPrompt?: string;
 }
 
 /** Image detail level controlling token cost and processing. */
-export declare const enum ImageDetail {
+export declare enum ImageDetail {
   /** Low detail: scales image to 512x512, uses fewer tokens. */
   Low = "low",
   /** High detail: processes up to 2x2 grid of tiles, higher token cost. */
@@ -907,65 +901,63 @@ export declare const enum ImageDetail {
 /** Response containing generated images. */
 export interface ImagesResponse {
   /** Unix timestamp of image creation. */
-  created?: number;
+  readonly created?: number;
   /** List of generated images. */
-  data?: Array<JsImage>;
+  readonly data?: Array<Image>;
 }
 
 /** An image URL reference with optional detail level for processing. */
 export interface ImageUrl {
   /** URL of the image (data URI or HTTP/HTTPS URL). */
-  url?: string;
+  readonly url?: string;
   /** Detail level: low (512x512), high (2x2 tiles), or auto (model-selected). */
-  detail?: JsImageDetail;
+  readonly detail?: ImageDetail;
 }
 
 /** An intent prototype: `(intent_name, prototype_embedding, target_model_id)`. */
 export interface IntentPrototype {
   /** Human-readable name for the intent (used in logs/metrics). */
-  name: string;
+  readonly name: string;
   /** Pre-computed embedding vector for this intent. */
-  embedding: Array<number>;
+  readonly embedding: Array<number>;
   /** Model to route to when this intent is detected. */
-  model: string;
+  readonly model: string;
 }
 
 /** JSON Schema specification for constrained output. */
 export interface JsonSchemaFormat {
   /** Name of the schema (must be unique in the request). */
-  name?: string;
+  readonly name?: string;
   /** Description of what the schema represents. */
-  description?: string;
+  readonly description?: string;
   /** JSON Schema object defining the output structure. */
-  schema?: any;
+  readonly schema?: JsonValue;
   /** If true, enforce strict schema validation. */
-  strict?: boolean;
+  readonly strict?: boolean;
 }
 
 /** A chat message in a conversation. */
-export interface Message {
-  role: string;
-  system?: SystemMessage;
-  user?: UserMessage;
-  assistant?: AssistantMessage;
-  tool?: ToolMessage;
-  developer?: DeveloperMessage;
-  function?: FunctionMessage;
-}
+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 };
 
 /** A model available from the API. */
 export interface ModelObject {
   /** Model ID (e.g., `"gpt-4o"`, `"claude-3-5-sonnet"`). */
-  id?: string;
+  readonly id?: string;
   /**
    * Always `"model"` from OpenAI-compatible APIs.  Stored as a plain
    * `String` so non-standard provider values do not break deserialization.
    */
-  object?: string;
+  readonly object?: string;
   /** Unix timestamp of model creation (or release date). */
-  created?: number;
+  readonly created?: number;
   /** Organization or entity that owns the model. */
-  ownedBy?: string;
+  readonly ownedBy?: string;
 }
 
 /** Response listing available models. */
@@ -974,162 +966,167 @@ export interface ModelsListResponse {
    * Always `"list"` from OpenAI-compatible APIs.  Stored as a plain
    * `String` so non-standard provider values do not break deserialization.
    */
-  object?: string;
+  readonly object?: string;
   /** List of available models. */
-  data?: Array<JsModelObject>;
+  readonly data?: Array<ModelObject>;
 }
 
 /** Boolean flags for each moderation category. */
 export interface ModerationCategories {
   /** Sexual content. */
-  sexual?: boolean;
+  readonly sexual?: boolean;
   /** Hate speech. */
-  hate?: boolean;
+  readonly hate?: boolean;
   /** Harassment. */
-  harassment?: boolean;
+  readonly harassment?: boolean;
   /** Self-harm content. */
-  "self-harm"?: boolean;
+  readonly selfHarm?: boolean;
   /** Sexual content involving minors. */
-  "sexual/minors"?: boolean;
+  readonly sexualMinors?: boolean;
   /** Hate speech that threatens violence. */
-  "hate/threatening"?: boolean;
+  readonly hateThreatening?: boolean;
   /** Graphic violence. */
-  "violence/graphic"?: boolean;
+  readonly violenceGraphic?: boolean;
   /** Intent to self-harm. */
-  "self-harm/intent"?: boolean;
+  readonly selfHarmIntent?: boolean;
   /** Instructions for self-harm. */
-  "self-harm/instructions"?: boolean;
+  readonly selfHarmInstructions?: boolean;
   /** Harassment that threatens violence. */
-  "harassment/threatening"?: boolean;
+  readonly harassmentThreatening?: boolean;
   /** Non-graphic violence. */
-  violence?: boolean;
+  readonly violence?: boolean;
 }
 
 /** Confidence scores for each moderation category. */
 export interface ModerationCategoryScores {
   /** Sexual content score. */
-  sexual?: number;
+  readonly sexual?: number;
   /** Hate speech score. */
-  hate?: number;
+  readonly hate?: number;
   /** Harassment score. */
-  harassment?: number;
+  readonly harassment?: number;
   /** Self-harm content score. */
-  "self-harm"?: number;
+  readonly selfHarm?: number;
   /** Sexual content involving minors score. */
-  "sexual/minors"?: number;
+  readonly sexualMinors?: number;
   /** Hate speech that threatens violence score. */
-  "hate/threatening"?: number;
+  readonly hateThreatening?: number;
   /** Graphic violence score. */
-  "violence/graphic"?: number;
+  readonly violenceGraphic?: number;
   /** Intent to self-harm score. */
-  "self-harm/intent"?: number;
+  readonly selfHarmIntent?: number;
   /** Instructions for self-harm score. */
-  "self-harm/instructions"?: number;
+  readonly selfHarmInstructions?: number;
   /** Harassment that threatens violence score. */
-  "harassment/threatening"?: number;
+  readonly harassmentThreatening?: number;
   /** Non-graphic violence score. */
-  violence?: number;
+  readonly violence?: number;
+}
+
+/** 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",
 }
 
 /** Request to classify content for policy violations. */
 export interface ModerationRequest {
   /** Text or texts to check. */
-  input?: JsModerationInput;
+  readonly input?: ModerationInput;
   /** Model ID (e.g., `"text-moderation-latest"`). Optional; API uses default if unset. */
-  model?: string;
+  readonly model?: string;
 }
 
 /** Response from the moderation endpoint. */
 export interface ModerationResponse {
   /** Unique identifier for this moderation request. */
-  id: string;
+  readonly id: string;
   /** Model used for classification. */
-  model: string;
+  readonly model: string;
   /** Results for each input string. */
-  results: Array<JsModerationResult>;
+  readonly results: Array<ModerationResult>;
 }
 
 /** A single moderation classification result. */
 export interface ModerationResult {
   /** True if any category was flagged. */
-  flagged: boolean;
+  readonly flagged: boolean;
   /** Boolean flags for each moderation category. */
-  categories: JsModerationCategories;
+  readonly categories: ModerationCategories;
   /** Confidence scores for each category. */
-  categoryScores: JsModerationCategoryScores;
+  readonly categoryScores: ModerationCategoryScores;
 }
 
 /** Document input for OCR — either a URL or inline base64 data. */
-export interface OcrDocument {
-  type: string;
-  url?: string;
-  data?: string;
-  mediaType?: string;
-}
+export type OcrDocument =
+  | { type: "document_url"; url: string }
+  | { type: "base64"; data: string; mediaType: string };
 
 /** An image extracted from an OCR page. */
 export interface OcrImage {
   /** Unique image identifier within the document. */
-  id: string;
+  readonly id: string;
   /** Base64-encoded image data (if `include_image_base64` was true). */
-  imageBase64?: string;
+  readonly imageBase64?: string;
 }
 
 /** A single page of OCR output. */
 export interface OcrPage {
   /** Page index (0-based). */
-  index: number;
+  readonly index: number;
   /** Extracted page content as Markdown. */
-  markdown: string;
+  readonly markdown: string;
   /** Embedded images extracted from the page (if `include_image_base64` was true). */
-  images?: Array<JsOcrImage>;
+  readonly images?: Array<OcrImage>;
   /** Page dimensions in pixels, if available. */
-  dimensions?: JsPageDimensions;
+  readonly dimensions?: PageDimensions;
 }
 
 /** An OCR request. */
 export interface OcrRequest {
   /** The model/provider to use (e.g. `"mistral/mistral-ocr-latest"`). */
-  model?: string;
+  readonly model?: string;
   /** The document to process (URL or base64). */
-  document?: JsOcrDocument;
+  readonly document?: OcrDocument;
   /** Specific pages to process (1-indexed). `None` means all pages. */
-  pages?: Array<number>;
+  readonly pages?: Array<number>;
   /** Whether to include base64-encoded images of each processed page. */
-  includeImageBase64?: boolean;
+  readonly includeImageBase64?: boolean;
 }
 
 /** An OCR response. */
 export interface OcrResponse {
   /** Extracted pages in order. */
-  pages: Array<JsOcrPage>;
+  readonly pages: Array<OcrPage>;
   /** Model/provider used for OCR. */
-  model: string;
+  readonly model: string;
   /** Token usage, if reported by the provider. */
-  usage?: Usage;
+  readonly usage?: Usage;
 }
 
 /** Page dimensions in pixels. */
 export interface PageDimensions {
   /** Width in pixels. */
-  width: number;
+  readonly width: number;
   /** Height in pixels. */
-  height: number;
+  readonly height: number;
 }
 
 /**
  * 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.
  */
 export interface PromptTokensDetails {
   /** Cached tokens present in the prompt. Defaults to 0 when absent. */
-  cachedTokens?: number;
+  readonly cachedTokens?: number;
   /** Audio input tokens present in the prompt. Defaults to 0 when absent. */
-  audioTokens?: number;
+  readonly audioTokens?: number;
 }
 
 /**
@@ -1143,250 +1140,272 @@ export interface PromptTokensDetails {
  *
  * All flags default to `false` so that newly added providers are safe.
  *
- * Access via the crate-level `capabilities` function:
+ * 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);
+ * ```
  */
 export interface ProviderCapabilities {
   /** The provider accepts image input in chat messages. */
-  vision?: boolean;
+  readonly vision?: boolean;
   /** The provider supports extended-thinking / reasoning tokens. */
-  reasoning?: boolean;
+  readonly reasoning?: boolean;
   /** The provider supports JSON-mode or `response_format` structured output. */
-  structuredOutput?: boolean;
+  readonly structuredOutput?: boolean;
   /** The provider supports tool / function calling. */
-  functionCalling?: boolean;
+  readonly functionCalling?: boolean;
   /** The provider accepts audio as input. */
-  audioIn?: boolean;
+  readonly audioIn?: boolean;
   /** The provider can generate audio / TTS output. */
-  audioOut?: boolean;
+  readonly audioOut?: boolean;
   /** The provider accepts video as input. */
-  videoIn?: boolean;
+  readonly videoIn?: boolean;
 }
 
 /**
  * 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.  Keeping
+ * format, which are accessed via the [`capabilities`] function.  Keeping
  * these fields separate preserves backward compatibility with all generated
  * binding code that constructs `ProviderConfig` using struct literal syntax.
  */
 export interface ProviderConfig {
   /** Provider identifier (matches the entry key in providers.json). */
-  name: string;
+  readonly name: string;
   /** Human-readable provider name shown in UIs. */
-  displayName?: string;
+  readonly displayName?: string;
   /** Base URL used as the default for this provider's HTTP client. */
-  baseUrl?: string;
+  readonly baseUrl?: string;
   /** Authentication scheme metadata (auth type + env var holding the key). */
-  auth?: JsAuthConfig;
+  readonly auth?: AuthConfig;
   /** Supported endpoint kinds (e.g. `chat`, `embeddings`). */
-  endpoints?: Array<string>;
+  readonly endpoints?: Array<string>;
   /** Model-name prefixes claimed by this provider (e.g. `["gpt-", "o1-"]`). */
-  modelPrefixes?: Array<string>;
+  readonly modelPrefixes?: Array<string>;
   /**
    * Parameter key renaming for this provider.
    *
    * 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`].
    */
-  paramMappings?: Record<string, string>;
+  readonly paramMappings?: Record<string, string>;
 }
 
 /** Configuration for per-model rate limits. */
 export interface RateLimitConfig {
   /** Maximum requests per window.  `None` means unlimited. */
-  rpm?: number;
+  readonly rpm?: number;
   /** Maximum tokens per window.  `None` means unlimited. */
-  tpm?: number;
+  readonly tpm?: number;
   /** Fixed window duration (defaults to 60 s). */
-  window?: number;
+  readonly window?: number;
 }
 
-export declare function rateLimitConfigDefault(): RateLimitConfig;
-
 /** Controls how much reasoning effort the model should use. */
-export declare const enum ReasoningEffort {
+export declare enum ReasoningEffort {
   Low = "low",
   Medium = "medium",
   High = "high",
 }
 
-/**
- * Register a custom provider in the global runtime registry.
- *
- * The provider will be checked **before** all built-in providers during model
- * detection. If a provider with the same `name` already exists it is replaced.
- *
- * # Errors
- *
- * Returns an error if the config is invalid (empty name, empty base_url, or
- * no model prefixes).
- */
-export declare function registerCustomProvider(config: CustomProviderConfig): void;
+/** 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",
+}
 
 /** Request to rerank documents by relevance to a query. */
 export interface RerankRequest {
   /** Model ID (e.g., `"cohere/rerank-english-v3.0"`). */
-  model?: string;
+  readonly model?: string;
   /** The search query. */
-  query?: string;
+  readonly query?: string;
   /** Documents to rerank. */
-  documents?: Array<JsRerankDocument>;
+  readonly documents?: Array<RerankDocument>;
   /** Return only the top N results. Optional. */
-  topN?: number;
+  readonly topN?: number;
   /** Include the document content in results. Defaults to false. */
-  returnDocuments?: boolean;
+  readonly returnDocuments?: boolean;
 }
 
 /** Response from the rerank endpoint. */
 export interface RerankResponse {
   /** Unique identifier for this rerank request. */
-  id?: string;
+  readonly id?: string;
   /** Reranked documents in order of relevance. */
-  results: Array<JsRerankResult>;
+  readonly results: Array<RerankResult>;
   /** Optional metadata about the reranking operation. */
-  meta?: any;
+  readonly meta?: JsonValue;
 }
 
 /** A single reranked document with its relevance score. */
 export interface RerankResult {
   /** Original document index in the input list. */
-  index: number;
+  readonly index: number;
   /** Relevance score in `[0, 1]`. Higher indicates more relevant. */
-  relevanceScore: number;
+  readonly relevanceScore: number;
   /** Original document content (if `return_documents` was true). */
-  document?: JsRerankResultDocument;
+  readonly document?: RerankResultDocument;
 }
 
 /** The text content of a reranked document, returned when `return_documents` is true. */
 export interface RerankResultDocument {
   /** Document text. */
-  text: string;
+  readonly text: string;
 }
 
 /** Response format constraint. */
-export interface ResponseFormat {
-  type: string;
-  jsonSchema?: JsonSchemaFormat;
-}
+export type ResponseFormat =
+  | { type: "text" }
+  | { type: "json_object" }
+  | { type: "json_schema"; jsonSchema: JsonSchemaFormat };
 
 /** Response from a structured response request. */
 export interface ResponseObject {
   /** Unique response ID. */
-  id?: string;
+  readonly id?: string;
   /** Object type (e.g., `"response"`). */
-  object?: string;
+  readonly object?: string;
   /** Unix timestamp of response creation. */
-  createdAt?: number;
+  readonly createdAt?: number;
   /** Model used to generate the response. */
-  model?: string;
+  readonly model?: string;
   /** Status (e.g., `"succeeded"`, `"failed"`). */
-  status?: string;
+  readonly status?: string;
   /** Output items from the response. */
-  output?: Array<JsResponseOutputItem>;
+  readonly output?: Array<ResponseOutputItem>;
   /** Token usage. */
-  usage?: JsResponseUsage;
+  readonly usage?: ResponseUsage;
   /** Error details (if status is "failed"). */
-  error?: any;
+  readonly error?: JsonValue;
 }
 
 /** A single output item from the response. */
 export interface ResponseOutputItem {
   /** Output type (e.g., `"text"`, `"object"`, `"error"`). */
-  type?: string;
+  readonly itemType?: string;
   /** Output content (flattened into the object). */
-  content?: any;
+  readonly content?: JsonValue;
 }
 
 /** A tool available for the response request. */
 export interface ResponseTool {
   /** Tool type (e.g., "extractor", "search"). */
-  type?: string;
+  readonly toolType?: string;
   /** Tool configuration (flattened into the object). */
-  config?: any;
+  readonly config?: JsonValue;
 }
 
 /** Token usage for a response. */
 export interface ResponseUsage {
   /** Input tokens used. */
-  inputTokens?: number;
+  readonly inputTokens?: number;
   /** Output tokens used. */
-  outputTokens?: number;
+  readonly outputTokens?: number;
   /** Total tokens used. */
-  totalTokens?: number;
+  readonly totalTokens?: number;
 }
 
 /** A search request. */
 export interface SearchRequest {
   /** The model/provider to use (e.g. `"brave/web-search"`, `"tavily/search"`). */
-  model?: string;
+  readonly model?: string;
   /** The search query string. */
-  query?: string;
+  readonly query?: string;
   /** Maximum number of results to return. */
-  maxResults?: number;
+  readonly maxResults?: number;
   /** Domain filter — restrict results to specific domains. */
-  searchDomainFilter?: Array<string>;
+  readonly searchDomainFilter?: Array<string>;
   /** Country code for localized results (ISO 3166-1 alpha-2, e.g., `"US"`, `"FR"`). */
-  country?: string;
+  readonly country?: string;
 }
 
 /** A search response. */
 export interface SearchResponse {
   /** List of search results. */
-  results: Array<JsSearchResult>;
+  readonly results: Array<SearchResult>;
   /** Model/provider that performed the search. */
-  model: string;
+  readonly model: string;
 }
 
 /** An individual search result. */
 export interface SearchResult {
   /** Result title. */
-  title: string;
+  readonly title: string;
   /** Result URL. */
-  url: string;
+  readonly url: string;
   /** Text snippet or excerpt from the page. */
-  snippet: string;
+  readonly snippet: string;
   /** Publication or last-updated date, if available. */
-  date?: string;
+  readonly date?: string;
 }
 
+/**
+ * The value broadcast from a singleflight leader to all followers.
+ *
+ * `Arc<LiterLlmError>` is used because `LiterLlmError` is not `Clone` and
+ * broadcast channels require `T: Clone`.  The `Arc` adds only a reference-count
+ * bump per follower, which is negligible under the burst loads this layer targets.
+ */
+export declare class SingleflightResult {}
+
 /** Name of the specific function to invoke. */
 export interface SpecificFunction {
   /** Function name. */
-  name?: string;
+  readonly name?: string;
 }
 
 /** Directive to call a specific tool. */
 export interface SpecificToolChoice {
   /** Tool type (always "function"). */
-  type?: JsToolType;
+  readonly choiceType?: ToolType;
   /** The specific function to invoke. */
-  function?: JsSpecificFunction;
+  readonly function?: SpecificFunction;
+}
+
+/** Stop sequence(s) that cause the model to stop generating. */
+export declare enum StopSequence {
+  /** Single stop sequence. */
+  Single = "Single",
+  /** Multiple stop sequences. */
+  Multiple = "Multiple",
 }
 
 /** A streaming choice with incremental delta. */
 export interface StreamChoice {
   /** Index of this choice in the choices array. */
-  index?: number;
+  readonly index?: number;
   /** Incremental update to the message (content, tool calls, etc.). */
-  delta?: JsStreamDelta;
+  readonly delta?: StreamDelta;
   /** Why the stream ended (present only in final chunk). */
-  finishReason?: JsFinishReason;
+  readonly finishReason?: FinishReason;
 }
 
 /** Incremental delta in a stream chunk. */
 export interface StreamDelta {
   /** Role (typically present only in the first chunk). */
-  role?: string;
+  readonly role?: string;
   /** Partial content chunk (e.g., a few words of the response). */
-  content?: string;
+  readonly content?: string;
   /** Partial tool calls being streamed. */
-  toolCalls?: Array<JsStreamToolCall>;
+  readonly toolCalls?: Array<StreamToolCall>;
   /** Deprecated legacy function_call delta; retained for API compatibility. */
-  functionCall?: JsStreamFunctionCall;
+  readonly functionCall?: StreamFunctionCall;
   /** Partial refusal message. */
-  refusal?: string;
+  readonly refusal?: string;
 }
 
 /**
@@ -1395,9 +1414,9 @@ 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 const enum StreamFormat {
+export declare enum StreamFormat {
   /** Standard Server-Sent Events (text/event-stream). */
   Sse = "sse",
   /** AWS EventStream binary framing (application/vnd.amazon.eventstream). */
@@ -1407,49 +1426,57 @@ export declare const enum StreamFormat {
 /** Partial function call details in a stream. */
 export interface StreamFunctionCall {
   /** Function name (typically in the first chunk). */
-  name?: string;
+  readonly name?: string;
   /** Partial JSON arguments chunk. */
-  arguments?: string;
+  readonly arguments?: string;
 }
 
 /** Options for streaming responses. */
 export interface StreamOptions {
   /** If true, include token usage in the final stream chunk. */
-  includeUsage?: boolean;
+  readonly includeUsage?: boolean;
 }
 
 /** A streaming tool call being built incrementally. */
 export interface StreamToolCall {
   /** Index of this tool call in the tool_calls array. */
-  index?: number;
+  readonly index?: number;
   /** Tool call ID (typically in the first chunk for this call). */
-  id?: string;
+  readonly id?: string;
   /** Tool type (typically "function"). */
-  type?: JsToolType;
+  readonly callType?: ToolType;
   /** Partial function name and arguments. */
-  function?: JsStreamFunctionCall;
+  readonly function?: StreamFunctionCall;
 }
 
 /** System message guiding model behavior for the entire conversation. */
 export interface SystemMessage {
   /** Instructions or context that apply throughout the conversation. */
-  content?: string;
+  readonly content?: string;
   /** Optional name for the system message source. */
-  name?: string;
+  readonly name?: string;
 }
 
 /** A tool call the model wants to execute. */
 export interface ToolCall {
   /** Unique ID for this call, used to reference in tool result messages. */
-  id: string;
+  readonly id: string;
   /** Tool type (always "function"). */
-  type: JsToolType;
+  readonly callType: ToolType;
   /** Function name and arguments. */
-  function: JsFunctionCall;
+  readonly function: FunctionCall;
+}
+
+/** 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",
 }
 
 /** Tool choice mode. */
-export declare const enum ToolChoiceMode {
+export declare enum ToolChoiceMode {
   /** Model may or may not call tools; default behavior. */
   Auto = "auto",
   /** Model must call at least one tool. */
@@ -1461,11 +1488,11 @@ export declare const enum ToolChoiceMode {
 /** Tool execution result returned to the model. */
 export interface ToolMessage {
   /** Result of the tool execution. */
-  content?: string;
+  readonly content?: string;
   /** ID of the tool call this result responds to. */
-  toolCallId?: string;
+  readonly toolCallId?: string;
   /** Optional tool/function name. */
-  name?: string;
+  readonly name?: string;
 }
 
 /**
@@ -1475,68 +1502,64 @@ export interface ToolMessage {
  * that constraint at the type level and rejects any other value on
  * deserialization.
  */
-export declare const enum ToolType {
+export declare enum ToolType {
   Function = "function",
 }
 
 /** Response from a transcription request. */
 export interface TranscriptionResponse {
   /** The transcribed text. */
-  text?: string;
+  readonly text?: string;
   /** Detected language (ISO-639-1 code). */
-  language?: string;
+  readonly language?: string;
   /** Total audio duration in seconds. */
-  duration?: number;
+  readonly duration?: number;
   /** Detailed segment-level transcription (if response_format is "verbose_json"). */
-  segments?: Array<JsTranscriptionSegment>;
+  readonly segments?: Array<TranscriptionSegment>;
 }
 
 /** A segment of transcribed audio with timing information. */
 export interface TranscriptionSegment {
   /** Segment index (0-based). */
-  id?: number;
+  readonly id?: number;
   /** Start time in seconds. */
-  start?: number;
+  readonly start?: number;
   /** End time in seconds. */
-  end?: number;
+  readonly end?: number;
   /** Transcribed text for this segment. */
-  text?: string;
+  readonly text?: string;
 }
 
-/**
- * Remove a previously registered custom provider by name.
- *
- * Returns `true` if a provider with the given name was found and removed,
- * `false` if no such provider existed.
- *
- * # Errors
- *
- * Returns an error only if the internal lock is poisoned.
- */
-export declare function unregisterCustomProvider(name: string): boolean;
-
 /** Token-usage accounting returned by the provider on each completion / embedding call. */
 export interface Usage {
   /** Prompt tokens used. Defaults to 0 when absent (some providers omit this). */
-  promptTokens?: number;
+  readonly promptTokens?: number;
   /** Completion tokens used. Defaults to 0 when absent (e.g. embedding responses). */
-  completionTokens?: number;
+  readonly completionTokens?: number;
   /** Total tokens used. Defaults to 0 when absent (some providers omit this). */
-  totalTokens?: number;
+  readonly totalTokens?: number;
   /**
    * Breakdown of tokens used in the prompt, including cached tokens served
    * at the provider's discounted cache-read rate. Absent when the provider
    * does not return prompt-token details.
    */
-  promptTokensDetails?: JsPromptTokensDetails;
+  readonly promptTokensDetails?: PromptTokensDetails;
+}
+
+/** 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",
 }
 
 /** User message in the conversation. */
 export interface UserMessage {
   /** Message content as plain text or array of content parts (text, images, documents, audio). */
-  content?: JsUserContent;
+  readonly content?: UserContent;
   /** Optional name for the user. */
-  name?: string;
+  readonly name?: string;
 }
 
 /**
@@ -1547,13 +1570,41 @@ export interface UserMessage {
  */
 export interface WaitForBatchConfig {
   /** Initial interval between polls, in seconds. */
-  initialIntervalSecs?: number;
+  readonly initialIntervalSecs?: number;
   /** Maximum interval between polls (backoff plateau), in seconds. */
-  maxIntervalSecs?: number;
+  readonly maxIntervalSecs?: number;
   /** Exponential backoff multiplier (e.g., 1.5 increases delay by 50% each poll). */
-  backoffMultiplier?: number;
+  readonly backoffMultiplier?: number;
   /** Optional timeout in seconds — polling fails if this duration is exceeded. */
-  timeoutSecs?: number;
+  readonly timeoutSecs?: number;
+}
+
+/**
+ * Register a custom provider in the global runtime registry.
+ *
+ * The provider will be checked **before** all built-in providers during model
+ * detection. If a provider with the same `name` already exists it is replaced.
+ * @throws Returns an error if the config is invalid (empty name, empty base_url, or
+ * no model prefixes).
+ */
+export declare function registerCustomProvider(config: CustomProviderConfig): void;
+
+/**
+ * Remove a previously registered custom provider by name.
+ *
+ * Returns `true` if a provider with the given name was found and removed,
+ * `false` if no such provider existed.
+ * @throws Returns an error only if the internal lock is poisoned.
+ */
+export declare function unregisterCustomProvider(name: string): boolean;
+
+export declare class ChatStreamIterator {
+  next(value?: undefined): Promise<IteratorResult<ChatCompletionChunk, void>>;
+  [Symbol.asyncIterator](): AsyncGenerator<ChatCompletionChunk, void, undefined>;
 }
 
-export declare function waitForBatchConfigDefault(): WaitForBatchConfig;
+export declare class LiterLlmErrorInfo {
+  statusCode(): number;
+  isTransient(): boolean;
+  errorType(): string;
+}