Skip to main content
A task names its model as <provider>/<name>. The language specification names canonical providers (spec catalog), and the 0.124.3 binary drives exactly those: local servers, cloud APIs, and mock, the rehearsal provider that makes no model call. The engine’s catalog records entries: nika catalog lists the ones this build cannot drive under CATALOG ONLY, and nika check refuses them.
Every provider with its environment variable and default model: Providers catalog. nika catalog prints the same inventory from your binary.
Switching provider is one line:
A cataloged-only vendor is not a runnable one:

Model and access

Two choices are separate. The model (model: in the file) picks the intelligence. The access path picks how Nika reaches it: Every nika check prints an ACCESS line and a final access ready ✔ | ✖ layer: whether this machine has a path to each model the file names, without calling it. That line judges the model route only. On the mock it reads mock · this model route never dials, then names the tasks whose own effects can still reach the network (a fetch or webhook to a real host, an MCP tool, a paid media call), which the PERMITS row judges. A file with no infer: or agent: task reads access ready n/a · no model route, followed by the same names. --json lists every one as verdicts.network_tasks. An exec: task is not in that list, whatever its command reaches; permits.exec bounds the programs it may run. nika run --access <class or seat> pins the path; a pin is a pin, so an unsatisfied one refuses before anything runs and never substitutes another path or model. nika doctor lists the paths your machine has. Read Local models and Harness access to set one up. A file can declare its route itself. run.access names the route (via), its protocol (protocol: api or acp) and the service tier asked of it (service_tier: standard or fast); run.reasoning.effort names the route’s own effort value. A declared selection is honored exactly or refused before any model call, never replaced by another route. Only the Codex seat over ACP carries a service tier: every other route refuses the key, and leaving it out keeps the route’s own tier, which is not standard (Harness access · run.access).

One inference request for every provider

The engine turns every infer: and agent: step into one request type, InferRequest (crates/nika-kernel-ai/src/provider.rs), whatever the provider: the model, the messages, temperature, max_tokens, tools and tool choice, the response format, stop sequences, a thinking budget, a reasoning effort, provider extras, a timeout and a cancel handle, among others. A provider is the combination of three small traits, ProviderInfer (one call), ProviderStream (a streamed call) and ProviderMeta (its name and capabilities), sealed so only the workspace implements the whole. Every wire lives in one crate, nika-providers. The catalog records three API dialects (openai-chat, anthropic, gemini); at run time Ollama gets its own native wire: Any other OpenAI-compatible endpoint is reached by pointing a cataloged id at it: NIKA_<ID>_BASE_URL (for example NIKA_OPENAI_BASE_URL) sets the complete endpoint and NIKA_<ID>_API_KEY its key, and the file keeps model: openai/<name>.
Built-in local inference. nika model pull downloads a GGUF model and nika model serve starts an OpenAI-compatible server on 127.0.0.1:8712 (Qwen3-family models in 0.124.3); a workflow reaches it as llamacpp/<model id> with NIKA_LLAMACPP_BASE_URL set. The native/ catalog id is not wired in 0.124.3. See Local models.

Capability rules

Every request is checked against capability rules before dispatch: defaults first, then the first matching rule wins. The rules record:
  • the token-limit parameter a model takes (max_tokens, max_completion_tokens…);
  • whether the model reasons (a thinking model spends part of max_tokens on thinking);
  • the modalities it accepts and returns (text, image…);
  • whether JSON mode is unavailable, object or schema;
  • which parameters it supports (temperature, stop sequences, system messages, reasoning effort…).
nika check reads them for its MODELS and CAPACITY FIT lines: a reasoning model whose max_tokens leaves no room for an answer is refused before any call, with the minimum to set.

Structured output: the engine picks the wire (ADR-098)

A task’s schema: is the single authored contract: there is no json: true sugar and no per-provider knob. The engine decides, per run, how to honor it on the wire the model speaks:
  • Fully specified schema (every object has properties, every array has items): forwarded verbatim to the provider’s strict structured mode where the wire has one.
  • Underspecified schema (an object without properties, or an array without items): strict mode would reject it, so the engine requests the provider’s native JSON mode instead, steers the shape through the prompt, and validates the reply locally against your schema, with bounded retry.
  • A wire with no native JSON mode (the anthropic dialect): the prompt carries the shape; the same local validation applies.
  • The mock wire receives the schema verbatim and synthesizes a conformant instance: this is what lets every schema workflow run offline under nika test.
Local validation is the constant floor across all wires: the provider’s strict mode is an optimization, never the guarantee.

One model per task

A task names one model; there is no model fallback syntax (fallback: is refused, NIKA-PARSE-005). To try another model when a task fails, add a second task gated on after: { primary: failure } that names it; to give a failed task a fallback value instead, use on_error: { recover: … } (Patterns).

The wider catalog

The engine catalog ( entries) also records vendors this build does not drive: Together, Fireworks, Cerebras, SambaNova, Cohere, AI21, Bedrock, Azure, Vertex, Perplexity, Voyage, Qwen, MiniMax, Zhipu, DeepInfra, Replicate, Hyperbolic, Writer, Databricks, Cloudflare and native. They are records, not routes: nika check refuses each one. The catalog lives in the engine’s llm-providers.toml and is validated at build time.

Adding a provider

Adding a provider is engine work: a [[providers]] block in llm-providers.toml (id, environment variable, default model, api_dialect, models), capability rules in model-capabilities.toml when the provider is not standard, and a wire in nika-providers: an existing dialect needs only a base URL and auth header. The admission checklist applies.

See also

Providers catalog

Every provider with its environment variable, default model and dialect.

Capability rules

The rule format and the resolution order.

Local models

Run every step on your own machine.

Harness access

Run on an agent app you are already signed into.