Ax for Rust

Write Ax programs in Rust with native Result-based errors, serde_json dynamic values at Ax boundaries, blocking provider transport, protocol-first RLM runtime sessions, and shared Ax semantics generated from the compiler contract.

Quick Start

cargo add axllm

Or add to your Cargo.toml:

axllm = "23.0.11"

Enable realtime audio over WebSocket with the realtime feature (pulls tungstenite):

cargo add axllm --features realtime

use axllm::{s, AxResult};

fn main() -> AxResult<()> {
    let sig = s("question:string -> answer:string")?;
    let schema = sig.to_json_schema("outputs");
    assert!(schema["properties"].get("answer").is_some());
    Ok(())
}

What You Can Build

• Signatures and schemas: describe inputs and outputs once, then reuse that shape for validation, prompts, tools, and typed results.
• AxGen: run structured generation with retries, tool calls, field processors, assertions, traces, usage, and provider-backed output parsing.
• AxAI: call OpenAI-compatible, OpenAI Responses, Gemini, Anthropic, Azure OpenAI, DeepSeek, Mistral, Reka, Cohere, and Grok clients through one provider boundary.
• Audio and realtime: .chat() accepts input_audio content parts, transcribe()/speak() do batch speech-to-text and text-to-speech, and realtime-capable models stream audio over a WebSocket — transparently through chat() or via the productized realtime_chat() driver (Go: RealtimeChat).
• AxAgent and RLM: let an agent plan and execute actor-code steps while Ax keeps envelopes, state, logs, traces, context, discovery, recall, and final typed responses aligned.
• AxFlow: compose AxGen, AxAgent, and nested flows into a portable program graph.
• Optimizers: save, load, apply, and evaluate optimizer artifacts, including the generated GEPA engine.

Package Shape

• Crate: axllm
• Dynamic value boundary: serde_json::Value
• Error boundary: Result<T, AxError>
• Built-in HTTP transport: blocking reqwest with rustls TLS
• Runtime execution: process/JSONL protocol through ProcessCodeRuntime; embedded QuickJS is opt-in with the runtime-quickjs Cargo feature
• Network support: available

Shared Ax behavior is Core-owned. The generated target code stays focused on idiomatic wrappers, transports, dynamic value helpers, and host-runtime boundaries.

Examples

no-key examples are deterministic local smokes. They are the fastest way to see the package work without any provider account:

• cargo run --example signature_schema: signature parsing and JSON schema generation
• cargo run --example provider_mapping_no_key: provider mapping through a scripted transport
• cargo run --example adaptive_balancer_no_key: adaptive balancer state, scoring, and stable route keys without a provider key
• cargo run --example provider_stream_no_key: provider streaming through a scripted SSE transport
• cargo run --example axgen_scripted_client_tool: AxGen with a scripted client and tool
• cargo run --example axflow_program_graph: AxFlow program graph
• cargo run --example flow_mermaid: portable Mermaid flow parsing and canonical round-trip
• cargo run --example audio_responses_mapping: OpenAI Responses speak/transcribe mapping through a scripted transport
• cargo run --example realtime_audio_events: Grok/Gemini realtime audio setup, input, and event folding
• cargo run --example realtime_audio_turn: drive a full realtime audio turn through realtime_chat (offline, scripted transport)
• cargo run --example runtime_adapter: custom AxCodeRuntime session
• cargo run --example runtime_protocol: process runtime protocol against the AxJS reference adapter
• cargo run --example javascript_quickjs --features runtime-quickjs: embedded QuickJS actor runtime profile
• cargo run --example optimizer_artifact: optimizer artifact lifecycle smoke
• cargo run --example gepa_local_optimizer: local GEPA optimizer artifact generation
• cargo run --example ace_playbook: grow an evolving context playbook with playbook() (offline, scripted client)
• cargo run --example agent_playbook: attach a seeded agent playbook, exercise stage instructions and citations, learn from run-end failures, and verify accept/rollback evolution (offline, scripted client)
• cargo run --example mcp_scripted_tools: MCP tool discovery and invocation through a scripted transport
• cargo run --example mcp_modern_roundtrip: modern MCP discovery, cache, task, and roots MRTR over an in-process HTTP loopback
• cargo run --example context_cache_recovery: Gemini managed-context-cache recovery through a scripted transport

provider-api examples make a real provider call. OpenAI examples require OPENAI_API_KEY; Vertex examples require GOOGLE_VERTEX_ACCESS_TOKEN, GOOGLE_PROJECT_ID, and GOOGLE_REGION:

• OPENAI_API_KEY=... cargo run --example axgen_openai_api: GPT-5.6 prompt-cached AxGen with the OpenAI Chat API
• GOOGLE_VERTEX_ACCESS_TOKEN=... GOOGLE_PROJECT_ID=... GOOGLE_REGION=... cargo run --example vertex_gemini_api: Gemini through Vertex routing
• OPENAI_API_KEY=... cargo run --example flow_openai_api: AxFlow with a real OpenAI-compatible provider API

Runtime Profiles And RLM Agents

AxAgent uses an RLM executor loop. On each turn, the model writes a small actor-code step, and Ax sends that step into an AxCodeRuntime session. Think of the runtime as the agent's REPL: it keeps session state, exposes safe host callbacks, returns envelopes such as final(...), askClarification(...), discover(...), recall(...), and used(...), and lets the agent continue from the result.

The TypeScript package ships AxJSRuntime as the reference JavaScript implementation of that REPL contract. Generated runtime profiles are adapters for the same AxCodeRuntime / AxCodeSession boundary. They exist so RLM agents can execute actor code in a host runtime that fits the target package.

This package is not a TypeScript transpiler. AxIR compiles shared Ax semantics into native package code; it does not run your original Ax TypeScript application inside a Rust runtime. Application code is still written in the language you are using here.

Runtime profiles are target-specific and opt in to their engine dependencies:

• ProcessCodeRuntime speaks the shared AxCodeRuntime JSONL protocol.
• javascript-quickjs is an embedded JavaScript actor runtime backed by rquickjs and gated by Cargo feature runtime-quickjs.

Verify it with axir verify --targets rust --runtime-profiles javascript-quickjs when the AxIR toolchain is available.

Optional runtime profiles are dependency-bearing and opt-in. Adapter policy owns sandboxing, dependency loading, hard cancellation, process security, and host permissions. The shared Ax contract still owns envelopes, state, logs, traces, and the model-visible protocol.

Contract Snapshot

• Compiler contract version: 0.1
• Package: axllm
• Supported conformance suites: signature, schema, validation, prompt, axgen, axai, axagent, axoptimize, axprogram, axflow, axmcp, axevent
• Provider mode: provider-descriptor-registry-openai-compatible-openai-responses-google-gemini-anthropic
• Scripted transport support: true
• Real network support: available