Siumai — Provider-faithful AI model interfaces for Rust
Siumai (烧卖) is a type-safe Rust workspace for integrating AI model providers. Its application
facade starts with a typed Siumai::builder() provider hub, retains six small provider-neutral
model-family interfaces for portable code, and keeps provider-specific resources and modes on their
concrete owners. Registry and runtime are optional integrations, not hidden parts of the builder.
What Siumai provides
- Provider-direct construction, typed options, annotations, metadata, and native resources
- Typed provider hubs and family clients for concise direct application calls
- Provider-neutral family traits for language, embeddings, images, reranking, speech, and transcription
- Established language streams with explicit terminal outcomes and cancellation
- An optional immutable Registry for routing caller-configured providers
- An optional runtime for tool loops, structured output, approvals, budgets, and durable runs
- Shared transport and protocol crates with bounded, sanitized error handling
Install
The examples in this README target 0.11.0-beta.12.
Users staying on 0.11.0-beta.10 should follow the old side of the
migration map.
Enable only the provider and integration features that the application uses:
[]
= { = "=0.11.0-beta.12", = false, = ["openai"] }
= { = "1", = ["rt-multi-thread", "macros"] }
The typed provider hub was introduced in 0.11.0-beta.11; the published
0.11.0-beta.10 crate does not contain it.
The facade's default features are registry and runtime; no provider is enabled by default. Add
registry or runtime explicitly when using default-features = false.
The current workspace is a breaking public API reset. Existing users should read
docs/migration/siumai-next.md before updating.
Quickstart: typed direct call
For ordinary application calls, configure one provider, bind one model family, and use the family client method:
use GPT_5_6;
use Siumai;
async
OpenAI .language(...) means Responses; use .chat_completions(...) explicitly for Chat
Completions. Gemini .language(...) means Interactions; use .generate_content(...) explicitly
for Generate Content. Neither provider infers an API mode from the model name.
Provider features
Provider features describe the exact retained slice, not every product sold under a vendor name:
| Feature | Current public scope |
|---|---|
openai |
Responses and Chat language, embeddings, image generation, buffered speech, final-result transcription, and typed Conversations/Files/Vector Stores/Skills resources |
openai-realtime |
Experimental provider-owned OpenAI Realtime bootstrap and session transport |
openai-responses-websocket |
Experimental persistent OpenAI Responses WebSocket sessions; also enables openai |
anthropic |
Messages plus Files, Message Batches, token counting, and Skills metadata/version CRUD with bounded uploads |
google |
Gemini Interactions/GenerateContent language, text and native multimodal embedding, image, speech, Files, and Veo |
google-vertex-anthropic |
Anthropic Messages on Google Vertex AI |
alibaba |
Chat, Responses, Anthropic-compatible Messages, embeddings, and experimental Wan video |
moonshotai |
Moonshot AI's Kimi Chat Completions, Partial Mode, and typed Files lifecycle |
volcengine |
Volcengine ARK Chat Completions/Responses, portable Image, Remote MCP, and typed Video tasks |
openai-compatible |
Explicit generic or custom OpenAI-compatible endpoints |
groq |
Chat, Responses, transcription, buffered Orpheus speech, Remote MCP, and URL-audio/translation resources |
xai |
Responses-primary language, explicit Chat Completions, image, speech, transcription, Files, and video jobs |
minimax |
Three language modes, portable image/speech, Responses input-token counting, and typed files/media/voice resources |
deepseek |
Chat, beta Chat strict/prefix, Responses, and Anthropic-compatible Messages language modes |
cohere |
Embeddings, reranking, and provider-native audio transcription |
deepgram |
Final-result transcription and buffered Aura speech synthesis |
elevenlabs |
Buffered speech synthesis and final-result/batch transcription |
See the provider support policy for fidelity, stability, and host-control-plane boundaries. Model identifiers remain open; constants are dated hints rather than allowlists. The beta.12 model advisory refresh records dated hints and lifecycle corrections without expanding protocol support claims.
Each row is a claimed slice complete inventory for this release, not a provider platform complete claim. Surfaces outside a row's exact scope are intentionally deferred and remain
available for future provider-owned additions without widening the portable core.
Custom HTTP endpoints
Enable openai-compatible explicitly; it is not included in all-providers. The
OpenAiCompatibleProfile::custom(provider, base_url, replay_domain, mode) accepts HTTP or HTTPS
for a developer-trusted origin, whether it is public, LAN, or loopback. No network classification
or separate facade switch is needed. Pass the profile through .openai_compatible().profile(...)
and choose .unauthenticated() or .api_key(...) as the service requires. Provider identity,
non-secret replay domain, model ID, and API mode remain explicit; a custom URL never implies an
official provider claim.
These convenience APIs are available starting with 0.11.0-beta.12. Never use unchecked tenant
or user URLs as trusted configuration. Prefer HTTPS:
HTTP sends prompts, responses, and credentials in cleartext. Resource downloads and CONNECT
proxy routing do not inherit this trust, and their restrictions remain unchanged.
Published beta.11 callers can keep local_explicit(...) for loopback, or custom_endpoint(...)
with an explicit private-network grant for LAN, and
.credential(OpenAiCompatibleCredential::unauthenticated()) when no key is needed. Those strict
paths are unchanged; public_custom(...) still requires HTTPS and public addresses. See the
endpoint guide for complete examples and the compatibility
section, or run the offline example.
Provider HTTP transport settings and trusted CONNECT
Provider features automatically enable the facade's narrow siumai::transport namespace. The
standalone transport feature exposes only provider HTTP configuration and payload-free attempt
observation; authenticated execution, request plans, raw responses, resource downloaders, and
socket primitives remain in their owning crates.
use Duration;
use ;
let settings = default
.with_retry_policy
.with_call_timeout
.unwrap;
assert_eq!;
The default route is Direct. Select a trusted forward proxy explicitly without consulting process proxy variables:
use ;
let route = trusted_connect;
let settings = default
.with_route
.unwrap;
assert!;
The same cloneable settings value can be reused across configured providers. Its observer events contain structural attempt and retry state only—never URLs, headers, credentials, payloads, or provider identity.
Direct validates provider DNS and peers locally. Trusted CONNECT validates the proxy endpoint and
peer, then trusts that proxy for destination DNS/peer selection while preserving the logical
provider URL, inner TLS, credential audience, replay proof, deadlines, and bounds. Proxy Basic
authentication is separate from provider authentication and rotates by rebuilding the configured
provider. Streamable HTTP MCP reuses only the route type through McpClientConfig; WebSocket,
Realtime, and provider-returned external downloads remain Direct-only.
Verified facade journeys
The checkout contains six compile-checked, offline examples, including the custom endpoint example:
openai_flagship.rscombines typed Responses options and prompt-cache intent, complete portable response inspection, Files/Responses resources, and a model-native Responses call;anthropic_flagship.rscombines typed Messages/cache/file intent, complete portable response inspection, model cache prewarming, and provider-owned Files and Message Batches;provider_switching.rsconstructs OpenAI, Anthropic, and Gemini typed hubs and uses the identicalclient.generate(...)application call;registry_switching.rskeeps generic and Registry-resolved switching separate and makes the one-way erasure boundary explicit;trusted_connect_route.rsconstructs the trusted route and compiles a provider settings handoff without credentials or network I/O;self_hosted_http.rsuses thecustomAPI to build a loopback HTTP compatible provider and model handle without credentials or a server.
Compile or execute them independently with only their documented feature set:
cargo check -p siumai --example openai_flagship --no-default-features --features openai -j 1
cargo check -p siumai --example anthropic_flagship --no-default-features --features anthropic -j 1
cargo check -p siumai --example provider_switching --no-default-features --features openai,anthropic,google -j 1
cargo check -p siumai --example registry_switching --no-default-features --features openai,registry -j 1
cargo check -p siumai --example trusted_connect_route --no-default-features --features openai -j 1
cargo check -p siumai --example self_hosted_http --no-default-features --features openai-compatible -j 1
The switching and flagship examples use synthetic credentials and never poll provider request futures, so checking or running them does not perform a billable network call.
OpenAI Responses WebSocket is intentionally provider-owned rather than a portable family. Enable
openai-responses-websocket, acquire a Responses model, call model.websocket()?, and connect the
returned configuration. One connection accepts one generated turn at a time, supports sequential
continuation and native-only warm-up, and uses the same canonical Responses decoder as HTTP SSE.
Custom HTTP providers must configure a WebSocket endpoint explicitly and do not inherit OpenAI's
official session support claim.
Choose the narrowest public surface
- Start ordinary direct calls with
Siumai::builder(), then bind a family client from the typed provider hub. - Use the root
siumai::{language, embedding, rerank, image, speech, transcription}modules for generic, dependency-injected, trait-object, or Registry-resolved code. - Use
client.provider()orclient.model()for provider-native resources, sessions, responses, and explicit mode-specific methods before type erasure. - Add Registry only when the host needs deterministic local route lookup.
- Add runtime only when the host needs provider-neutral multi-step orchestration.
Provider-specific behavior stays available through typed call options, typed annotations attached to semantic nodes, or provider-native resources. Only semantics demonstrated to be portable belong in shared family requests. Call-level provider options are bounded ordered patches and normally bind to the exact configured model instance; host route/model/step/call precedence remains private to runtime instead of becoming part of every provider API.
Registry resolution returns the same family trait object accepted by the root modules. Resolve a route once and pass that live handle to ordinary application code; Registry does not recover a concrete provider through downcasting. Keep the configured concrete provider beside Registry when the application also needs native files, batches, sessions, or media jobs.
Generic, dependency-injected, and Registry code uses the root family seam rather than a facade-specific trait:
use ;
async
A typed family client and a Registry-resolved Arc<dyn LanguageModel> both satisfy this function.
Erasure is one-way: use client.provider() and client.model() for native resources, sessions, or
mode-specific responses before passing a model behind a trait object.
Canonical language call with MiniMax
MiniMax uses Anthropic-compatible Messages as its recommended language mode:
use ;
use Siumai;
async
The call returns the complete LanguageResponse: content, termination, usage, warnings, and
provider metadata remain available. output_text() is only a display-oriented concatenation of
canonical text parts. It excludes reasoning, refusals, tools, citations, media, and
provider-native state, and it does not replace project_assistant_history() when building the next
request.
The typed hub's language(model) and the provider's language(model)/messages(model) constructors
select Messages. Use client.provider().chat_completions(model) or
client.provider().responses(model) only when that wire API is an explicit requirement. Each mode
has a matching typed options type and rejects options from another mode.
Messages prompt-cache breakpoints use typed MinimaxMessageCache, MinimaxContentCache, or
MinimaxToolCache annotations on the node they modify. The same configured provider remains
reachable through client.provider() and owns native resources through:
client.provider().files();client.provider().images();client.provider().video();client.provider().music();client.provider().speech().
These resources are not flattened into a universal client because their request shapes, result types, and task lifecycles are provider-specific.
See docs/providers/minimax.md for dated support evidence, API-mode
stability, resource boundaries, and deliberate streaming limitations.
Optional Registry
Registry stores immutable registrations from providers the caller has already configured. It does not discover remote models, read hidden credentials, choose a region, or apply business fallback policy. One route may expose several disjoint model families from the same provider; each family retains its own exact protocol scope and configured factory.
use models;
use ;
use Siumai;
let ai = builder
.minimax
.api_key
.build?;
let mut builder = builder;
builder.register_provider?;
let registry = builder.build?;
let model = registry.language_model?;
# Ok::
The default MiniMax registration uses Messages. Chat Completions and Responses registrations remain
explicit provider-owned choices while retaining the same portable image and speech families.
register_provider returns a typed error when a valid provider configuration exposes only
provider-native resources or jobs. Combined registrations can be narrowed with for_family before
assigning a route.
Provider plane and host control plane
Siumai owns request correctness, authentication, technical endpoints, wire behavior, response decoding, and provider-native resource operations. The host application owns account and region selection, aliases, default models, current commercial availability, pricing, quota, compliance, health, weights, and fallback.
A provider may accept a technical region, project, deployment, or endpoint when the remote API needs it for addressing or signing. That input is not an SDK-maintained availability catalog.
Documentation
- Repository architecture
- Public API and extension policy
- Typed Siumai provider hub decision
- Registry contract
- Transport contract
- Provider support policy
- Google Gemini support evidence
- Contributing
- Documentation index
Development
Run Cargo commands serially and prefer focused package checks:
Default tests are deterministic, offline, and secret-free. Do not run live, credentialed, billable, or destructive provider tests without explicit authorization.
Acknowledgements
Siumai draws product inspiration from the Vercel AI SDK while keeping its public ownership, traits, builders, errors, feature flags, and async boundaries Rust-first.
Changelog and license
See CHANGELOG.md for release history. Siumai is licensed under either the Apache
License, Version 2.0, or the MIT license, at your option.