The feature matrix

In one line

Thirty-one opt-in features: eight providers, five provider-local GPU features, twelve plugins, six services

You need

At least one provider-* feature; the build stops without one

Read this if

You are choosing a feature list, or tracing which crate a feature pulls in

default = []. Every feature below is off until you enable it. The source of truth is the [features] table in Cargo.toml.

The provider gate

A build with none of the eight provider features stops at a compile_error! in src/lib.rs:

CUCA requires one provider-* feature; enable the adapter for the backend you use.

The gate is a #[cfg(not(any(...)))] over provider-openai, provider-anthropic, provider-deepseek, provider-gemini, provider-llamacpp, provider-vllm, provider-lmstudio and provider-local. The five GPU features are not providers and do not satisfy it. CI asserts that cargo check --no-default-features fails.

Provider features

Eight features: seven HTTP adapters and one in-process engine. Each dep: entry is an optional dependency the feature turns on.

provider-local does not use tokio-stream: its stream is a plain mpsc receiver. It uses reqwest only for the one-time model download.

Local GPU features

Five features extend provider-local. None is a provider.

• provider-local-gpu is the shared GPU engine. It selects no backend by itself; each backend feature enables it.
• provider-local alone runs the model on the CPU.
• LocalDevice and GpuAdapter exist in every provider-local build. Selecting a backend whose feature is off makes LocalModel::load fail with CucaError::Config.
• provider-local-cuda and provider-local-rocm download a prebuilt LLVM on the first build. ROCm builds on Linux only.

Plugin features

Twelve features. Each plugin implements CucaPlugin and runs on the request pipeline.

No plugin feature enables another plugin feature, and none names a service: the tier is flat.

Service features

Six features. A service is driven by direct method calls and never implements CucaPlugin.

Feature edges

Three hard edges, all service to plugin:

• service-entity-extraction = ["plugin-memory"]
• service-replay = ["plugin-session-log"]
• service-vector-store = ["plugin-memory", "dep:wide"]

One optional edge, not a Cargo feature: ModelOrchestrator::with_session_store exists only when service-speculative and plugin-session-log are both enabled.

service-prompt-cache and service-rate-limit declare no plugin dependency. A plugin never depends on, or names, a service.

Unconditional dependencies

Five crates compile in every build. They carry the public wire types, the SSE parser and the response stream contract.

Optional dependencies

Why some defaults are off

• reqwest has no defaults, so TLS arrives only through the reqwest/rustls entry that every provider-* feature and plugin-web-search carries.
• jsonschema has no defaults because guardrails compiles inline schemas only and needs no $ref retrieval.
• postcard has no defaults because its default heapless-cas feature pulls in heapless, which the crate never uses. use-std supplies the std buffer and COBS helpers.
• burn has no defaults because they enable the optimizer and autodiff, which inference never uses.

C compilers and downloads

• candle-core hard-depends on tokenizers[onig], so provider-local compiles C through onig_sys and needs a C compiler.
• The Vulkan and Metal backends are Rust (wgpu: SPIR-V, MSL). Every GPU feature still compiles C, because CubeCL's runtime pulls an embedded store (turso) that builds C through cc.
• On Windows, a dependency's build script runs the SDK resource compiler (rc.exe; windres on the GNU target) for the GPU features.
• provider-local-cuda and provider-local-rocm pull CubeCL's LLVM backend. Its build script, tracel-llvm-bundler, downloads a prebuilt LLVM on the first build (network needed once, then cached) and links it statically.
• docs.rs builds have no network, so the [package.metadata.docs.rs] feature list names every feature except those two.

Feature-conditional modules

Every other public module compiles unconditionally: types, error, request, session, sse, plugin, plugins, services, client. The plugins and services modules are always present. Their submodules are individually gated, so each is empty when none of its features is on. The provider module is pub(crate).

Crate metadata

doctest = false because the doctest pass does a plain library build that the provider gate rejects, and the crate has no doctests.

Example targets

Twenty-three examples. All but local_model require provider-llamacpp. Run one with cargo run --example <name> --features <list>.

Examples live in examples/<name>.rs.

Bench target

benches/vector_store.rs is a Divan benchmark with harness = false. It requires provider-openai and service-vector-store. No CI job runs it.

Feature combinations CI verifies

ALL_NO_LLVM is a top-level env entry in .github/workflows/ci.yml, the same list as the docs.rs feature set: every feature except provider-local-cuda and provider-local-rocm. The run steps expand it as $ALL_NO_LLVM.