ai-lib-rust

Protocol runtime for AI-Protocol — high-performance Rust reference implementation (v1.2.0).

中文文档

ai-lib-rust is the umbrella crate most applications depend on. It re-exports ai-lib-core (execution) and ai-lib-contact (policy) so existing ai_lib_rust::… import paths stay stable.

How it works

Default chat path: AiClient loads a provider manifest → builds a Pipeline from manifest operators → sends HTTP via HttpTransport. Streaming frames are normalized to StreamingEvent.

This is protocol-driven for chat, but not “zero provider code”: the repo also ships provider-specific decoders/mappers, optional ProviderDriver implementations (advanced / WASM / tests), and standalone HTTP clients for embeddings, STT, TTS, and rerank.

Published on crates.io: ai-lib-core, ai-lib-contact, ai-lib-rust (all 1.2.0). ai-lib-wasm is built for wasm32-wasip1 and is not published.

Pin: Prefer crates.io 1.2.0 (tag v1.2.0). CI pins ai-protocol v1.1.0. See CHANGELOG.

Quick start

[dependencies]
ai-lib-rust = "1.2.0"
tokio = { version = "1", features = ["full"] }

export DEEPSEEK_API_KEY="your-key"

use ai_lib_rust::{AiClient, Message};

#[tokio::main]
async fn main() -> ai_lib_rust::Result<()> {
    let client = AiClient::new("deepseek/deepseek-chat").await?;

    let response = client
        .chat()
        .messages(vec![
            Message::system("You are a helpful assistant."),
            Message::user("Hello!"),
        ])
        .temperature(0.7)
        .max_tokens(500)
        .execute()
        .await?;

    println!("{}", response.content);
    Ok(())
}

Same example: cargo run --example basic_usage (requires DEEPSEEK_API_KEY).

Streaming

use ai_lib_rust::{AiClient, Message, StreamingEvent};
use futures::StreamExt;

#[tokio::main]
async fn main() -> ai_lib_rust::Result<()> {
    let client = AiClient::new("deepseek/deepseek-chat").await?;

    let mut stream = client
        .chat()
        .messages(vec![Message::user("Write a haiku about Rust.")])
        .stream()
        .execute_stream()
        .await?;

    while let Some(event) = stream.next().await {
        match event? {
            StreamingEvent::PartialContentDelta { content, .. } => print!("{content}"),
            StreamingEvent::StreamEnd { .. } => break,
            _ => {}
        }
    }
    Ok(())
}

Share across tasks

AiClient is not Clone (API key / ToS boundary). Use Arc<AiClient>:

use ai_lib_rust::AiClient;
use std::sync::Arc;

let client = Arc::new(AiClient::new("openai/gpt-4o").await?);

Public API (crate root)

Always available (non-WASM):

• Client: AiClient, AiClientBuilder, ChatBatchRequest, CancelHandle, CallStats, ClientMetrics, EndpointExt
• Types: Message, MessageRole, StreamingEvent, ToolCall, ExecutionMetadata, ExecutionResult, ExecutionUsage
• Errors: Result, Error, ErrorContext, StandardErrorCode
• Feedback: FeedbackEvent, FeedbackSink
• Structured output: structured module (JsonModeConfig, OutputValidator, …)
• Text-tool / TTC: StandardTextToolParser, ToolCallingPolicy, TextToolConfig, …
• Policy (always re-exported): cache, context, plugins, resilience

ai_lib_rust::context (policy layer, always on) includes layered context assembly: MessageChunk, ContextLayer, MessageAssembler::assemble_layered, AssemblePool (async façade with concurrency / timeout), and AssembleError::HardBudgetViolation when System+Active exceed the token budget.

Feature-gated re-exports from ai-lib-contact: batch, guardrails, interceptors, routing (routing_mvp), telemetry, tokens.

Feature-gated modules in ai-lib-core: embeddings, mcp, computer_use, multimodal, stt, tts, rerank.

What features actually do

Enable features in Cargo.toml:

ai-lib-rust = { version = "1.2.0", features = ["embeddings", "telemetry"] }

Advanced: ProviderDriver

ai_lib_rust::drivers exposes ProviderDriver, create_driver, and OpenAI / Anthropic / Gemini drivers. AiClient does not use this path for chat; it uses Pipeline::from_manifest. Drivers are for WASM targets, compliance tests, and custom integrations.

Resilience

• Built into AiClient: max_inflight backpressure (AiClientBuilder::max_inflight or AI_LIB_MAX_INFLIGHT).
• Opt-in policy layer: ai_lib_rust::resilience (retry, rate limiter, circuit breaker) — wire beside the client; not auto-enabled on AiClient::new.
• Batch concurrency: AI_LIB_BATCH_CONCURRENCY.
• HTTP proxy: reqwest system proxy (HTTP_PROXY / HTTPS_PROXY / NO_PROXY) on the direct route; set AI_PROXY_URL for an explicit failover candidate route.

Protocol manifests

Resolution order for provider manifests:

1. ProtocolLoader::with_base_path(...)
2. AI_PROTOCOL_DIR / AI_PROTOCOL_PATH (local dir or GitHub raw URL)
3. Dev paths: ai-protocol/, ../ai-protocol/, …
4. Fallback: GitHub raw ailib-official/ai-protocol (main)

Per base path: dist/v2/providers/<id>.json → v2/providers/<id>.yaml → dist/v1/providers/<id>.json → v1/providers/<id>.yaml.

Identity / aliases: load_provider resolves marketplace aliases via dist/provider-identity.json (multi-family map), e.g. google → gemini, kimi → moonshot. Validation errors are not masked by alias lookup.

Wire model id: chat requests resolve the OpenAI-compatible model field via the v1 model registry (resolve_wire_model_id), with NIM-aware fallback for nvidia/<name> ids.

Endpoints: operation "chat" falls back to endpoints.chat_openai when the canonical chat key is absent (DeepSeek dual-API manifests).

Model modalities (Experimental): when metadata.models.<id> is present, those modality facts are preferred over provider-level ads (ALR-ME-001).

Manifest cache: in-memory only. with_hot_reload(true) stores a flag but does not watch files — call ProtocolLoader::clear_cache() or rebuild the client after manifest changes.

API keys

1. Builder override (if set)
2. Manifest-declared env vars (auth.token_env / auth.key_env)
3. Conventional <PROVIDER_ID>_API_KEY env var
4. OS keyring (optional, keyring feature, desktop)

Recommended for CI/containers: env vars; use default-features = false to drop keyring.

Standard error codes (V2)

Testing

# Unit + integration (facade crate)
cargo test

# Cross-runtime YAML compliance
COMPLIANCE_DIR=../ai-protocol/tests/compliance cargo test --test compliance

# All optional features
cargo test --features full

Mock server integration (requires ai-protocol-mock):

MOCK_HTTP_URL=http://localhost:4010 cargo test -- --ignored

Examples

CLI bins: cargo run --bin validate_protocols, cargo run --bin ai-protocol-cli.

WASM

cargo build -p ai-lib-wasm --target wasm32-wasip1 --release
# → target/wasm32-wasip1/release/ai_lib_wasm.wasm

Related

• AI-Protocol — specification & manifests
• ai-lib-python — Python runtime
• docs/ARCHITECTURE.md — workspace layout

License

Dual-licensed under Apache-2.0 or MIT.