NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev
Unified LLM service layer for Flutter/Dart (Rust core, 327 providers, C ABI via dart:ffi)
Latest stable
0.6.1
Last release 17 days ago
05 Nov 2026
Ships fairly regularly
a new release about every 5 weeks
Nearly every release is documented
notes for 5 of 5 stable releases
Nothing withdrawn
no release was ever pulled
3 months old
5 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
fix(release): repair 0.6.0 packaging jobs by @eric8810 in https://github.com/arcships/aimux/pull/456
Full Changelog: https://github.com/arcships/aimux/compare/v0.6.0...v0.6.1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
One column per month.
Patch release for issues found against 0.6.0. ABI 1 / ops 1.0 are unchanged, but the manifest digest changes, so every binding in a process must come from 0.6.1.
forceServiceTier for OpenAI Chat and Responses: send the caller's service
tier for a deployment alias without the capability warning (#485).ToolResultOutput::Content gains optional isError (wire isError, omitted
when None), so a tool result that carries text, an image or a file can also
be a failure. Anthropic and Bedrock map it (#486).reasoning_content; the capability helpers
are public as aimux_providers::openai::language_model_capabilities
(#485, #492).reasoning_summary_part.added; each Responses output_text part keeps its
own text block; a late delta reopens it; replay groups one item's adjacent
text parts (#482).contentBlockDelta without exactly one known member
fails the stream; strict mode rejects unopened or unclosed content blocks;
a non-error messageStop plus metadata finishes the stream (#489).parse_tool_call::parse_json_input is public
(#479, #481).x-amz-content-sha256 and x-amz-security-token are
kept and signed as aws4fetch does (#480).--no-default-features, and
CI lints that configuration (#497).LanguageModelToolResultOutput.Content gains isError:
Java/Kotlin Content constructors take it as the first positional argument,
Swift's .content case becomes .content(isError:value:), and Rust struct
literals or exhaustive patterns need the new field. The wire JSON is
additive.fix(flutter): stop shipping LTO bitcode in the iOS static lib (pub.dev 256MiB) by @eric8810 in https://github.com/arcships/aimux/pull/196
Full Changelog: https://github.com/arcships/aimux/compare/v0.5.0...v0.6.0
Breaking release. 0.6.0 moves every binding onto the shared operations ABI (ABI 1 / ops 1.0) and aligns the public JSON with the Vercel AI SDK V4. Provider-specific constructors, the old error getters and the hand-written binding DTOs are removed; errors now carry the shared envelope and a native cause chain. See the 0.6 upgrade guide and the detailed sections below.
The Go binding's macOS cgo flags link CoreFoundation, which the
iana-time-zone dependency used by the release archive requires. The
Flutter publish job also builds its ABI test fixtures and Dart bridge
before flutter test, matching the CI job; both were missing from the first
0.6.0 tag run.
The static archives (libaimux_ffi.a for Go and the iOS xcframework
slices) are built with the staticlib-release profile, the release
profile without LTO. One command replaces the two old ones:
cargo build -p aimux-ffi --profile staticlib-release
# was: cargo build -p aimux-ffi --release (Go archive)
# was: cargo build -p aimux-ffi --profile ios-release (iOS slices; the profile is gone)
The archive lands in target/<triple>/staticlib-release/ instead of
release/ or ios-release/; the Go binding's cgo flags look there first,
and go generate downloads the release archive there. A static archive is
linked by the consumer's toolchain, so fat LTO only embedded every crate's
LLVM bitcode into it: the Linux Go archive as shipped goes from 194.2 MB
to 95.0 MB with the same linked code (RFC-0043 §5.1, §15.1). The shared
libraries (.so, .dylib, .dll) and the Node and Python extensions are
not changed by this PR.
Release and CI builds check the archive's workspace objects for bitcode
and print every artifact's byte size (scripts/check_native_artifact.py).
The shipped static archives carry no LLVM bitcode at all. rustup's sysroot
objects (std, alloc, core, ...) embed their bitcode whatever the profile
says, about 10 MB of each archive that no consumer's linker reads;
scripts/check_native_artifact.py --strip-bitcode removes those sections
with rust-objcopy (rustup's llvm-tools component) before the Go
archives are staged and the iOS slices are packed, and fails if any
bitcode is left. The Linux Go archive goes from 95.0 MB to 85.0 MB, the
iOS slices lose ~9.7 MB each; the code the consumer links is unchanged
(RFC-0043 §5.3 S1b, §15.7). CI's Go tests link the stripped archive.
The Go archives (libaimux_ffi-<target>.a for Linux and Windows) ship as
one merged object. rustc gives every function its own section, so the
527 members of the Linux archive spent a third of their bytes on section
tables and string tables; scripts/merge_archive.py links them once with
GNU ld -r --gc-sections, rooted at the 14 functions aimux.h declares
(the script checks that list against the symbols the archive defines),
strips the local symbols and writes the archive back with a single member.
The Linux archive goes from 85.0 MB to 58.8 MB; what the consumer links is
what a --gc-sections link of the old archive kept, and a consumer that
does not pass --gc-sections (Go's cgo link, for one) now gets that
smaller result too: the Go test binary drops from 39.1 MB to 27.6 MB. The
Windows gnu archive keeps its DLL import-library members as they are
(two import libraries for the same DLLs coexist in it, which ld -r
would reject) and is merged without --gc-sections (GNU ld's PE garbage
collection in a relocatable link leaves .pdata/.xdata of discarded
gcc-built functions dangling, and removed 77 KB); it goes from 57.1 MB to
48.1 MB, and a program linked against it grows by 160 KB (1%) because the
merged object carries every code member, not only the ones a link would
have pulled. The macOS archives and the iOS slices are unchanged (ld64's
-r does not dead-strip; they are inside the 70 MB and 64 MiB budgets
already). CI rehearses the Windows gnu archive on the Windows leg
(RFC-0043 §5.3 S1c).
The Node and Python extensions (aimux.node, aimux wheel) are built with
a size profile: opt-level = "s", fat LTO, one codegen unit, stripped. On
Linux x86_64 the published aimux.node goes from 39.9 MB (unstripped) to
17.4 MB (−57%) and the wheel's aimux.abi3.so from 30.6 MB (maturin publish already stripped it) to 17.3 MB (−43%); the six paired benchmark
scenarios in
bindings/node/bench/bench_profile.cjs and
bindings/python/bench/bench_profile.py stay within noise of the old
build. panic stays unwind, so a panic still surfaces as a JS exception
or a Python PanicException. npx napi build --release and
maturin build --release pick the profile up; no command changes.
Historical entries in this section. The V4 migration landed in layers, so some entries below name transitional APIs that were replaced again before the final 0.6.0 cutover — for example
aimux_error_provider_code,aimux_decide,aimux_provider_new,aimux_register_providers, NodeProviderConfig/ native constructors, anddescribeDecisionModel. Treat those names as history, not as 0.6 migration targets: the final surface is the ops ABI in docs/upgrading-to-0.6.md and the fourteen primitives inaimux-ffi/include/aimux.h.
anthropic::types::StreamErrorData::is_retryable is an
Option<Option<bool>>: Some(None) is an isRetryable sent as null,
None an absent one. code and status_code keep their types and are
Some(Value::Null) for a null. Code that read the flag adds a
.flatten().
FileSearchArgs::max_num_results (OpenAI and Azure file search tool) is an
Option<u32> instead of an Option<f64>, so maxNumResults: 5 goes out
as 5, as the AI SDK sends it, not 5.0. Code that set it from an f64
passes an integer now.
Errors keep their cause, as the AI SDK's cause. ApiCallError has
cause (.caused_by(..)): the transport error with its whole source chain
down to the OS error, the body parse error, or the error a response handler
returned; invalid_response_api_call takes that error instead of a
message, its text becoming the message. JsonParse, NoOutputGenerated, InvalidResponseData,
InvalidArgument, InvalidPrompt and Other are { message, cause }
(build them with AiMuxError::json_parse(..), invalid_argument(..), ...),
and InvalidToolInput.cause is the parse or validation error itself instead
of its text. A value that fails its schema is the new TypeValidation
error (AI_TypeValidationError, with the value), the cause of an
InvalidToolInput or of a structured output that does not match. A cause
is a nested AiMuxError or a SourceError chain of an OS, TLS or parser
error, and is what source() returns; RetryError::source() is the last
attempt. FetchError and download errors carry a SourceError without the
request URL, so their messages lose it too: error sending request for url (…) is now error sending request. Other messages are unchanged.
The ops error envelope carries the cause in all four domains, as the
payload's optional cause: the recording domain's source string becomes
cause: { message, cause? }, and the binding and protocol domains keep the
JSON parser's or serializer's error (InvalidWireJson,
ResultSerialization, InvalidParams, now struct variants). Every binding
exposes it natively: Node error.cause (AimuxCauseError for a nested
error, AimuxSourceError for an underlying one), Python __cause__ (a
nested error is its own exception class, an underlying error is
aimux.SourceError), Java/Kotlin getCause() (ErrorCause), Go Unwrap()
(*aimux.Cause), Swift and Flutter cause; a retry error's cause is its
last attempt. The C++ wrapper throws aimux::NativeError
(a std::runtime_error) with the error code and the envelope JSON.
aimux's public JSON equals the AI SDK's JSON. Struct fields serialize
camelCase (toolCallId, providerOptions, inputTokens); unions carry the
AI SDK's tag and strings ({"type":"text-delta"}, "tool-call",
"reasoning-file", Source sourceType, Warning/FileData/ResponseFormat/
stream parts no longer externally tagged); bytes are base64 strings;
optional fields are omitted instead of null and generate as field?: T;
AiMuxError is tagged by name
(AI_APICallError, AI_RetryError, ...). Vendor request and response types
and the OpenAI chat-completion output keep their vendor wire formats.
Persisted recordings and trace records change with the same rule;
recordings stay schema 2 and still read the snake_case envelope keys
aimux 0.5 writes (call_id, recorded_at, model_id, ...).
MoA failMode values ("best-effort", "fail-fast") and the recording
operation value "language-model" use kebab-case.
Bytes are base64 strings in the public JSON, as the AI SDK writes a
Uint8Array: image part image, file part data, FileBytes, speech
audio, image outputs, video binary data and audio/image/video inputs. An
array of numbers is no longer read. Bindings keep their byte-valued APIs
(Binary variants, Python bytes) and encode them at the JSON boundary
(#232 C33). Decision images (images[].data in a provider's options)
follow the same rule; Python decide encodes bytes image data there
(C33a).
JSON null is kept apart from a missing value where the AI SDK's type is
unknown: response and request body (language, speech, transcription,
embedding, reranking and search results), APICallError.data and the tool
approval request's inputSchemaInput read "body": null as a present null
and write it back, and omit the field only when it was missing. Python
serializes without exclude_none and keeps a set None of an Any field;
Go reads these bodies as json.RawMessage, and Error.Data changes from
any to json.RawMessage (nil when missing, null when null); Dart
gains hasBody / hasInputSchemaInput (#232 C34).
File content parts are the AI SDK's FilePart: one file tag whose data
is a tagged FileData ({type:"data"|"url"|"reference"|"text"}), a string
(base64 or a URL) or a bare {provider: id} reference. The file-base64,
file-url and file-reference parts are removed; write
{type:"file", data:{type:"url", url}} and so on. A reasoning-file
part's data also takes a bare string. A data: URL's media type wins over
the part's mediaType, and response messages carry files as bare base64
strings. Bindings replace the three part classes with a typed FilePartData
(#232 C35).
Generated files are the AI SDK's GeneratedFile: files[] holds
{base64, mediaType, providerMetadata?} instead of
{type:"data"|"url", ...}, and the text results' and stream's file /
reasoning-file parts are {type, file: GeneratedFile, providerMetadata?}.
ReasoningFileOutput is replaced by GeneratedFileOutput; the
provider-level raw.content keeps the V4 file
(LanguageModelFile: {mediaType, data}). Bindings gain a GeneratedFile
type with a bytes accessor (#232 C46).
Response timestamps are written as JavaScript's Date.toISOString()
("2025-03-06T13:50:19.000Z": UTC, milliseconds) instead of each
provider's own form (+00:00 offsets, nanoseconds, Bedrock's HTTP date,
Open Responses' Unix seconds). Reading one requires an RFC 3339 date-time;
other text is an error, so stored results or recordings with another form
no longer parse. In Rust the fields are Option<Timestamp>
(aimux_core::Timestamp) instead of Option<String>. Binding types stay
strings (#232 C48).
The text stream's text-delta and reasoning-delta parts carry their
text under text, as the AI SDK's TextStreamPart does, instead of
delta. tool-input-delta keeps delta, and so does the provider-level
StreamPart. Rust matches TextStreamPart::TextDelta { text, .. }; the
bindings' typed parts rename delta to text (Go TextDeltaPayload.Text,
Java getText(), Kotlin/Swift/Dart text) (#229 B9).
Provider options, provider metadata and provider references keep their
keys in insertion order end to end, as the AI SDK's JS objects do: Rust
holds them as IndexMap (see the provider options entry below) and the
bindings no longer sort them. Go: Tool.ProviderOptions and
TranscriptionSessionOpts.ProviderOptions are json.RawMessage instead of
map[string]json.RawMessage, and UploadFileResult.ProviderReference is a
ProviderReference (raw JSON, read with Get(provider)) instead of
map[string]string. Java's UploadFileResult defaults to a
LinkedHashMap. Swift's typed dictionaries remain unordered (#229 NP2-1).
A tool call or source outside content carries its AI SDK type tag: the
text results' toolCalls[] and an approval request's toolCall are
{"type": "tool-call", ...} (the AI SDK's TypedToolCall), and their
sources[] are {"type": "source", "sourceType", ...}. So are the repair
context's toolCall and the call apply_tool_call_repair returns (a
LanguageModelV4ToolCall). Reading accepts JSON without the tag and rejects
a different one. Rust keeps ToolCall and Source untagged and writes the
tag through wire::typed / wire::typed_vec / wire::Tagged; TypeScript
types the fields as the new TypedToolCall and TypedSource. Every
binding's standalone ToolCall, RawToolCall and Source writes the tag
(Go through MarshalJSON; Java, Kotlin, Swift, Dart and Python as a fixed
type field) (#229 NP2-7).
Tool-call input parsed from the model's argument text writes an integral
number as JavaScript does: 1e2 and 100.0 become 100, -0.0 becomes
0, as JSON.stringify(JSON.parse(text)) writes them, instead of
serde_json's 100.0. Other numbers are unchanged. Bindings that tell
integers from floats (Python int, Go raw JSON, Jackson IntNode) now see
integers (#229).
The text results' usage, steps and typed tool outputs follow the same JSON
rules. LanguageModelUsage (usage, totalUsage, each step's and the
finish / finish-step parts' usage) is camelCase: inputTokens,
inputTokenDetails {noCacheTokens, cacheReadTokens, cacheWriteTokens},
outputTokens, outputTokenDetails {textTokens, reasoningTokens},
totalTokens, raw?; an unknown count is omitted instead of null, the
two detail objects are always written. steps[] are camelCase (callId,
stepNumber, model {provider, modelId}, rawFinishReason?,
performance {stepTimeMs, responseTimeMs, timeToFirstOutputMs?, ...},
response {id, timestamp, modelId, headers?, body?, messages}). Tool
results, tool errors, tool-output-denied and tool-approval-response
parts write toolCallId, toolName, providerExecuted, approvalId; an
approval response's toolCall carries type: "tool-call", and the
results' toolResults[] are {"type": "tool-result", ...} (the AI SDK's
TypedToolResult; TypeScript TaggedToolResult). Recordings write the
outcome's usage the same way. Go, Java, Kotlin, Swift and Dart read and
write the camelCase keys with unchanged field names; Python dicts and Node
objects carry the new keys. Kotlin, Swift and Dart keep a parsed JSON
null output apart from no output (Kotlin JsonNull, Swift .null, Dart
hasOutput).
Output (the output option of generateText / streamText and
generate_object) is tagged by type, as the AI SDK names its output
modes: {"type": "text"}, {"type": "object", "schema", "name?", "description?"}, {"type": "array", "element", "minItems?", "maxItems?", ...}, {"type": "choice", "options"}, {"type": "json"}. The externally
tagged {"Object": {...}} form is no longer read.
Decisions follow the same JSON rules. DecideOptions and
DecisionCallOptions write maxRetries and providerOptions;
DecisionResult and DecideResult write rounding {probabilityDecimals, scoreDecimals}, providerMetadata and usage {inputTokens, outputTokens, totalTokens}, an unknown count omitted instead of null
(decision-result.ts:27-31). The model description of
aimux_decision_capabilities and every binding's describe is
{specificationVersion, provider, modelId, supportedQuestionTypes}. The
options and metadata aimux defines in a provider's namespace are camelCase
too: images[].mediaType, OpenAI choiceValues and safetyIdentifier,
candidate scoring's modelRevision, tokenizerRevision,
promptFormatVersion and encoded.<id>.{promptTokenIds, labelTokenIds},
and the metadata's probabilitySource and latencyMs; options a runtime
receives as given keep the runtime's names (keep_alive,
chat_template_kwargs, ...). Python's decide takes the JSON keys as
keyword arguments (maxRetries=0). Decision recordings write the options
and result this way, and replay refuses recorded options with snake_case
keys instead of ignoring them.
Request options reject keys they do not have (RFC-0042 §7.2):
GenerateTextOptions and its timeout, the options of the other
operations (embedding, speech, image, transcription, reranking, video and
its poll, search, file upload, decide), the MoA config, and the router
and transcription-session configs of the C ABI, Node and Python. aimux
0.5's snake_case keys (max_retries, timeout.total_ms, fail_mode,
provider_name) and typos fail naming the key instead of falling back to
the default. The Node and Python router and transcription-session configs
are camelCase, as the C ABI's are.
Middleware wraps generation and streaming with callbacks for both operations,
parameter transforms and provider/model/supported-URL overrides. Explicit
model and provider ids take precedence over middleware overrides.
NoSuchProvider carries provider_id, model_id, model_type and
available_providers. Node and Python OpenAI constructors use Responses
by default.
Vendor packages follow their upstream counterparts more closely. Visible
changes: Bedrock percent-encodes the model id in request URLs and writes
provider metadata under both amazonBedrock and bedrock; OpenAI embeddings
request encoding_format: "float" and no longer decode base64 vectors; the
Google provider result no longer carries a model id unless the API returns
one; an Anthropic mid-stream error event is forwarded as an error part
without a synthetic finish; each package sends its own user-agent suffix;
Mistral has no transform_request_body setting; the deprecated
text_embedding and text_embedding_model provider methods are removed.
SigV4Fetch::new takes a required SigV4Signing. Aws4Fetch signs like
aws4fetch 1.0.20, the signer of the AI SDK's AWS packages: user-agent,
content-type and its other UNSIGNABLE_HEADERS are sent but not signed,
and no x-amz-content-sha256 is sent. AllHeaders is the previous rule.
Bedrock and Anthropic-AWS sign with Aws4Fetch, Polly with AllHeaders.
Bedrock, Bedrock Mantle and Anthropic-AWS send the user-agents of
@ai-sdk/amazon-bedrock 5.0.100 and @ai-sdk/anthropic-aws 2.0.63 (the
package part is appended again by the transport).
The ai-sdk-provider-utils/<v> part of a pinned package's user-agent names
the provider-utils that the package's upstream package.json depends on, as
the AI SDK sends it. That is 5.0.51 for Azure, Bedrock, Cohere, DeepSeek,
Groq, Mistral, xAI and Google Vertex, and 5.0.53 for OpenAI,
OpenAI-compatible, Open Responses, Anthropic, Anthropic-AWS and Google. A
per-call user-agent keeps the package's part. The Vertex MaaS and xAI
sub-providers send ai-sdk-openai-compatible/3.0.59, the version
google-vertex depends on. Hugging Face sends ai-sdk-provider-utils/5.0.53
and no package part, as @ai-sdk/huggingface 2.0.62 does (now pinned in
VERSIONS.json). Other packages send ai-sdk-provider-utils/5.0.53.
to_chat_completion reads choices[].logprobs from the calling
provider's metadata namespace (Azure's azure, DeepSeek's deepseek)
and returns it in the Chat Completions wire shape, { "content": [...], "refusal": null }. It used to return the provider's raw token list. A
Responses result's per-part lists become one list, and a token without
bytes gets "bytes": null.
Security: OpenAI image edits download URL files (files and mask) with
download_blob, as @ai-sdk/openai does with downloadBlob. The download
goes through the download guard, so a private-network, loopback or
link-local URL is refused before any request, and it sends no headers. A
failed download is a status-code error rather than a parsed OpenAI error.
OpenAI chat providerMetadata.openai.logprobs holds the entries as the AI
SDK's chat schema parses them, {token, logprob, top_logprobs: [{token, logprob}]}: bytes is dropped, so to_chat_completion returns it as
null. A null content sets no logprobs.
Anthropic-AWS follows @ai-sdk/anthropic-aws 2.0.63 settings: the region
comes from the setting or AWS_REGION with no us-east-1 default; the
workspace id is required, from the setting or ANTHROPIC_AWS_WORKSPACE_ID;
with no auth, a request uses ANTHROPIC_AWS_API_KEY when it is set and
otherwise SigV4 with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and
AWS_SESSION_TOKEN. All of them are read when a request is made.
Anthropic gains the computer toolset of @ai-sdk/anthropic 4.0.71
(anthropic.computer_toolset_20260801). A member call in a response (for
example left_click) comes back as one call of the caller's toolset tool,
with the member name as action in its input and
providerMetadata.anthropic.toolsetName. Sent back as history, the call
keeps its input as it is, action included; a call without a string
action is still sent, named after the toolset, with a warning; the
toolset name is read from the call's tools or from
providerOptions.anthropic.toolsetName only.
Anthropic checks the args of the provider-defined tools that
@ai-sdk/anthropic 4.0.71 prepareTools validates (computer toolset,
advisor, text_editor_20250728, the three web_fetch and three
web_search versions): args that do not match fail the call with
InvalidArgument before any request, on Anthropic, Vertex and Bedrock
alike. anthropic::prepare_tools::{prepare_tools, prepare_tools_with_provider} return a Result.
Public surface (aimux-core, aimux-provider-utils): removed
recording::init_recording_from_env; made private the retry preparation
helpers and default constants, composite::{add_usage, build_aggregator_prompt, extract_text}, recording::new_call_id,
util::rfc3339_now, two session helpers, fetch_error_to_ai_mux_error,
extract_response_header_pairs, the SigV4 signing internals, the logging
internals and DEFAULT_MAX_JSON_RESPONSE_SIZE.
Proxy settings belong to a transport instance, not to the process
(aimux-provider-utils). init_proxy and its set-once global are
removed; ProxyConfig moves to fetch. ReqwestFetch::new(proxy) is a
transport with its own proxy and connection pool, given to a provider as
its fetch setting, as the AI SDK leaves routing to fetch; the
WebSocket counterpart is ws::TungsteniteConnector::new(proxy), given as
web_socket. set_default_transport replaces the default that providers
without fetch, built-in WebSocket connects and download hops read per
request. PinnedFetch::new takes the hop's ProxyConfig.
aimux_init_proxy (C ABI unchanged) and the Node and Python initProxy /
init_proxy now replace the default transport for later requests, every
time they are called, instead of taking effect only before the first
request.
Removed items the AI SDK has no counterpart for: aimux_core::ModelId
(and model_id, the Node ModelId type), the hidden
aimux_provider_utils::download_guard re-export (use
aimux_core::download_guard; same_origin stays re-exported), the
deprecated panicking converters convert_prompt_to_anthropic,
convert_prompt_to_anthropic_full, convert_prompt_to_openai_messages
and convert_prompt_to_openai_messages_with_mode (use the _fallible
forms), and the ResponsesSystemMessageMode alias (use
SystemMessageMode).
aimux_provider_utils::create_standard_json_error_response_handler is
removed. Failed-response handlers live in the provider modules, as the AI
SDK keeps groqFailedResponseHandler and DeepSeek's error schema in their
packages; build one with create_json_error_response_handler. The Groq
handler now reads only error.type as the provider code, and DeepSeek's
prefers error.code (a string or a number) over error.type.
LanguageModel::supported_urls and
LanguageModelMiddleware::override_supported_urls are async, as the AI
SDK's supportedUrls and overrideSupportedUrls may be a PromiseLike.
A wrapped model reads the override, else the inner model, when asked
instead of once at wrap time. The OpenAI-compatible SupportedUrlsFn
setting returns a BoxFuture<'static, SupportedUrls>.
The user operations download as the AI SDK's do, through a transport the
caller can replace (aimux-core, new public download module).
generate_text and stream_text read the model's supported_urls()
before the call and download each prompt file URL it does not cover (user
FileUrl parts and file items of tool outputs; not data: URLs), which
then reaches the provider as inline data; they used to pass every URL
through. The Cohere chat, Open Responses and xAI Responses models declare
the URLs their packages declare (HTTP(S) images; for xAI also PDF and
text), so those still reach the API as URLs. Codex models declare the
OpenAI Responses model's URLs (HTTP(S) images and PDFs) on both channels,
and the Hugging Face Responses model declares HTTP(S) images, as
@ai-sdk/huggingface does.
GenerateTextOptions::download takes a DownloadFunction (the AI SDK's
experimental_download) instead. AudioInput::Url is new:
transcribe downloads it with TranscriptionCallOptions::download, and a
transcription model given one returns AudioInput::url_error().
generate_video downloads every video returned as a URL with
VideoCallOptions::download and returns it as VideoData::Binary (it
returned the URL before). Without a download each operation uses
create_download(None), the guarded download (public HTTP(S) URLs only,
pinned hops, no provider credentials, 2 GiB limit), so a Vertex gs://
video result needs an injected download.
Provider results carry request and response information as the AI SDK does
(aimux-core). GenerateResult has request: Option<RequestInfo> and
response: Option<ResponseInfo>; ResponseInfo gains id and holds the
timestamp, model id, headers and body. StreamResult has request and
response: Option<StreamResponseInfo>. The flat request_body and
response_headers fields are removed and response is optional; the call
layer fills a missing id, timestamp and model id. GenerateTextResult
exposes request: RequestInfo and response: ResponseInfo, including
headers and body.
The prompt a provider receives is modelled by role (aimux-core), as the AI
SDK's LanguageModelV4Message. LanguageModelPrompt is
Vec<LanguageModelMessage>: System { content: String },
User { content: Vec<UserPart> }, Assistant { content: Vec<AssistantPart> },
Tool { content: Vec<ToolPart> }. The parts are TextPart, FilePart,
ReasoningPart, ToolCallPart, ToolResultPart. A provider sees one file
part, FilePart { data: FileData, media_type, filename }; the five
user-facing file variants are folded into it by
convert_to_language_model_prompt, which now returns Result and rejects a
part its role does not allow. LanguageModelPromptMessage is removed.
Recordings store the new prompt JSON: a system message's content is a
string and every file input is a file part. In TypeScript the provider
ToolResultPart / ToolResultOutput are LanguageModelToolResultPart /
LanguageModelToolResultOutput; the plain names are the user-facing types.
The user-facing ModelMessage is a union by role, as the AI SDK's
(aimux-core): System { content: String }, User { content: UserContent },
Assistant { content: AssistantContent }, Tool { content: ToolContent },
each with message-level provider_options, which now reach the provider
prompt (they were dropped). Each role has its own part union:
UserContentPart (text, image and the file variants),
AssistantContentPart (text, custom, the file variants, reasoning,
reasoning file, tool call, tool result, tool approval request) and
ToolContentPart (tool result, tool approval response). ContentPart,
MessageContent and Role are removed; ModelMessage::role() returns the
role name. A tool result is ToolResultPart { tool_call_id, tool_name, output: ToolResultOutput, provider_options }, the AI SDK's typed output
(text, json, execution-denied, error-text, error-json, content);
preliminary and dynamic are gone from it. A tool message can carry a
tool_approval_response { approval_id, approved, reason, provider_executed },
which reaches the provider only for a provider-executed tool, as upstream;
a tool message left empty is dropped. Wire format: the role and part tags
are unchanged; a tool result carries only output, an AI SDK output
object, and the earlier result / is_error fields are no longer read or
written; a part its role does not allow (an image in an assistant message, a
non-text system message, a string or text part in a tool message) is now
rejected when the prompt is parsed instead of when it is converted.
Provider options and provider metadata have one typed shape, the AI SDK's
Record<string, JSONObject>: SharedProviderOptions and
SharedProviderMetadata (ProviderMetadata is an alias) are one type,
NamespaceMap = IndexMap<String, JsonObject>, namespace to JSON object.
Like the AI SDK's JS objects they keep insertion order: a value serializes
with its keys in the order it was built or parsed.
SharedProviderReference is IndexMap<String, String> for the same
reason. They replace serde_json::Value, HashMap<String, Value> and the
per-part Option<Value>. Every provider_options / provider_metadata field of
content parts, messages, call options, tools, results and stream parts uses
them. {"namespace": {"key": value}} serializes as before; a value that is
not namespace -> object (a number, string or array under a namespace, or a
non-object at the top) is rejected when deserialized. Build one with
provider_namespace(ns, json!({..})).
ContentPart::Reasoning has no signature field any more, as the AI SDK's
ReasoningPart (text and provider_options only). A reasoning signature
travels in its provider's namespace (provider_options.anthropic.signature,
provider_options.bedrock.signature), which is where the providers already
read it; response messages no longer copy it to a top-level field. A
signature key in input JSON is ignored.
convert_to_language_model_prompt takes the called provider's id as a third
argument (aimux-core), the part of LanguageModel::provider() before the
first ., as the AI SDK passes it. A content tool output accepts the AI
SDK's deprecated items file-data, file-url, file-id,
file-reference, image-data, image-url, image-file-id and
image-file-reference (ToolResultContentPart; a file_id is a string or
a provider-to-id map, ToolResultFileId), and the conversion turns each
into a file part as upstream does: a file-url without a media type gets
one from the URL's extension, a URL keeps its given spelling as
original_url when normalizing changes it, and a string file_id becomes
a reference for the called provider (an error when there is none). These
items and a user image part log upstream's deprecation warning through
tracing.
generate_text and stream_text check the prompt and the response as the
AI SDK does (aimux-core). An empty message list is an InvalidPrompt
error (messages must not be empty). The prompt conversion combines
consecutive tool messages into one, merging the earlier message's
provider_options into its last part, and fails with the new
AiMuxError::MissingToolResults { tool_call_ids } when a tool call the
provider did not execute has no tool result or approval response before
the next user or system message or by the end of the prompt. A response
that breaks a required or tool tool choice fails generate_text with
the new AiMuxError::ToolChoiceViolation(ToolChoiceViolationError { tool_choice, finish_reason, provider, model_id, content }); stream_text
ends with that error as an Error part followed by a Finish part whose
unified finish reason is error. Error codes: the C ABI reports
MissingToolResults as AIMUX_E_INVALID_PROMPT and ToolChoiceViolation
as AIMUX_E_INVALID_RESPONSE_DATA; Node and Python raise them as
InvalidPromptError and InvalidResponseDataError.
Text results carry the AI SDK's core ContentPart (aimux-core), eleven
kinds, instead of the provider's GenerateContent: StepResult.content
(and so GenerateTextResult.content) is Vec<ContentPart>
(TextContent is removed; Node exports ContentPart, Python keeps the
TextContent model name). New kinds: ToolError(TypedToolError) and
ToolApprovalResponse(ToolApprovalResponseOutput). A provider tool result
is ToolResult(TypedToolResult { tool_call_id, tool_name, input, output, provider_executed, provider_metadata, dynamic, preliminary }), with the
input of the call it answers, or ToolError(TypedToolError { .., error, .. }) when the provider marks it as an error. A tool call that could not
be parsed is followed by a ToolError holding its error message, which
the response messages replay in a tool message as error text. Wire
format: {"File": {"file": GeneratedFile, "provider_metadata": ..}} (was
the bare GeneratedFile), {"ToolResult": {.., "input", "output", "provider_executed"}} (was result / is_error), and the new
ToolError / ToolApprovalResponse tags. GenerateContent is no longer
generic.
The custom content kind is a types::NamespacedKind at every layer
(AssistantContentPart::Custom, the provider CustomPart,
GenerateContent::Custom, ContentPart::Custom, StreamPart::Custom),
the AI SDK's ${string}.${string}: a kind without a . (for example
"compaction" instead of "openai.compaction") no longer deserializes.
The JSON is still a plain string; the TypeScript type is NamespacedKind.
Tool-call and tool-result types are unified, one per protocol layer
(aimux-core). A provider emits tool::RawToolCall (input is the raw
argument text) in GenerateContent::ToolCall(..) and
StreamPart::ToolCall(..), and tool::ToolResult in the ToolResult
variants; these variants are newtype variants now. A provider's do_stream
yields StreamPart with raw tool-call input. stream_text and everything
after it yield TextStreamPart with parsed input and invalid / error.
Call-layer streams consume provider response-metadata events internally;
TextStreamPart has no ResponseMetadata variant. RawToolCall moved from parse_tool_call to tool. Wire format:
enum variants keep their JSON shape; a provider-layer StreamPart::ToolCall
has a string input and no invalid / error; a
GenerateContent::ToolCall with a non-string input no longer
deserializes; the standalone tool::ToolResult gains a required
tool_name and optional dynamic / provider_metadata.
Source, generated-file and reasoning types are unified, one per concept
(aimux-core). result::Source, result::GeneratedFile and
result::ReasoningOutput are the payloads of GenerateContent::{Source, File, Reasoning} and StreamPart::{Source, File} (newtype variants now) and
the elements of sources, files and reasoning on GenerateTextResult
and StreamTextResultAggregated; StreamPart::ResponseMetadata wraps
types::ResponseMetadata. SourcePart, FilePart and ReasoningPart are
removed (TypeScript: Source, GeneratedFile, ReasoningOutput). Wire
format: enum variants keep their JSON shape; the top-level sources /
files / reasoning arrays gain provider_metadata (so the reasoning
signature is no longer dropped), and a source's url / title serialize as
null when absent instead of being omitted.
A repaired tool call that still fails to parse or validate is reported as
the AI SDK reports it: the original call stays invalid and carries the
replacement's own InvalidToolInput / NoSuchTool error, no longer wrapped
in ToolCallRepair (only a failing repair function is wrapped). This holds
for the repair_tool_call closure and for a host's repaired reply in every
binding.
CallOptions.tool_choice is the V4 object union
LanguageModelV4ToolChoice ({"type":"auto"}, {"type":"none"},
{"type":"required"}, {"type":"tool","toolName":..}); the user-level
ToolChoice ("auto" | "none" | "required" | {type:"tool",toolName})
stays on GenerateTextOptions. prepare_tool_choice converts one into the
other as the AI SDK's prepareToolChoice does, and generate_text /
stream_text now send {"type":"auto"} when no choice is given, with or
without tools (providers still drop it when there are no tools, except
open-responses, which sends it as upstream does). Provider authors match
on LanguageModelV4ToolChoice. Recordings store the object form, so an
ExactMatcher no longer matches recordings made before this change.
CallOptions.call_id and CallOptions::for_step are removed
(aimux-core); the V4 call options have no call id. The recording
correlation id is the recording context's call_id, and HttpRequest::new
takes it from there. Provider code that built HttpRequest { call_id: options.call_id.clone(), .. } uses HttpRequest::new(url, headers, options). The JSON is unchanged (both were internal and never serialized).
CallOptions.max_retries, CallOptions.timeout and
CallOptions.session_id are removed (aimux-core), as in the V4 call
options. They are settings of the generate_text / stream_text
operation: GenerateTextOptions keeps all three, and the JSON bindings
are unchanged. The operation runs its model calls inside
operation::OperationSettings::scope. The router and MoA take the child
retry count from OperationSettings::current(), and TraceLayer takes
the session id from it. Code that calls do_generate / do_stream on a
router, MoA or trace layer directly wraps the call in
OperationSettings { .. }.scope(..). Recordings keep the three keys in
input.options, and replay restores them.
generate_text accepts a provider tool result without its call only for a
provider tool that sets supportsDeferredResults: true (new optional
ProviderTool.supports_deferred_results), as in the AI SDK
(convert-language-model-content.ts:96-103); before, any provider tool of
that name was enough. stream_text passes such a result on without its
input, as streamText does (stream-language-model-call.ts:760-798). The
flag is not sent to the provider.
CallOptions.recording_context and DecisionCallOptions.recording_context
are removed (aimux-core): the V4 call options carry no recording context.
generate_text, stream_text and decide run the model call in
recording::RecordingContext::scope, and the stream in
RecordingContext::scope_stream; the router and MoA scope each child step
in a child context. HttpRequest::new and the trace layer read
RecordingContext::current(). Code that set the field on call options
wraps the call in RecordingContext::scope(Some(context), ..). The JSON is
unchanged (the field was never serialized).
ProviderTool.id is a types::NamespacedKind, the V4
${string}.${string} identifier: an id without a . (for example
"web_search" instead of "openai.web_search") no longer deserializes,
and NamespacedKind::new / parse check it when built in Rust. The JSON
is still a plain string.
A provider-executed tool::ToolResult whose result is null no longer
deserializes: the V4 result is NonNullable<JSONValue>.
Removed the generated ProviderName type in every binding (Rust enum, TS
const object, Go/Java/Kotlin consts, Swift enum, Dart consts, Python
Literal) and scripts/gen_provider_names.py. Provider names are plain
strings: Rust uses create_provider("groq", PresetSettings); bindings retain
provider("groq", ...), including overlay-registered names. The provider list lives in
docs/api/providers.md; Rust also gains
provider_names().
RetryError's text names the last attempt's message as the AI SDK's
getErrorMessage does: Failed after 3 attempts. Last error: Too Many Requests, not ... Last error: API call error: HTTP 429: Too Many Requests. The HTTP status stays a field of the attempt error.
Video poll settings belong to the operation, as the AI SDK's
generateVideo poll option (aimux-core, aimux-providers).
VideoModel::poll_config() and VideoPollConfig are removed; unset
VideoCallOptions::poll fields use the AI SDK defaults (5000 ms interval,
600000 ms timeout). RunwayML no longer paces its own polling (it used
2 s / 300 s, first as settings, then as package constants); pass poll per
call instead. Each status check, its retries included, now races
the time left in the poll budget and a hanging check fails with Timeout
"Video generation timed out after {timeoutMs}ms." as upstream.
Call-level usage and finish reasons follow the AI SDK (aimux-core). The
results of generate_text / stream_text / generate_object and the
TextStreamPart finish parts report usage as LanguageModelUsage
(input_tokens, input_token_details { no_cache_tokens, cache_read_tokens, cache_write_tokens }, output_tokens,
output_token_details { text_tokens, reasoning_tokens }, total_tokens,
raw) and the finish reason as the unified string ("stop",
"tool-calls", ...) with raw_finish_reason beside it. Usage is summed
over steps with add_language_model_usage. Provider results
(GenerateResult, StreamPart) keep Usage and FinishReason.
Recordings store the call-level usage for both the generate and the
stream path.
GenerateTextResult is built from steps, as the AI SDK's
(aimux-core). It holds steps: Vec<StepResult>, the summed usage and the
parsed output; everything else is an accessor: final_step(), content(),
text(), files(), sources(), tool_calls(), static_tool_calls(),
dynamic_tool_calls(), tool_results() (and the static/dynamic
variants), finish_reason(), raw_finish_reason(), usage(),
warnings(), response_messages(), output(), and the deprecated
reasoning(), reasoning_text(), total_usage(), request(),
response(), provider_metadata() that the AI SDK also deprecates.
StepResult carries the step's call id, model, content, finish reason,
usage, performance, warnings, request, response (with its messages) and
provider metadata. The raw provider result is removed, and
reasoning_text is None when there is no reasoning. The JSON form is a
snapshot: it writes the derived values next to steps, total_usage and
output, and only those three are read back.
Structured output is the output option, as the AI SDK's Output
(aimux-core). GenerateTextOptions::response_format is replaced by
output: Option<Output> (Text, Object, Array, Choice, Json); the
parsed and schema-checked value is GenerateTextResult::output().
generate_object is deprecated, as upstream, and is a wrapper over
generate_text with Output::Object; its GenerateObjectResult has
object, reasoning, finish_reason, usage, warnings, request,
response (GenerateObjectResponse: id, timestamp, model id, headers,
body) and provider_metadata, and no raw. It no longer repairs
malformed JSON before parsing.
TextStreamPart is the AI SDK's call-level stream part, its own enum and
no longer StreamPart<ToolCall> (aimux-core). The stream opens with
Start and StartStep { request, warnings } and closes with
FinishStep { response, usage, performance, finish_reason, raw_finish_reason, provider_metadata } and
Finish { finish_reason, raw_finish_reason, total_usage }; the provider's
StreamStart and ResponseMetadata parts are not forwarded. TextDelta
and ReasoningDelta carry text (was delta). Aborting the call ends the
stream with Abort { reason }. StreamTextResult::consume() returns a
GenerateTextResult; StreamTextResultAggregated is removed.
stream_text drops an empty TextDelta that carries no provider
metadata, as the AI SDK does (aimux-core); providers emit one, e.g. the
opening "content": "" chunk of OpenAI chat.
TextStreamPart carries the AI SDK's tool parts (aimux-core,
stream-language-model-call.ts:760-792). ToolResult is a
TypedToolResult (tool_call_id, tool_name, input? from the call it
answers, output, provider_executed, provider_metadata?, dynamic?,
preliminary?) instead of the provider's ToolResult; a provider result
marked is_error arrives as ToolError (TypedToolError, with
error), and an invalid client tool call is followed by a ToolError
holding its error message and dynamic: true
(stream-language-model-call.ts:709-725). ToolOutputDenied and
ToolApprovalResponse are added to complete the AI SDK's set; aimux's
stream does not produce them yet. Unlike upstream, the provider's preliminary flag is kept, so
a preliminary result stays out of the step content, as on the generated
path. A consumed stream's step content records the tool results, tool
errors and approval responses as they arrive (stream-text.ts:1529-1538,
:1648-1650), so an invalid call's tool error is inline after its call
there, where generate_text puts it after the content, as upstream does.
generate_text fails with Tool call {id} not found. when the model
returns a provider tool result whose call is not in the response and no
provider tool of that name was passed (aimux-core,
convert-language-model-content.ts:87-104). A result for a passed provider
tool is kept as a deferred result. The stream passes such results through,
without input, as upstream does.
The response messages write a tool approval request's
input_schema_input only when it differs from the call's input under the
AI SDK's isDeepEqualData (aimux-core, to-response-messages.ts:133-146).
Partial-JSON parsing returns one enum (aimux-core):
aimux_core::json_repair::parse_partial_json, ParsePartialJsonResult and
ParsePartialJsonState (also re-exported from aimux_core::util) are
removed; use PartialJson::parse(&str) (doc alias parsePartialJson). Its
variants Parsed(Value), Repaired(Value) and Failed carry the value, so
a value without a parse state or a state without its value cannot be built;
value() / into_value() return it for either successful variant.
Upstream's undefined-input state is the caller's Option:
parse_partial_json(text) becomes text.map(PartialJson::parse). Outcomes
and values are unchanged; fix_json is unchanged.
Rust (aimux-stream)
SseStream is now a thin adapter over the sse-stream crate (WHATWG
event-stream parsing), mirroring how the AI SDK's parseJsonEventStream
wraps eventsource-parser: \n, \r and \r\n line endings in any
mix, a leading UTF-8 BOM is stripped, a field line without : counts as an
empty value, an empty event: is None, an id containing U+0000 is
ignored, retry must be all ASCII digits, and a block is dispatched only
when it had a data line. There is no event size limit any more (as
upstream): with_max_event_size and SseError::FrameTooLarge are gone,
which fixes streams carrying multi-megabyte events (OpenAI Responses and
Gemini image generation). SseError::Stream carries the transport error
as its source instead of a String; SseError::Utf8 holds a
str::Utf8Error; SseError::Decode is added. Decoder errors (invalid
UTF-8, transport failure) now end the stream after being reported.
The response handler propagates terminal SSE decoding failures as
non-retryable ApiCall errors, preventing a normal finish or tool-call
finalization after truncated input. Invalid JSON inside an otherwise valid
SSE event remains a recoverable JsonParse error.
SseStream requires the body error type to implement std::error::Error + Send + Sync + 'static.NdjsonStream / NdjsonError: nothing in the workspace used them
and the AI SDK has no counterpart. tokio is now a dev-dependency only and
the unused direct serde dependency is dropped.StreamingToolCallTracker, ToolCallStreamPart and TrackerError are no
longer exported from aimux-stream; nothing in the workspace used them and
the AI SDK keeps the tracker in @ai-sdk/provider-utils, next to the
provider code that drives it. See aimux-provider-utils below.Rust (aimux-provider-utils)
StreamingToolCallTracker (plus StreamingToolCallDelta,
TypeValidation and TrackerError), a port of the current
@ai-sdk/provider-utils tracker, exported from the crate root only: the
streaming_tool_call_tracker and streaming_tool_call_argument_state
modules are private, and the argument state is internal, as upstream
exports only the tracker from its index. The previous aimux-stream version was
a port of an older, index-only tracker. Deltas are correlated by wire
id, index and function name (ambiguous deltas are dropped), ids are
de-duplicated with -N suffixes, generated ids come from the new
generate_id (upstream's default generateId; tool-call only when a
generator returns a blank id), blank function names are ignored, and
finish orders calls by index only when every call has one. It emits
aimux_core::StreamPart tool-input parts directly (ToolInputStart /
ToolInputDelta / ToolInputEnd / ToolCall); there is no separate
ToolCallStreamPart event type. StreamingToolCallDelta borrows from the
provider's wire type and flattens upstream's function object;
process and finish append to a caller-owned Vec<StreamPart>, and
finish consumes the tracker. The upstream extractMetadata /
buildToolCallProviderMetadata hooks are replaced by
StreamingToolCallDelta::provider_metadata, read from the delta that
starts a call. TrackerError converts into
AiMuxError::InvalidResponseData.@ai-sdk/provider-utils 5.0.55 (pinned in
fixtures/aisdk/VERSIONS.json): a named delta with an unseen id and empty
arguments continues an incomplete matching call, but starts a new call
once that call's structured arguments are complete; a continuation without
labels goes to the only matching call whose structured arguments are not
complete. Parallel same-name calls whose ids are missing or reused are no
longer merged into the first call.SigV4Fetch::with_clock takes a plain function (fn() -> DateTime<Utc>)
instead of a closure.Transformer, TransformStreamController and pipe_through, the
Rust form of the WHATWG TransformStream the AI SDK models build doStream
with (start / transform / flush; enqueue, enqueue_error, error,
terminate). pipe_through returns PipeThrough, a Stream that calls
start immediately and the transformer's other methods as it is polled;
TransformStreamController::new, drain and is_closed let a test drive
a transformer without a stream.StreamingToolCallTracker, StreamingToolCallDelta, TypeValidation and
TrackerError are removed. The tool-call matching they ported from
@ai-sdk/provider-utils 5.0.55 is now part of the OpenAI-style chat
streams in aimux-providers (OpenAI, OpenAI-compatible, DeepSeek, Groq,
Mistral), which emit the same parts as before.Rust (aimux-providers)
openai/model.rs, which serves every
registry-backed provider) correlates tool_calls deltas with the tracker
instead of by index alone: deltas are matched by wire id, index and
function name; a continuation without an id follows its call; indices
reused across parallel calls stay distinct; ambiguous deltas are dropped;
a call whose delta carries no id gets a generated id, as upstream, instead
of an empty string; a new call without a function name ends the stream with
InvalidResponseData (previously it started a call with an empty name).
DeltaToolCall.index is now Option<usize>.openai_compatible, the OpenAI (and
Azure) chat stream drives the tracker with @ai-sdk/openai's options:
type is validated when present, ids missing from the wire come from the
provider's generate_id, and DeltaToolCall.index is required again, so a
chunk without it fails to parse.OpenAIUrl, MessagesUrl, BaseUrl), provider headers
(ProviderHeaders, EndpointHeaders), endpoint sources (Vertex, Bedrock,
Polly) and supported-URL rules. A registry row selects its chat usage
accounting with profile.convert_usage ("alibaba", "moonshotai")
instead of a name match. Public settings, requests and errors are
unchanged; the closures callers pass in settings (transform_request_body,
generate_id, the compatible supported_urls, convert_usage and
metadata_extractor) are kept as given.PresetDescriptor gains a crate-private field (the row's usage converter),
so code outside the crate can no longer build one with a struct literal;
descriptors come from the registry JSON.doStream (OpenAI chat and Responses, OpenAI-compatible
chat and completion, Groq, DeepSeek, Mistral, Anthropic, Bedrock, Cohere,
Google, Vertex, xAI, Hugging Face, Open Responses) is a named stream struct
driven by pipe_through; emitted parts are unchanged, and a stream still
stops reading the body at an Anthropic message_stop or a
Google/Vertex/xAI/Hugging Face error event.Rust (provider factory, RFC-0036)
The native Decision/Jev extension from master is retained. Its typed
JevConfig / JevProvider::new entry point and Provider::decision_model
remain available. Decision replay now takes the caller's registry;
recordings contain provider identity only and no capability snapshot
(see the DecisionModelV4 entry). Decision retries use the core call-level
policy.
OpenAIProvider::language_model(id) (and so create_provider("openai", ..)
and the registry id openai:<model>) returns the Responses model, as
@ai-sdk/openai does. It returned the Chat Completions model. Call
.chat(id) for Chat Completions, for example against an endpoint that has
no /responses route.
The bindings' openai(...) constructors and the C ABI's aimux_openai_new*
are unchanged: they still create the Chat Completions model.
Removed crate-root exports provider(), provider_handle,
provider_from_env, provider_discovery, provider_registry_entry,
ProviderOptions, ProviderProfile, register_provider and
load_providers_from_json. Binding compatibility lives in
aimux_providers::provider; binding APIs are unchanged. Rust by-name
creation is create_provider(name, PresetSettings); provider_names()
lists names, and default_providers() supplies the map for
aimux_core::provider_registry::create_provider_registry(providers, options)
with provider:model ids by default.
Redirects are handled in the request helper layer, not in the transport.
An ordinary API call follows every redirect, as the AI SDK's postToApi
does under fetch's default redirect: "follow". A hop that leaves the
request's origin keeps only User-Agent, the rule the AI SDK's
fetchWithValidatedRedirects applies on the server, so no credential
header (authorization, x-api-key, x-goog-api-key, api-key, ...)
reaches another origin, and dropped headers stay dropped if a later hop
returns. FetchRequest.credentials (RequestCredentials::Include /
Omit, after the fetch credentials member) is Omit on such a hop, and
SigV4Fetch then sends it unsigned, without x-amz-security-token. Every
followed hop goes through the request's transport again, so SigV4 signs
the URL it sends. A Fetch never follows a redirect itself:
RedirectPolicy, FetchRequest.redirect and PinnedFetch::unpinned are
removed. Validated downloads keep their hop-by-hop guard.
Provider follows the AI SDK's ProviderV4: language_model,
embedding_model and image_model are required and return
NoSuchModel { model_id, model_type } when a vendor has no such modality;
transcription_model, speech_model, reranking_model and files are
optional (None = not offered); video and search stay aimux extensions.
Provider gains specification_version(), returning "v4" like
ProviderV4 and the model traits.
AI SDK model constructors return an Arc<dyn …>. Removed: Provider::name(),
LanguageModel::config_snapshot() and list_models on Provider.
Discovery is the separate ProviderDiscovery trait, accessed through
Provider::discovery(); supported_urls() is added to LanguageModel.
AI SDK-aligned packages remove XxxConfig, config builders, from_env(),
with_* methods and XxxProvider::new(...). Each package
has package-specific XxxProviderSettings, create_xxx(settings)
(validating package-specific settings, including base URLs, conflicting
credentials and template parameters) and a default instance xxx() where
the package provides one.
Models read a crate-private per-model config; there are no getters and no
snapshot. Fetch (HTTP) and package-specific WebSocket settings are
transport injection points. OpenAI, Anthropic and Google use fixed string
credentials and header maps, without a body-transform setting. The
OpenAI-compatible package exposes its upstream transform_request_body,
supported_urls and convert_usage hooks. Cohere and Mistral expose
generate_id settings. Package settings omit name and body transforms
when the upstream package does not offer them. Every request carries
ai-sdk-<package>/<version> in its user-agent.
For packages using the API-key loader, environment fallbacks are evaluated
on every request: api_key: None reads the package's environment variable, Some("") is
sent verbatim and never falls back to the environment, and a missing key
fails the call (not the factory) with AiMuxError::LoadApiKey { env_var, description }. A missing
chore(release): bump to 0.5.0 and document breaking changes by @eric8810 in https://github.com/arcships/aimux/pull/195
Full Changelog: https://github.com/arcships/aimux/compare/v0.3.0...v0.5.0
Breaking release. 13 PRs since 0.3.0: the cross-language error model stabilized behind one opaque C-ABI error pointer, the request pipeline aligned with the AI SDK (core-owned retries, timeouts, stream lifecycle, video start/status split), tool inputs parsed and validated at the Core boundary with host-side repair in every binding, WebSocket proxy support plus ElevenLabs realtime transcription, and SSRF hardening for provider-supplied download URLs.
Rust (aimux-core / aimux-provider-utils)
RetryError { maxRetriesExceeded | errorNotRetryable } preserves the
full attempt history; Full Jitter drives the exponential branch; server
retry-after hints are honored exactly. Providers declare policy
through retry_config(); Core executes it around
do_generate/do_stream. stream_text now requires a tokio runtime
(its pump task spawns unconditionally).VideoModel splits into do_start/do_status with a Core-owned poll
loop; generate_video validates n (0 is InvalidArgument before any
network call), batches by max_videos_per_call concurrently, and mints
one idempotency key per batch — billable starts replay safely.parseToolCall contract. Invalid
calls return as tool calls marked invalid: true with a typed error
(NoSuchTool / InvalidToolInput / ToolCallRepair; 16-variant
contract, compile-time exhaustive). GenerateContent::ToolCall.input
is String (was serde_json::Value); a compatibility deserializer
accepts the legacy object shape.to_chat_completion_stream_with_deferred_tool_calls, the
defer_tool_calls flag): the OpenAI stream always forwards provider
tool-input deltas and does not reflect repair (#192).send / send_timed / send_stream_timed /
send_with_retry_raw and the JSON-path ErrorStructure are replaced
by single-exchange helpers (post_json_to_api, post_form_data_to_api,
post_to_api, get_from_api) dispatching to typed response handlers —
exactly one fetch attempt and one recorded exchange per call; retry,
timeouts and backoff belong to Core (#164).C ABI
aimux_error_t * (#158): every
fallible function returns NULL on success (result in a trailing
out-parameter) or one owned error, released exactly once with
aimux_error_free(). The caller-allocated AimuxError struct,
aimux_error_clear and the error_value projection are removed. One
unified code space: AiMuxError 1–17 (4 retired slots, 14 = Retry),
RecordingError 100–105, C-boundary failures 200–206; a non-NULL error
never reports code 0.aimux_error_request_id is removed — request ids ride in response
headers (#164).aimux_tool_call_repair_context,
aimux_apply_tool_call_repair,
aimux_apply_tool_call_repair_to_result) let any host repair an
invalid call in its own language; safe to call from inside a stream
callback.Node / Python (native bindings)
instanceof across
sync throws, promise rejections, streams and workers; the serialized
errorValue/error_value companion is removed (#158).All eight bindings
VideoPollOptions
surface (#164); recoverable stream-frame errors keep the stream alive
(forwarded as data on the plain path, skipped on the chunk-typed
OpenAI path).repairToolCall (RFC-0035) (#192): the binding runs the
user's repair function in the host language and re-validates through
the pure core functions; non-streaming results are patched before
decoding, OpenAI-format outputs repaired then converted.Go
Close is no longer a join (#157): every native owner is an atomic
handle; Close never waits for an in-flight C call, and owners must
not be copied after first use (go vet flags it). Router/Moa
constructors reject any invalid member handle instead of silently
dropping it.ws_connect honors
the global ProxyConfig (HTTP CONNECT tunnel with Basic proxy auth,
no_proxy suffix matching); SOCKS and https-scheme proxies fail loudly
as UnsupportedFunctionality; wss tunnels run rustls with webpki-roots.
Proxy credentials never reach error strings; IPv6 proxy hosts work.scribe_v2_realtime streaming transcription
(RFC-0034 P2) (#184) — realtime WS sessions with commit-on-last-chunk
semantics, partial/committed transcript mapping, timestamped finals,
and 14 documented error events classified retry/terminal; non-pcm/ulaw
formats fail fast without connecting.{error:{message,code}} (ElevenLabs
FastAPI, AssemblyAI, Deepgram, fal, Hume) (#164).TranscriptionSession.Close vs
NextPart(-1), a backpressured stream vs Model.Close); FFI
Router/MoA silently dropped dead member handles mid-construction.aimux) (#155/#156).{} on the OpenAI wire instead of invalid JSON
(#165).invalid: true call instead
of aborting the stream (#165).Retry-After HTTP-date hints no longer read as "absent" through the
C ABI (#164).transcribe / rerank / search accept options
(max_retries, timeout were unreachable), and
search("cats", {query: "dogs"}) no longer silently searches for dogs
(#164).close() no longer deadlocks the
three threads (#192).staticlib never goes through cargo's link step — the 0.5.0 xcframework
hit pub.dev's 256MiB uncompressed package limit and was rejected. The
iOS build now uses an LTO-off profile and strips debug/local symbols:
each slice drops from ~128MB to ~15MB.fix_tool crate, and unused
workspace deps (schemars, proc-macro2, syn, quote) (#169).aimux_error_request_id (C ABI) — request ids ride in response
headers (#164).fix(release): flutter-publish embeds iOS xcframework from artifact root by @eric8810 in https://github.com/arcships/aimux/pull/29
Full Changelog: https://github.com/arcships/aimux/compare/v0.2.1...v0.3.0
Full Changelog: https://github.com/arcships/aimux/compare/v0.2.1...v0.3.0
Breaking release. 196 commits since 0.2.1: observability primitives (recording / replay / sessions / tracing), composite models, streaming transcription, a reworked error model across the C ABI and all eight bindings, a browser console, and a large provider-correctness sweep.
Rust (aimux-core / aimux-provider-utils)
AiMuxError::RateLimited gained message: String (now
RateLimited { retry_after_ms, message }); #[serde(default)] keeps
old payloads deserializable, but the generated TypeScript marks
message required — update exhaustive destructuring.GenerateTextOptions / CallOptions / StreamTextResult gained public
fields (session_id, recording/trace controls, stream-result metadata).
Use struct-update (..Default::default()) instead of exhaustive
initializers.shared_client() / shared_streaming_client() (aimux-provider-utils)
now return Result<&'static Client, AiMuxError>: client-build failures
(TLS backend, resource exhaustion) surface as a sticky, non-retryable
ApiCall instead of aborting the host process (#147).C ABI & the six FFI bindings (Kotlin / Java / Swift / Go / Flutter / C)
AimuxError out-parameter with typed
code + HTTP status + retry hint; the JSON error envelope, the streaming
on_error callback, and aimux_last_error() are removed.topK is now Double (was Long — 40.5 truncated
silently); published artifacts require JDK 17 (jvmToolchain(17)).topK likewise typed as double-valued (#106).init_recording_ring(0) now throws instead of a silent no-op
(consistent across all seven languages).Python / Node (native bindings)
next_part) / rejecting (nextPart) the typed hierarchy, and part
payloads are no longer wrapped in a {"Ok": ...} envelope — both now
match the C-ABI session shape and the other six bindings (#145/#150).
Code that parsed the envelope manually must catch the exception.Recorder /
JsonlRecorder plus a bounded in-memory RingRecorder with drop
counting; layer-B HTTP choke-point recording (per-attempt, streaming,
credential redaction); mock & request replay with matchers and the
aimux-replay CLI; cross-binding exposure via C ABI, Python, Node, Go,
Swift, Kotlin, Java, Flutter; config_snapshot() captures the minimal
provider/model identity. aimux_recording_try_flush FFI export reports
write failures (sticky first error) across the ABI (#133/#137).session_id groups related calls;
SessionStore + SessionInferer with query APIs in all bindings;
session-cache trajectory export.TraceLayer, verdict engine, and
RingTraceStore detect prompt-cache hits from provider headers
(vLLM / SGLang / LMCache behaviours), with cluster/route-aware gating;
exposed in every binding.aimux-cli cache-probe client (RFC-0025) — offline / session /
provider probing over the trace store.generateOpenAIOutput
across all eight bindings.Provider::list_models and
get_model_specs with reasoning/capability metadata.LanguageModel wrappers, usable from every
binding with zero call-site changes:
RouterModel (RFC-0021) routes each call to one child model through a
pluggable Router strategy (built-ins: RuleRouter, WeightedRouter)
with automatic fallback to the remaining children on failure.MoaModel (RFC-0022) implements mixture-of-agents in a single call:
reference models run in parallel, their outputs are spliced into an
aggregator prompt, and the aggregated answer is returned — no agent
loop involved.streamText aggregation, generateObject,
top-level result aggregation (reasoning / sources / files /
responseMessages), proxy configuration, rawFinishReason, logprobs,
usage.raw, streaming warnings, includeRawChunks,
ResponseMetadata.timestamp.aimux-web console (RFC-0029) — browser-based model-call testing
and trace visualization, shipped as release artifacts.0600, masked hints only, and plaintext
entry is loopback-gated (non-loopback binds fall back to env:VAR
references).ProviderWithConfig (Go), full ProviderOptions for
provider() (Python), optional recording-ring capacity in every
language.Provider correctness
functionResponse.name now uses the tool name instead of the
opaque call id (multi-turn tool calls no longer 400) (#127).Finish part
(contract parity with OpenAI/Google) (#128); assistant reasoning —
including its signature — is echoed back when thinking is enabled
(#131/#138).try_flush instead of a silent Ok, and the completion barrier requires
the input record before finalizing (#110/#133).ApiCall/NoSuchProvider fields with unified retry
classification (#94); retry config honored for vertex/anthropic-aws;
credential-source accuracy for xai/open-responses; real provider
identity surfaced on the OpenAI chat path.nextPart is
actually reachable (#116/#144); close-race read/write locks for handle
types in Kotlin/Java/Flutter; Python exposes recording / mock-replay /
get_model_specs with typed exceptions.Tests & fixtures
top_k drift that hid for
months is regression-locked (#106).# Errors docs),
rustdoc -D warnings in CI, ts-rs type-drift check, ProviderName
generator-drift check.docs/quality-audit/round4/; unused-dependency sweep; rustdoc errors
47 → 0.aimux_last_error() (C ABI) — replaced by the AimuxError out-param.on_error callback.fix(go): correct Go binding doc examples that fail to build/run by @cunninghamcard-bit in https://github.com/arcships/aimux/pull/11
Full Changelog: https://github.com/arcships/aimux/compare/v0.2.0...v0.2.1
Full Changelog: https://github.com/arcships/aimux/compare/v0.2.0...v0.2.1
Patch release following 0.2.0. First Maven Central (Java + Kotlin) and pub.dev (Flutter) release; Rust / Node / Python re-released to stay aligned with the new bindings.