<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.
Switching provider is one line:
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 everyinfer: 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_tokenson thinking); - the modalities it accepts and returns (text, image…);
- whether JSON mode is unavailable,
objectorschema; - 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’sschema: 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
objecthasproperties, everyarrayhasitems): forwarded verbatim to the provider’s strict structured mode where the wire has one. - Underspecified schema (an
objectwithoutproperties, or anarraywithoutitems): 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.
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 andnative. 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.