runifold-model 0.9.1

[!WARNING] Runifold is pre-alpha. Public APIs may change before 1.0; breaking changes are documented in the changelog and released with a new minor version.

Contents

• What is Runifold?
• Why Runifold?
• Quickstart
• Choose the right layer
• Provider support
• Production boundaries
• Technical documentation
• Workspace
• Contributing
• License

What is Runifold?

Runifold provides one execution model for calling models, executing typed tools, running agents, and composing durable workflows. The name combines run with manifold: models, tools, agents, and flows are different surfaces over the same execution space.

Simple APIs use the same runtime path as advanced ones. A quick prompt can therefore grow into a capability-limited, observable, recoverable workflow without replacing its model or tool abstractions.

Why Runifold?

• Typed, provider-neutral contracts. Models, multimodal content, tools, retrieval, effects, and workflows remain independent of vendor wire types.
• Explicit authority. Capabilities, budgets, deadlines, and cancellation propagate through a structured run tree; child runs cannot gain authority their parent did not grant.
• Durable execution. Write-ahead effects, checkpoints, leases, fencing, timers, signals, and human review support conservative crash recovery.
• Observable by construction. Canonical events, optional OpenTelemetry instrumentation, read-only operational tooling, and value-free diffs explain what happened without making prompt capture the default.
• Failure-aware delivery. Provider adapters expose retry safety, strict stream lifecycles, bounded retries, circuit breakers, and visible capability degradation instead of silently hiding failures.
• Testable offline. Deterministic models, fault injection, real loopback protocol cassettes, evaluation gates, and reproducible benchmarks are part of the public testing surface.

Quickstart

Add the facade and the provider adapters your application needs:

cargo add runifold
cargo add runifold-providers --features openai

Create an OpenAI-backed agent:

use runifold::ProviderModelExt;
use runifold_providers::openai::OpenAiClient;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = OpenAiClient::from_api_key(std::env::var("OPENAI_API_KEY")?)?
        .runtime("gpt-5")?;

    let answer = runtime
        .agent("assistant")
        .system("Answer precisely and expose uncertainty.")
        .prompt_text("Why is durable execution useful?")
        .await?;

    println!("{answer}");
    Ok(())
}

ProviderRuntime is long-lived application state. Construct it once at startup and clone it into request handlers. Clones share retry and circuit-breaker state; rebuilding it for every request resets route health.

OpenAI-compatible providers use the same runtime and Agent path. For example:

use runifold::ProviderModelExt;
use runifold_providers::deepseek;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let answer = deepseek::client(std::env::var("DEEPSEEK_API_KEY")?)?
        .runtime("deepseek-reasoner")?
        .agent("reasoner")
        .prompt_text("Why does idempotency matter?")
        .await?;

    println!("{answer}");
    Ok(())
}

The root run created by this ergonomic path receives only the Tool, retrieval, and child-Agent capabilities explicitly registered on the Agent. Use agent.run(input, &context) when the application must supply a tighter budget, narrower capabilities, a deadline, durable journaling, or shared run-tree identity.

Choose the right layer

For a lightweight model-only application:

cargo add runifold-model
cargo add runifold-providers --features openai

Add the facade only when Agent, Tool, Effect, Retrieval, or Workflow composition is required.

Provider support

Runifold separates provider identity from wire protocol. Native adapters keep vendor event semantics, while compatible providers share a hardened transport without creating one crate per endpoint.

• Native adapters: OpenAI Responses, Azure OpenAI, Anthropic Messages, Gemini GenerateContent, Ollama Chat, Amazon Bedrock Converse Stream, and Cohere Rerank.
• OpenAI-compatible profiles: Ark, Qwen, DeepSeek, OpenRouter, xAI, Groq, Mistral, Together AI, Perplexity Sonar, MiniMax, Zhipu AI, SiliconFlow, and Hugging Face Inference Providers.
• Application-owned endpoints: vLLM, llama.cpp, llamafile, gateways, and custom Responses or Chat Completions services.

Capabilities are declared per model when they vary by model. Unknown model names retain conservative adapter defaults instead of inheriting guessed features. See the provider support matrix for constructors, Cargo features, protocol boundaries, regional endpoints, and verification levels.

Production boundaries

Runifold treats correctness claims as executable contracts:

• Provider streams, cancellation, disconnects, and concurrent requests run through real loopback HTTP/SSE/NDJSON/binary EventStream cassettes.
• SQLite recovery includes forced process termination; PostgreSQL behavior is verified against disposable real databases with outage and restart tests.
• The provider-neutral facade compiles for wasm32-unknown-unknown; supported browser Provider paths run in pinned headless Chrome through real CORS, Fetch, WebSocket, and WebRTC boundaries.
• Rich Tool results and durable artifacts retain text, images, audio, documents, resources, structured content, and stable artifact references without flattening everything into a JSON string.
• The framework-neutral benchmark contract includes a standalone, release-mode Rig comparison with equivalent requests, alternating rounds, confidence intervals, and retained raw evidence.

These claims are deliberately narrower than the feature list. The reliability matrix distinguishes mandatory CI evidence, scheduled or manual gates, planned work, and areas requiring independent reproduction. Browser deployments must also follow the documented application-gateway credential boundary.

Technical documentation

• Runifold technical site
• API reference
• Project charter and architectural laws
• Provider support matrix
• Reliability evidence
• Browser and edge deployment
• Benchmarking contract
• Testing guide
• Operations and SLO runbook
• RFC index
• Release history

The RFC series records the stable kernel, model and provider boundaries, Agent and Tool semantics, MCP, retrieval, durable workflows, multi-tenant budgets, governance, storage, evaluation, and release integrity. The API reference is the best entry point for type-level usage; the RFCs explain why the boundaries exist.

Workspace

Planned edge crates include A2A transports and additional persistence backends. They remain outside the kernel until their dependency and protocol boundaries are clear.

Contributing

Start with the project charter, then use the testing guide for the relevant reliability boundary. Changes to public behavior should update the corresponding RFC and changelog. Release maintainers should follow the release runbook.

Issues and proposals are welcome in the GitHub repository.

License

Licensed under either Apache License 2.0 or MIT, at your option.