# news.nika.yaml — Scrape Hacker News and summarize the top stories
schema: "nika/[email protected]"
provider: claude                  # or: openai, mistral, groq, gemini, deepseek, xai, local

tasks:
  - id: scrape
    fetch: { url: "https://news.ycombinator.com", extract: article }

  - id: summarize
    with: { page: $scrape }
    infer: "3-bullet summary of today's top stories: {{with.page}}"

nika run news.nika.yaml

What is Nika?

Nika is a workflow engine where each step is a YAML task with exactly one verb -- infer, exec, fetch, invoke, or agent. Write your steps in a .nika.yaml file, run nika run, and Nika handles the rest: parallel execution, data flow between tasks, retries, structured output, and multi-provider LLM routing.

Inference as Code. The same shift that Terraform brought to infrastructure -- describe your intent in a file, let a runtime handle execution. Your workflow is a YAML file that you commit, review in a PR, diff, and version. Five verbs describe any automation, from a 3-step summary to a 50-task parallel pipeline across multiple AI providers.

Quick Start

# Install (pick one)
brew install supernovae-st/tap/nika      # macOS / Linux
cargo install nika                        # from crates.io
npx @supernovae-st/nika                   # run without installing

# Set up your API key
nika setup

# Run your first workflow
nika run hello.nika.yaml

schema: "nika/[email protected]"
provider: claude

inputs:
  topic: "butterflies"

tasks:
  - id: haiku
    infer: "Write a haiku about {{inputs.topic}}"

Want more? Scaffold a full project or start the interactive course:

nika init                   # 5 starter workflows (one per verb)
nika init --course          # 44 hands-on exercises across 12 levels
nika doctor                 # verify your setup

The 5 Verbs

Every task uses exactly one verb. That is the entire API surface.

flowchart LR
    classDef verb fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    classDef target fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff

    INFER[infer]:::verb --> LLM["9 Providers"]:::target
    EXEC[exec]:::verb --> SHELL[Shell]:::target
    FETCH[fetch]:::verb --> HTTP["HTTP + 9 Extract Modes"]:::target
    INVOKE[invoke]:::verb --> TOOLS["62 Tools + MCP"]:::target
    AGENT[agent]:::verb --> LOOP["Agentic Loop + Guardrails"]:::target

Five words. Not fifty abstractions. If you've used Terraform, GitHub Actions, or Docker Compose, this will feel familiar -- because the pattern is the same. Declare what you want, let the engine figure out how.

Examples

Scrape, summarize, translate -- in parallel

schema: "nika/[email protected]"
provider: claude

tasks:
  - id: scrape
    fetch: { url: "https://example.com/blog", extract: markdown }

  - id: summarize
    with: { content: $scrape }
    infer: "Summarize in 3 bullets: {{with.content}}"

  - id: translate
    for_each: ["French", "Spanish", "Japanese", "German", "Portuguese"]
    as: lang
    concurrency: 5
    with: { summary: $summarize }
    infer: "Translate to {{with.lang}}: {{with.summary}}"

Multi-provider fan-out -- same question, three perspectives

schema: "nika/[email protected]"

tasks:
  - id: claude_take
    provider: anthropic
    infer: "Analyze this trend: {{inputs.topic}}"

  - id: gpt_take
    provider: openai
    model: gpt-4o
    infer: "Analyze this trend: {{inputs.topic}}"

  - id: gemini_take
    provider: gemini
    model: gemini-2.5-flash
    infer: "Analyze this trend: {{inputs.topic}}"

  - id: synthesize
    depends_on: [claude_take, gpt_take, gemini_take]
    with:
      claude: $claude_take
      gpt: $gpt_take
      gemini: $gemini_take
    infer: "Synthesize these 3 perspectives: {{with.claude}} / {{with.gpt}} / {{with.gemini}}"

Structured data extraction -- guaranteed valid JSON

schema: "nika/[email protected]"
provider: claude

tasks:
  - id: extract
    infer: "Tell me about Alice, 30, Rust and Python developer"
    structured:
      schema:
        type: object
        required: [name, age, skills]
        properties:
          name: { type: string }
          age: { type: number, minimum: 0 }
          skills: { type: array, items: { type: string }, minItems: 1 }
      enable_repair: true
      max_retries: 3

The prompt is natural language -- never mention JSON. The 5-layer defense handles extraction, validation, retry, and LLM repair automatically. Same result on all 9 providers.

AI agent with guardrails and cost limits

schema: "nika/[email protected]"
provider: claude

tasks:
  - id: research
    agent:
      prompt: "Research the top 5 competitors for our product"
      tools: [nika:read, nika:write, nika:glob]
      max_turns: 15
      guardrails:
        - type: length
          max_words: 2000
      limits:
        max_cost_usd: 1.00
      completion:
        mode: explicit

Image processing pipeline

schema: "nika/[email protected]"
provider: claude

tasks:
  - id: import
    invoke: { tool: nika:import, params: { path: "./photo.jpg" } }

  - id: thumbnail
    with: { img: $import }
    invoke:
      tool: nika:pipeline
      params:
        hash: "{{with.img.hash}}"
        ops:
          - { op: thumbnail, width: 800 }
          - { op: optimize }
          - { op: convert, format: webp }

  - id: describe
    with: { img: $import }
    infer:
      content:
        - type: image
          source: "{{with.img.hash}}"
        - type: text
          text: "Write an alt-text description for this image"

115 more examples available via nika showcase list and nika showcase extract <name>.

Key Features

Providers -- 9 backends, zero lock-in

Switch providers in one line. Same workflow, any AI.

Connect to any OpenAI-compatible endpoint (vLLM, Ollama, LiteLLM, SGLang) via base_url:.

Structured Output -- 5-layer defense

Get guaranteed schema-valid JSON from any provider. No prompt hacking required.

Same result on all 9 providers. No exceptions.

Data Flow -- 63 transforms, bindings, parallel loops

tasks:
  - id: fetch_data
    fetch: { url: "https://api.example.com/users" }

  - id: process
    with:
      users: $fetch_data                     # bind upstream output
      name: $fetch_data.data[0].name         # JSONPath access
      safe: $fetch_data.name ?? "Unknown"    # default fallback
    infer: "First user: {{with.name | upper | trim}}"

63 pipe transforms: upper, lower, trim, join(","), split(","), sort, unique, flatten, first, last, length, to_json, parse_json, default("x"), pluck(field), where(field, val), sort_by(field), pick(f1,f2), omit(f1,f2), jq(expr), regex(pattern), and 40+ more.

Parallel loops with for_each + concurrency:

- id: translate
  for_each: ["en", "fr", "ja", "de", "ko"]
  as: locale
  concurrency: 5
  infer: "Translate to {{with.locale}}: {{with.text}}"

62 Builtin Tools

All accessible via invoke: nika:* -- no external dependencies.

MCP Integration

Nika is an MCP-native client. Connect to any Model Context Protocol server.

mcp:
  web_search:
    command: npx
    args: ["-y", "@anthropic/mcp-web-search"]

tasks:
  - id: search
    invoke: { mcp: web_search, tool: search, params: { query: "..." } }

  - id: agent_task
    agent:
      prompt: "Research this topic thoroughly"
      mcp: [web_search]
      max_turns: 10

nika serve -- workflows as HTTP endpoints

Expose any workflow as a REST API. SDKs for Rust, Node.js, and Python.

nika serve --port 3000

curl -X POST http://localhost:3000/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"workflow": "news.nika.yaml", "inputs": {"topic": "AI"}}'

SSE streaming, job queues, concurrent execution, and per-job isolation built in.

Terminal UI

Three views: Studio (editor + DAG), Command (chat + execution), Control (settings).

+-----------------------------------------------------------------------+
| Nika Studio                                              v0.71.0      |
|-----------------------------------------------------------------------|
| +- Files --------+ +- Editor ------------------------------------+   |
| | > workflows/   | |  1 | schema: "nika/[email protected]"           |   |
| |   deploy.nika  | |  2 | provider: claude                       |   |
| |   review.nika  | |  3 | tasks:                                 |   |
| +- DAG ----------+ |  4 |   - id: research                       |   |
| | [research]--+  | |  5 |     agent:                             |   |
| |      |      |  | |  6 |       prompt: "Find AI papers"         |   |
| | [analyze] [e]  | +--------------------------------------------+   |
| |      |      |  |                                                    |
| | [  report   ]  | Tree-sitter highlighting | LSP | Git gutter       |
| +----------------+ Vi/Emacs modes | Fuzzy search | Undo/redo         |
+-----------------------------------------------------------------------+
| [1/s] Studio  [2/c] Command  [3/x] Control                           |
+-----------------------------------------------------------------------+

Language Server

Full LSP with 16 capabilities: completion, hover, go-to-definition, diagnostics, semantic tokens, code actions, inlay hints, CodeLens, rename, formatting, and more.

cargo install nika-lsp                                # standalone
code --install-extension supernovae.nika-lang         # VS Code

Interactive Course

12 levels. 44 exercises. From shell commands to full AI orchestration.

nika init --course
nika course next
nika course hint

Benchmarks

Real benchmarks. Real tasks. No cherry-picking.

RAM usage -- "Summarize 10 web pages" task

Nika uses 5x less RAM than LangChain for the same task.

Nika vs. Python -- the deployment story

A Raspberry Pi can run Nika. A GitHub Action can run Nika. A $5/month VPS can run Nika.

Agent reliability

Architecture

flowchart TD
    classDef phase fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    classDef verb fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    classDef backend fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff

    YAML[".nika.yaml"]:::phase
    RAW["Parse (source spans)"]:::phase
    ANA["Analyze (validate + resolve)"]:::phase
    LOW["Lower (runtime types)"]:::phase
    DAG["DAG Engine"]:::phase

    YAML --> RAW --> ANA --> LOW --> DAG

    subgraph Verbs
        INF[infer]:::verb
        EXC[exec]:::verb
        FET[fetch]:::verb
        INV[invoke]:::verb
        AGT[agent]:::verb
    end

    DAG --> INF & EXC & FET & INV & AGT

    subgraph Backends
        PROV["9 Providers"]:::backend
        MCPS["MCP Servers"]:::backend
        BUILT["62 Builtin Tools"]:::backend
        CAS["CAS Media Store"]:::backend
    end

    INF & AGT --> PROV
    INV & AGT --> MCPS
    INV --> BUILT
    BUILT --> CAS

Three-phase AST (inspired by rustc): Raw (parse with source spans) --> Analyzed (validate, resolve bindings) --> Lowered (concrete runtime types). The immutable DAG is built from petgraph for safe concurrent execution.

17 workspace crates:

tools/
  nika/             CLI entry point                    cargo install nika
  nika-engine/      Embeddable runtime                 cargo add nika-engine
  nika-core/        AST, types, catalogs               zero I/O
  nika-event/       EventLog, TraceWriter
  nika-mcp/         MCP client (rmcp)
  nika-media/       CAS store, media processor
  nika-storage/     Storage abstraction
  nika-daemon/      Background daemon + secrets
  nika-init/        Project scaffolding + course
  nika-cli/         CLI subcommands
  nika-tui/         Terminal UI (ratatui)
  nika-display/     Render engine
  nika-lsp-core/    Protocol-agnostic LSP
  nika-lsp/         Standalone LSP binary
  nika-serve/       HTTP server
  nika-sdk/         Rust SDK
  nika-vault/       Encrypted credential store

Install

nika --version       # nika 0.71.0
nika doctor          # full system health check

# Minimal build
cargo install --path tools/nika --no-default-features

# Custom features
cargo install --path tools/nika --features "tui,native-inference,media-core"

Documentation

CLI at a glance

nika run flow.nika.yaml          # execute workflow
nika run flow.nika.yaml --resume # re-run, skip completed tasks
nika check flow.nika.yaml       # validate without executing
nika test flow.nika.yaml        # test with mock provider
nika lint flow.nika.yaml        # best-practice linting
nika explain flow.nika.yaml     # human-readable summary
nika graph flow.nika.yaml       # visualize DAG
nika ui                          # TUI
nika chat                        # direct chat mode
nika serve --port 3000           # HTTP API
nika init                        # scaffold project
nika init --course               # interactive course
nika course next                 # next exercise
nika provider list               # API key status
nika model list                  # available models
nika mcp list                    # MCP servers
nika doctor                      # system health
nika showcase list               # browse 115 example workflows

Contributing

git clone https://github.com/supernovae-st/nika.git
cd nika
cargo build                       # build all 17 crates
cargo test --workspace --lib      # 10,000+ tests (safe, no keychain popups)
cargo clippy -- -D warnings       # zero warnings policy

Note: cargo test without --lib runs contract tests that trigger macOS Keychain popups. Always use --lib.

See CONTRIBUTING.md for full guidelines.

License

AGPL-3.0-or-later -- Nika is free software. Use it, study it, share it, improve it.

The AGPL protects the commons: if you modify Nika and offer it as a hosted service, you share your changes back. For CLI usage, there are zero restrictions. Commercial use is welcome.

Read the Manifesto to understand why.