athanor-sdk 0.8.14

Multi-agent verification orchestration -- LLMs propose, formal tools prove, every change is machine-checked

kairos

Multi-agent verification orchestration for hardware and software.

LLMs can propose RTL optimizations, but they cannot prove those optimizations are correct. A single model call that claims "area reduced by 12%" has no way to guarantee functional equivalence with the original design. Kairos closes that gap: it orchestrates specialized agents (proposer, reviewer, counterexample analyst) through formal verification tools (EBMC, yosys, Lean) in a closed loop where every proposed change is machine-checked before acceptance.

kairos optimize block.sv runs a multi-agent loop: the proposer generates candidates, EBMC k-induction proves functional equivalence, yosys measures the real area delta, and the reviewer challenges the result. What ships is not what the LLM said works -- it is what the formal tools proved correct.

Kairos is a CLI with optional MCP server integration. Connect it to Claude Code, Kiro, or Cursor with athanor-sdk[mcp], and your agent gets verification tools that return machine-checked results, not LLM opinions.

Why agents need guardrails

Every agent in the kairos loop has a different role and a different incentive. The proposer optimizes, the reviewer challenges, the counterexample analyst actively tries to break the proposal. Only changes that survive all three reach formal verification. And formal verification is not simulation or testing -- it is mathematical proof over all possible inputs.

The guardrail stack:

• Pre-verification gates reject bad proposals before they reach formal tools: structural gate (cell count must decrease), toggle power gate (no >20% power regression)
• Bounded model checking (EBMC) proves properties hold for all states up to depth k
• Equivalence checking (yosys) proves the optimized netlist matches the original
• Counterexample generation refutes invalid proposals with concrete failing traces
• Trust boundary separates LLM-touching code from certificate generation (AST-lint enforced)
• Block memory tracks refuted approaches so agents cannot re-propose known failures
• Certificate chain with sha256 provenance from source through proof to output

Focus areas

Domain	Verification engine	What kairos checks
General software	mypy, hypothesis, CrossHair, mutmut	Types, properties, symbolic contracts, mutation testing
Chip design (RTL)	EBMC, yosys	Equivalence, safety properties, area/power optimization
Accelerator kernels	NKI runtime, Lean 4	Custom kernel correctness, formal proof gate
Networking protocols	EBMC, z3	Congestion control properties (BBR, CUBIC, Reno convergence)
Theorem proving	Lean 4	Proof verification, sorry closure, axiom auditing
Authorization policy	Cedar	permit/forbid policy correctness

Kairos is built by kairos. We use our own verification and anti-hallucination tools to develop, test, and ship kairos itself. Every bug found by kairos repair --review on our own codebase makes the tool stronger.

Quick start

pip install

pip install athanor-sdk                 # imports as: kairos
pip install 'athanor-sdk[types,verify]' # full Python verification deps

# If 'kairos' is not found after install, add ~/.local/bin to PATH:
# export PATH="$HOME/.local/bin:$PATH"

kairos setup                     # zero-config wizard
kairos doctor                    # verify your environment

# Verify any codebase (no LLM required)
kairos verify block.sv           # chip design (RTL)
kairos verify kernel.py          # accelerator kernel
kairos verify src/               # Python layers backed by installed extras

# Find + fix bugs (requires LLM API key)
kairos repair --review .         # diagnose issues across the project

Base pip install athanor-sdk gives the CLI, core libraries, and health checks. Full Python verification needs athanor-sdk[types,verify]; MCP IDE integration needs athanor-sdk[mcp]. RTL verification also needs yosys/EBMC/verilator, which are included in the Docker image.

Docker (includes all verification engines)

# Authenticate with GitHub Container Registry (one-time setup)
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

docker pull ghcr.io/athanor-ai/kairos:latest
docker run --rm -v $PWD:/work ghcr.io/athanor-ai/kairos:latest verify /work/block.sv
docker run --rm -v $PWD:/work ghcr.io/athanor-ai/kairos:latest verify /work/train.py
docker run --rm -e ANTHROPIC_API_KEY -v $PWD:/work ghcr.io/athanor-ai/kairos:latest optimize /work/block.sv

The Docker image includes yosys, EBMC, verilator, and all other engines. No additional installs needed. GITHUB_TOKEN needs read:packages scope (create at github.com/settings/tokens).

Commands

design -- create RTL from natural language (requires LLM)

kairos design "8-entry FIFO with sync reset"     # spec + architecture + RTL
kairos design --spec fifo_spec.sv                 # skip spec-gen, start from SVA
kairos design "pipelined ALU" --output ./alu/     # custom output directory

optimize -- area/power reduction with formal proof (requires LLM)

kairos optimize block.sv                          # propose + verify + measure
kairos optimize block.sv --estimate-only          # preview strategies + cost, no LLM
kairos optimize block.sv --compound 5             # 5 iterative rounds
kairos optimize block.sv --liberty cells.lib      # technology-mapped cell counts
kairos optimize block.sv --local-only             # zero network except LLM API
kairos optimize kernel.py                         # auto-detects NKI kernels (AWS Neuron NKI dispatch supported)

verify -- auto-detect domain, multi-layer checking (no LLM required)

kairos verify block.sv                            # RTL: yosys + EBMC bounded model check
kairos verify src/                                # directory: walks all files
kairos verify my_cca.py                           # Python CCA: telos + installed Python layers
kairos verify proof.lean                          # Lean: lake build + sorry check

Auto-detects the verification domain from file content, not just extension. A Python file with networking patterns (cwnd, ssthresh, pacing_rate) gets telos protocol verification, then any installed Python verification layers such as mypy, Hypothesis, CrossHair, and mutmut.

repair -- find + fix + verify (requires LLM)

kairos repair block.sv                            # detect issues, propose fixes, verify
kairos repair --review block.sv                   # diagnose only, no changes
kairos repair --focus security src/               # focus on security findings

explore -- fork and compare design variants (requires LLM)

kairos explore block.sv                           # architecture exploration
kairos explore block.sv --fork area timing power  # parallel variant comparison

doctor -- environment health check

kairos doctor                                     # check deps, license, engines, models
kairos doctor --json                              # machine-readable output

support-bundle -- collect diagnostics for debugging

kairos support-bundle                             # human-readable diagnostic info
kairos support-bundle --json                      # machine-readable for support tickets

quickstart -- zero to first verify

kairos quickstart                                 # detect env, install deps, run first verify

watch -- continuous verification

kairos watch .                                    # re-verify on file change
kairos watch src/ --interval 30                   # custom scan interval

setup -- first-run configuration

kairos setup                                      # interactive wizard
kairos setup --user-install                       # install EBMC to ~/.local/bin (no sudo)
kairos setup --check                              # validate current config

Example Designs

These examples live in the source repository, not in the minimal PyPI wheel. Run them from a repo checkout, or use the Docker image with a mounted checkout:

git clone https://github.com/athanor-ai/athanor-kairos.git
cd athanor-kairos

# Combinational (optimize works well)
kairos optimize examples/synthetic/hamming_encoder.sv    # -28.57% area reduction
kairos optimize examples/synthetic/alu_onehot.sv         # -10.83% area reduction

# Sequential networking
kairos optimize examples/sv-networking-reno/reno_sender.sv  # -54.24% area reduction

# Verification canaries (known-bad, should REFUTE)
kairos verify examples/golden/alu_wrong_op.sv            # wrong ALU operation → REFUTED
kairos verify examples/golden/fifo_off_by_one.sv         # FIFO pointer bug → REFUTED
kairos verify examples/golden/counter_no_reset.sv        # missing reset → REFUTED

More designs in examples/benchmarks/rtllm/ (multiplier, divider, FSM, signal processing). See examples/golden/README.md for the full canary matrix with honest measured verdicts.

How it works

1. Propose: LLM generates optimization candidates (local or cloud)
2. Verify: EBMC k-induction proves functional equivalence
3. Measure: yosys synthesis confirms real area reduction
4. Report: honest verdict with claim verification

Every measurement from a tool, not an LLM estimate. Area from yosys synthesis, equivalence from EBMC, timing from OpenSTA (when .lib provided).

Configuration (kairos.yaml)

Drop a kairos.yaml in your project root:

model: claude-sonnet-4-6

methodology:
  verification:
    require_equivalence_proof: true
    minimum_bound_k: 10
  certificate:
    require_all_properties_proved: true

agents:
  reviewer:
    enabled: true
    severity_threshold: medium

Precedence: CLI flags > kairos.yaml > environment variables > defaults.

Agent integration (MCP)

{
  "mcpServers": {
    "kairos": {
      "command": "kairos",
      "args": ["mcp", "serve"]
    }
  }
}

Works with Claude Code, Kiro, Cursor, and any MCP-compatible IDE. 41 tools available including kairos_optimize, kairos_verify, kairos_repair, kairos_explore, and kairos_doctor.

Local-only mode

kairos optimize block.sv --local-only
kairos optimize block.sv --proposer-backend local  # RTL never leaves machine

No trace upload, no telemetry. Only the LLM API call leaves your machine. Use --proposer-backend local with ollama/vLLM for full air-gapped operation.

Requirements

• Python 3.10+
• kairos setup installs everything else

Optional extras:

• pip install athanor-sdk[types]: mypy for Python type checking layer
• pip install athanor-sdk[verify]: Hypothesis, CrossHair, and mutmut for Python property/symbolic/mutation layers
• pip install athanor-sdk[mcp]: MCP server for IDE integration

Optional engines (for full verification):

• yosys + EBMC (hardware equivalence)
• Lean 4 (theorem proving)
• OpenSTA (timing analysis, requires Liberty .lib)

Run kairos doctor to check your setup.

Documentation

In Docker: see /opt/kairos-docs/ for bundled guides.

• Getting Started (getting-started.md)
• Installation Guide (installation.md)
• Enterprise RTL Quickstart (enterprise-rtl-quickstart.md)

License

Commercial license required for production use. Free evaluation available. Visit athanor-ai.com for access.