Nika

Authoring Nika workflows

Nika turns repeatable AI work into files: one .nika.yaml, four verbs, audited before it runs. You author the file; nika check is the oracle; the human runs it.

The loop (always)

1. Start from a template or example, never from scratch: nika examples list · nika examples show <slug> · nika new --from <template> <file>.nika.yaml
2. Write the file. Envelope is always nika: v1 + workflow: <kebab-id> + tasks:. Pick models and builtins from the embedded catalogs — nika catalog (providers · models · capabilities · which env var each needs) and nika tools (the nika:* builtins an invoke reaches without MCP); before a run, nika inspect <file> shows the anatomy: tasks · waves · the cost floor.
3. Check it: nika check <file> (exit 0 = clean · 2 = findings), then nika check --native-strict <file> — it fails on any native-first hint (an exec: a builtin covers).
4. Repair from the diagnostics — they name the exact task, reference and fix. Unknown code? nika explain NIKA-XXXX.
5. Repeat 3–4 until clean. Never hand a file to the human that does not pass nika check — and pass --native-strict too, unless every remaining exec: is in the exec ledger (below).
6. The human (or CI) runs it: nika run <file>. Preview offline with --model mock/echo; run locally with --model ollama/<model>. Inputs ride --var key=value (repeatable · unknown keys refused); a run paused on a nika:prompt resumes with nika run <file> --resume <trace> --answer <task>=<value> (confirm gates take booleans: --answer approve=true).
7. Pin it for CI: nika test <file> --update writes <file>.golden.json from an offline mock run; nika test <file> replays and compares — deterministic, zero keys.
8. Prove a run that mattered: every run writes a hash-chained journal to .nika/traces/ — nika trace verify <trace> checks the chain (tamper-evidence), nika trace show <trace> reads the card. Cite the trace, never a memory of the run.

Cost honesty (never hide unknown spend)

• nika check prints the cost ceiling BEFORE any token: ≤ $X is a ceiling · ≥ $X FLOOR means at least one task is unbounded — name the reason (a missing max_tokens, an uncataloged model, an expression fan-out), never round it to $0.
• A local model (ollama/…) is unpriced compute, not « free » — say "unpriced", never "$0" or "free".
• A spend cap rides the run: nika run <file> --max-cost-usd <n> blocks BEFORE the call that would cross the cap.
• nika explain <file> narrates all of this (waves · cost · touches · how to run) — use it before handing a workflow to a human.

The four verbs (exactly one per task)

• infer: — an LLM call (prompt, schema? for typed output, max_tokens?)
• exec: — a shell command (command, capture: text|structured) · last resort: run the native-first interrogation first (below)
• invoke: — a builtin or MCP tool (tool, args) · HTTP fetch is tool: "nika:fetch", a tool, not a verb
• agent: — a bounded multi-turn loop (prompt, tools allowlist, max_turns, max_tokens_total)