siumai-server 0.11.0-beta.12

Server gateway projections for the Siumai runtime
Documentation

Siumai — Provider-faithful AI model interfaces for Rust

Crates.io Documentation License Ask DeepWiki

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:

[dependencies]
siumai = { version = "=0.11.0-beta.12", default-features = false, features = ["openai"] }
tokio = { version = "1", features = ["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 siumai::providers::openai::models::GPT_5_6;
use siumai::Siumai;

async fn quickstart() -> Result<(), Box<dyn std::error::Error>> {
    let ai = Siumai::builder()
        .openai()
        .api_key("example-openai-key")
        .build()?;
    let client = ai.language(GPT_5_6)?;
    let response = client.generate("Explain typed provider hubs in one sentence.").await?;

    if let Some(text) = response.output_text() {
        println!("{text}");
    }
    Ok(())
}

fn main() {
    // This repository example uses a synthetic credential and deliberately
    // does not poll the future, so it cannot make a billable provider call.
    drop(quickstart());
}

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 std::time::Duration;
use siumai::transport::{ProviderHttpTransportSettings, RetryPolicy};

let settings = ProviderHttpTransportSettings::default()
    .with_retry_policy(RetryPolicy::new(2).unwrap())
    .with_call_timeout(Duration::from_secs(120))
    .unwrap();

assert_eq!(settings.retry_policy().max_attempts(), 2);

The default route is Direct. Select a trusted forward proxy explicitly without consulting process proxy variables:

use siumai::transport::{HttpTransportRoute, ProviderHttpTransportSettings, ProxyEndpoint};

let route = HttpTransportRoute::trusted_connect(
    ProxyEndpoint::https("https://proxy.example.com").unwrap(),
);
let settings = ProviderHttpTransportSettings::default()
    .with_route(route)
    .unwrap();

assert!(settings.route().proxy().is_some());

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.rs combines typed Responses options and prompt-cache intent, complete portable response inspection, Files/Responses resources, and a model-native Responses call;
  • anthropic_flagship.rs combines typed Messages/cache/file intent, complete portable response inspection, model cache prewarming, and provider-owned Files and Message Batches;
  • provider_switching.rs constructs OpenAI, Anthropic, and Gemini typed hubs and uses the identical client.generate(...) application call;
  • registry_switching.rs keeps generic and Registry-resolved switching separate and makes the one-way erasure boundary explicit;
  • trusted_connect_route.rs constructs the trusted route and compiles a provider settings handoff without credentials or network I/O;
  • self_hosted_http.rs uses the custom API 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() or client.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 siumai::{language, LanguageCallError, LanguageModel, LanguageResponse};

async fn answer<M>(model: &M) -> Result<LanguageResponse, LanguageCallError>
where
    M: LanguageModel + ?Sized,
{
    language::generate(model, "Explain explicit type erasure.").await
}

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 siumai::providers::minimax::{
    MinimaxMessagesOptions, MinimaxServiceTier, MinimaxThinking, models,
};
use siumai::Siumai;

async fn minimax_example() -> Result<(), Box<dyn std::error::Error>> {
    let ai = Siumai::builder()
        .minimax()
        .api_key("example-minimax-key")
        .build()?;
    let client = ai.language(models::MINIMAX_M3)?;
    let provider_options = MinimaxMessagesOptions::new()
        .with_thinking(MinimaxThinking::Adaptive)
        .with_service_tier(MinimaxServiceTier::Standard);
    let response = client
        .call("Hello MiniMax!")
        .with_provider_options(&provider_options)?
        .generate()
        .await?;

    if let Some(text) = response.output_text() {
        print!("{text}");
    }
    Ok(())
}

fn main() {
    // Keep the synthetic-credential example offline.
    drop(minimax_example());
}

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 siumai::providers::minimax::models;
use siumai::registry::{Registry, RegistryBuilderExt};
use siumai::Siumai;

let ai = Siumai::builder()
    .minimax()
    .api_key("example-minimax-key")
    .build()?;
let mut builder = Registry::builder();
builder.register_provider("minimax", ai.provider())?;
let registry = builder.build()?;
let model = registry.language_model(format!("minimax:{}", models::MINIMAX_M3))?;
# Ok::<(), Box<dyn std::error::Error>>(())

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

Development

Run Cargo commands serially and prefer focused package checks:

cargo fmt --all -- --check
cargo nextest run -p siumai-provider-minimax --all-features --test-threads 1
cargo clippy -p siumai-provider-minimax --all-targets --all-features -j 1 -- -D warnings

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.