Choose and configure a provider

Support matrix

Runifold exposes Provider adapters behind one canonical model interface. In 0.9, the runtime lives in runifold and concrete adapters live in runifold-providers; enable only the latter crate's Features you deploy.

The repository README is the release-specific source of truth for the complete matrix and verification status.

Native or compatible

Prefer a native adapter when you need provider-specific reasoning, tool, usage, or streaming semantics. Use a compatible protocol when interchangeability is more important and the endpoint has been verified.

“OpenAI-compatible” describes a wire shape, not identical behavior. Feature support, error classification, usage accounting, and streaming can still vary.

Configuration patterns

Construct the client from application configuration, then build a resilient runtime and an Agent. Keep credentials in the process secret store.

use runifold::ProviderModelExt;
use runifold_providers::openai::OpenAiClient;
 
let runtime = OpenAiClient::from_api_key(
    std::env::var("OPENAI_API_KEY")?
)?.runtime("gpt-5")?;

For compatible or regional endpoints, validate the base URL against an allowlist. Never accept an arbitrary model endpoint from end-user input.

Capability contract

Model features are negotiated explicitly. Tools, strict structured output, reasoning, vision, and streaming may be supported, unsupported, or unknown.

Choose fail-closed behavior for requirements that affect correctness. An explicit degradation is appropriate only when the product can safely explain and measure it.

Verification levels

Separate four claims:

1. the adapter compiles;
2. deterministic contract tests pass;
3. live smoke tests pass against the real service;
4. the exact model and feature combination is production-observed.

Pin versions, record the tested model identifier, and rerun live verification before relying on a new provider feature.