Rig 0.42.0 is live!

[gold-silver-copper]

Rig v0.42.0 released!

77 PRs merged since 0.41 — +207k/−35k lines, and the replay-cassette corpus grew from 508 to 1,793 recordings. Big thank you to all our contributors 🫡

The Generics Are Gone

#2257

Agent<M> is now Agent. CompletionResponse<T> is now CompletionResponse. Extractor<M, T> is Extractor<T>. The provider type no longer leaks into your agent's type, which means an agent can now swap its model — or its whole provider — at runtime, per run, or per model call from a hook.

Completion responses are normalized at the provider boundary, and the agent erases the model type at construction.

// Before
let agent: Agent<openai::CompletionModel> = client.agent("gpt-5.6").build();
let extractor: Extractor<openai::CompletionModel, Person> = ...;

// After
let agent: Agent = client.agent(openai::GPT_5_6).build();
let extractor: Extractor<Person> = ...;

The provider-native payload didn't disappear — it moved to inherent raw_completion / raw_stream on each provider model, and (see below) it now also travels on every hook event as serialized raw.

Swap Models and Providers at Runtime

Because the agent stores a handle rather than a type, the model behind it can change without the agent's Rust type changing. Three ways to do it:

use rig::prelude::*;
use rig::providers::{anthropic, gemini, openai};

let openai = openai::Client::from_env()?;
let anthropic = anthropic::Client::from_env()?;
let gemini = gemini::Client::from_env()?;

// 1. Build against one provider…
let mut agent = openai
    .agent(openai::GPT_5_6)
    .preamble("You are a terse assistant.")
    .build();

// …and replace the default model for every future run, on a different provider.
agent.set_model(anthropic.completion_model(anthropic::CLAUDE_SONNET_4_6));

// 2. Or override the model for a single run only.
let answer = agent
    .runner("Summarize this in one line.")
    .using_model_value(gemini.completion_model(gemini::GEMINI_2_5_FLASH))
    .run()
    .await?;

// 3. Or route per model call from a hook — retries, cost tiers, fallbacks.
struct FallbackOnRetry { fallback: ModelHandle }

impl AgentHook for FallbackOnRetry {
    fn on_model_select(&self, _ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction {
        // `previous_model` is set once an attempt has been issued in this run.
        if event.previous_model.is_some() {
            ModelSelectionAction::select(self.fallback.clone())
        } else {
            ModelSelectionAction::continue_run()
        }
    }
}

AgentHook::on_model_select runs once per model-call boundary — including retries and post-tool calls — after the completion-call hooks, so it sees the merged RequestPatch, the prompt and history, the run default, the candidate chosen by earlier hooks, and the model that executed the previous attempt.

OneOrMany Is Gone, and Content Is Tagged

OneOrMany<T> was a 743-line non-emptiness promise whose is_empty() returned a hardcoded false and whose deserializer rejected []. #2273 deletes it: every content list is Vec<T> — Message content, ToolResult::content, chat_history, CompletionResponse::choice, EmbeddingsBuilder::build's output, InsertDocuments. Serialization is byte-identical (zero cassette churn); the non-emptiness rule moves to a request-boundary validator (CompletionRequest::validate_message_content) on the way out and require_non_empty guards on the way in. Seven production sites that minted AssistantContent::text("") as padding are gone with it.

#2277 then makes AssistantContent internally tagged ("type": "text" | "image" | …) and turns provider extras into a named Option<AdditionalParams> field that is non-empty by construction ({} and null canonicalize to None).

Provider Consolidation and Architecture

The provider layer went through a dozen consolidation passes that deleted on the order of 8,000 lines of duplicated production code. The pattern is the same everywhere: one shared driver in providers::internal, and per-provider code reduced to the constants and hooks that actually differ.

• Shared drivers: send_completion owns every unary completion tail (send, status split, envelope decode, telemetry) at ten call sites; sse_frames / open_wire_stream replace six hand-rolled SSE loops; shared model-listing (with one paginated loop and cursor-repeat / budget protection — #2339), transcription, image-generation, audio-generation, and error-envelope drivers.
• Macros for the tables no function can factor: impl_capabilities!, impl_default_provider_builder!, impl_provider_client!, impl_model_lister!, provider_error_enum! — 49 hand-written ProviderBuilder / ProviderClient impls became invocations in one PR alone.
• De-forks: xAI dropped its private Responses driver for the shared generic one; Copilot dropped its forked chat types; Bedrock's unread mirror subtree (3,770 lines) is macro-generated; the four Anthropic-compatible gateways (MiniMax, Moonshot, Xiaomi MiMo, Z.ai) share one base-URL table.
• rig-agent: AgentRunner holds the agent's AgentConfig instead of a hand-copied mirror of 15 of its fields (#2327), and a 17-positional-argument request builder became 6.

Two API-cleanup notes: #[non_exhaustive] is removed from the whole workspace (#2335) — matches are exhaustive again, struct literals compile again. Basically I really don't like #[non_exhaustive] and AI agents always freak out when they see it, so bye bye.

1,000+ New Cassettes

The replay corpus went from 508 to 1,793 recorded provider interactions — 350 OpenAI, 336 Anthropic, 222 Gemini, 222 OpenRouter, 177 Mistral, 125 DeepSeek, 82 Doubleword, and coverage for xAI, Venice, Cohere, Ollama, Copilot, Bedrock, Groq, Perplexity, llamafile, and ChatGPT. Every one is recorded against the live API and replayed byte-for-byte in CI, with request-body assertions, and a cassette_cache_prefix guard that walks the whole corpus and asserts each multi-turn conversation's earlier request prefixes the later one.

We did this because it finds bugs. A partial list of what live recording caught this cycle:

• Gemini never received temperature or max_tokens (#2283) — Option::map on a None generation_config silently dropped both — and separately injected a hardcoded maxOutputTokens: 4096 and temperature: 1.0 into requests that set neither (#2324). Both are fixed. If you set these before and saw no effect, they apply now; if you relied on the 4096 cap, set one.
• Anthropic thinking tokens were reported as 0 (#2334); streamed input_tokens from Anthropic-compatible gateways were read from the wrong frame (#2279, reported by @shlim33); Anthropic and Gemini model listing could loop forever on a cursorless has_more / empty nextPageToken.
• Mistral silently dropped images, audio, and documents before the request left rig (#2331, reported by @ac-machache), plus a wrong verify path, a wrong batch cap, ndims() == 0, and truncated tool calls destroying the whole response (#2337).
• OpenAI structured-output refusals killed the turn as "empty response" on Chat Completions and OpenRouter (#2332, #2358); reasoning models were being sent max_tokens instead of max_completion_tokens; image/TTS additional_params were being ignored.
• A finish_reason: "length" turn cut mid-JSON in a tool call failed the entire blocking decode on OpenAI, DeepSeek, Mistral, and OpenRouter — text, usage, and complete sibling calls with it (#2359, 450 cassettes on its own).
• Cohere was sending request shapes the v2 chat API rejects — externally-tagged tool results, mistyped documents, no max_tokens, wrong tool_choice spelling (#2263 by @rleisti, #2302).
• Gemini discarded whole turns that used the built-in code-execution tool, glued chain-of-thought onto the transcript under includeThoughts, and dropped trailing thought signatures (#2328). Anthropic lost stop_sequence on the streamed terminal and rejected a legitimately empty stop-sequence turn (#2329).
• Bedrock shipped 38 model ids that were no longer invocable (#2309) and discarded guardrail traces and request ids (#2311); a two-tool streaming cassette from @kjones (#2251) closed an end-to-end gap.
• Doubleword reported ndims() == 0 for its only embedding model (#2356).

Observability: Identity, Headers, Raw Payloads, Finish Reasons

A cluster of features makes what a provider actually said reachable from an agent run without reaching into provider types:

• Response identity (#2313, requested by @domenic-donato): CompletionResponse and StreamFinal carry provider_request_id — the transport request id read off response headers, the one provider support asks you for — alongside response_id / message_id, bundled as ResponseIdentity and threaded to every agent hook event and completion_calls entry. It survives onto failed calls too (#2315), and every capability error gains a provider_request_id() accessor.
• Response headers on errors (#2333): Retry-After and friends now reach provider_response_headers() on completion, transcription, image, audio, and verify() errors — including 2xx error envelopes from gateways.
• Raw provider payload, everywhere (#2367): CompletionResponse::raw (and the streamed terminal) carry the serialized value raw_completion / raw_stream would have returned, and hook events expose it as raw: &serde_json::Value. openai::CompletionResponse::deserialize(event.raw) gets you the typed provider response back from inside a hook. See the new raw_response_hook example.
• Termination metadata to hooks (#2341): ModelTurnFinished carries the normalized finish_reason and the attempt's own max_tokens, which is what you need to write retry-on-truncation as a hook — see the retry_on_truncation example.
• Streaming reasoning is a hook event (#2282): AgentHook::on_reasoning_delta, with a stable per-part correlator.
• A truncated, answerless turn now fails loudly (#2324): a run whose final turn hit Length / ContentFilter with no text, tool call, or image returns an Err naming the remedy instead of Ok(""). On the OpenAI-compatible wire the underlying completion() call succeeds with an empty choice and the finish reason (#2332), so direct callers should check finish_reason().truncated_output().

Providers

Venice joins as a new provider (#2306) on the shared OpenAI path with native image generation, TTS, and ASR, and 33 cassettes from day one.

Anthropic gains opt-in strict tool use (#2296, requested by @kanyesthaker) with a schema-subset transformer that rewrites schemars output into what Anthropic's strict mode accepts (84 cassettes pin exactly where the API 400s), and per-breakpoint cache TTL (#2312, requested by @domenic-donato) so a 1h static prefix no longer drags the volatile conversation tail to 1h with it; usage now parses the per-TTL cache-write breakdown and reasoning_tokens.

Cohere gains image embeddings via a new ImageEmbeddingModel trait (#2304). Voyage AI exposes input_type / truncation / output_dimension (#2343 by @sergiomeneses). Groq, Moonshot, and MiniMax gain model listing. OpenAI merges additional_params tools into the typed tool list instead of clobbering it (#2294), and rejected Responses websocket upgrades keep their status, body, and request id (#2338).

EmbeddingsBuilder returned documents in HashMap order — arbitrary per process — and a document straddling a batch boundary could get its own embeddings shuffled. Both are fixed (#2344 by @sergiomeneses, #2348); output is now in input order at both levels, and a provider returning fewer embeddings than sent is an error rather than a silent truncation.

Dependencies, Packaging, CI

• Dependency requirements are floors now (#2369, from @Sytten's #2195): 86 workspace requirements dropped from "whatever patch was current" to the lowest version rig actually needs, so taking a rig release no longer forces cargo update on unrelated crates. A nightly job builds against the declared floors so they stay true.
• Security advisories cleared (#2342) and lopdf moved to 0.44 (#2297 by @mccormickt), which also lets --all-features build for browser wasm (#2319).
• CI split into a fast PR gate and a nightly --all-features sweep, dropped every API key from CI (cassettes make them unnecessary), and finally runs rig-derive's test suite, which had been running in no job at all (#2268, #2271, #2275).

Upgrading

Please read MIGRATING.md. The 0.41 → 0.42 section is long because we tried to write down every observable change, including the ones that only show up as different bytes on the wire.

Huge thank you to everyone who made 0.42 happen:

• @ac-machache
• @codyw912
• @domenic-donato
• @gold-silver-copper
• @kanyesthaker
• @kevinten10
• @kjones
• @lass274
• @mccormickt
• @nazq
• @nilennoct
• @rleisti
• @sergiomeneses
• @shlim33
• @suxiaoshao
• @Sytten
• @tripplen23
• @zentradev-rabih

And thank you to everyone who opened issues, reviewed the large architectural changes, and tested providers.

We build Rig, Rig builds us!

Full changelog: v0.41.0...v0.42.0

[sergiomeneses]

Great work!!!