Skip to main content
The doctrine in one line: unknown stays unknown. A cost Nika cannot prove is never rendered as $0.00, a local model is unpriced — your compute, your electricity — never « free », and an estimate always says which side of the truth it sits on: a floor (≥) or a ceiling (≤).

​
The vocabulary

Every cost surface speaks the same four words: There are exactly two ways a task goes UNBOUNDED, and the rung names which one:
  • UNBOUNDED — no max_tokens declared · the model has a price but the task has no output limit. You can fix this one: declare max_tokens: and the report upgrades from floor to hard ceiling (the check prints that exact hint).
  • UNBOUNDED — no catalog price (local/unknown model) · the task is bounded but the model has no price row. Local models stay here by design — pricing your own hardware would be invention.

​
Before a token: the COST rung

nika check audits cost statically, next to the plan and the permits — the same ladder, every time:
Bound every task and the same rung flips to ✔ COST $0.0001 – $0.0001 worst-case ceiling with a per-task ≤N tk · $… row. nika explain <file> narrates the same numbers in beginner words — « ≥ $0.0000 — a FLOOR, not a ceiling · local models: your compute · tokens unpriced — not « free » » — and nika run --dry-run carries them onto the plan.

​
The budget gate: refusal, not remorse

--max-cost-usd is a block-before-spend gate, not a post-hoc alarm:
  • If the static floor already exceeds the budget, the run refuses to start (exit 2, before any provider is touched):
  • Since 0.99 that pre-start refusal prices the effective model — --model override included. On 0.98.x the override was only guarded mid-run; upgrading closes that gap.
  • If unbounded work rides along, the gate says so loudly on stderr — a budget over work with no ceiling is a promise it names, not one it fakes.
  • Mid-run, the ledger stops the workflow the moment real spend crosses the budget (NIKA-1704) — settled tasks stay settled, the trace records what was spent.
  • The flag itself is guarded: a non-finite value (NaN, inf) is rejected at parse time — a budget that cannot compare is not a budget.

​
After the run: the totals stay honest

Every run ends with the same honest line, mock or cloud:
The ≥ is load-bearing: it is printed because an unpriced task rode the run. Per-task spend rides the trace itself (cost_usd on the terminal events), so nika trace show and the run report read the recorded ledger — never a summary’s opinion.

​
Where prices come from — and when they rot

Prices are a catalog fact with provenance, not a constant: nika check --json carries the pricing snapshot (source · date · hash · derived counts) so a cost claim is traceable to the table that produced it, and nika doctor warns when the snapshot is stale enough to distrust — an old price table silently undercounts, which is the one direction honesty cannot tolerate. Cache-aware accounting follows the OpenTelemetry GenAI convention (input includes cache reads), so exported traces mean the same thing your dashboards expect.

​
The workflow-side controls

  • max_tokens: per task · turns FLOOR into ceiling.
  • agent: budgets (max_turns · token budgets) bound the loop the same way — exhaustion is a named failure, never a silent overrun.
  • nika check before nika run, always: the cost story is part of the same pre-flight as permits and secrets.
Local-first corollary: a workflow that runs entirely on ollama/…, llamacpp/… or vllm/… reports $0.00 with the unpriced count attached — Nika never converts « I don’t know the price » into « it’s free ». That distinction is the whole doctrine.