# kanros

[![Version](https://img.shields.io/github/v/release/kanros/kanros?include_prereleases&sort=semver&label=release)](https://github.com/kanros/kanros/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue)](#license)

A fast, type-safe Rust framework for evaluating and red-teaming LLM
applications. Single binary. Local-first. No telemetry. No cloud account.

> Status: **`v0.1.0-rc.1` in preparation** (branch
> `release/v0.1.0-rc.1-prep`; not yet tagged). All 11 workstreams have
> landed (27 providers, 44 assertions, the red-team fleet, WASM + JS
> plugin hosts, RAG and agent eval, TUI and Web UI, share endpoint,
> cargo-dist release pipeline). The `v0.1.0-rc.1` tag will be cut when
> this branch merges; the rc tag then enters a 7-day soak before
> promotion to `v0.1.0` GA. See [`CHANGELOG.md`](./CHANGELOG.md) for the
> release notes in progress, [`DESIGN.md`](./DESIGN.md) for the decision
> log, and [`STABILITY.md`](./STABILITY.md) for the trait-freeze gate.

## Installation

### Pre-built binaries

cargo-dist publishes pre-built binaries for macOS (arm64 + x86_64),
Linux (glibc + musl, x86_64 + arm64), and Windows (x86_64) on every
tagged release.

> **Note:** no release has been published yet — the installer commands
> below will work once the first release (`v0.1.0-rc.1`) is tagged and
> published. Until then, use [Build from source](#build-from-source).

**macOS / Linux (shell installer):**

```sh
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/kanros/kanros/releases/latest/download/kanros-installer.sh \
  | sh
```

**Windows (PowerShell installer):**

```powershell
irm https://github.com/kanros/kanros/releases/latest/download/kanros-installer.ps1 | iex
```

**Direct download:**  
Tarballs and zips for every target triple (plus SHA256 checksums) are
attached to each GitHub Release.

### Build from source

```bash
cargo install --path crates/kanros-cli
```

Requires Rust ≥ 1.88.

## Quick start

```bash
cargo build --workspace
cargo run -p kanros-cli -- run -c examples/smoke/kanros.yaml
```

Expected output:

```
kanros run <uuid>
  cells: 2 passed, 0 failed, 0 errored (… ms)
  [PASS] echo:identity   prompt#0  test#0  say hello
  [PASS] echo:identity   prompt#0  test#1  say world
```

The smoke fixture uses the built-in `echo` provider — no network, no API key.

## CLI

```text
kanros run        --config kanros.yaml         # run an eval suite
kanros validate   --config kanros.yaml         # parse and check without running
kanros schema                                  # print the JSON Schema (workstream G)
kanros version                                 # print binary and trait-layer versions
```

Exit codes follow §4.12 of the spec: `0` pass, `1` assertion failures,
`2` config error, `3` provider error.

## Repository layout

| Crate | Purpose |
|---|---|
| `kanros-core` | The frozen trait layer. `Provider`, `Assertion`, `Config`, `EvalResult`. |
| `kanros-providers` | Provider registry + per-provider sub-crates (`echo`, `openai`, `anthropic`, …). |
| `kanros-assertions` | Assertion engine (44 variants, organized by family). |
| `kanros-runner` | Eval loop: concurrency, retries, cancellation, cache. |
| `kanros-cache` | SQLite-backed response cache. |
| `kanros-redteam` | Red-team plugins and attack strategies. |
| `kanros-rag` / `kanros-agent` | RAG and agent/tool-call eval. |
| `kanros-templating` | minijinja prompt templating + URI loaders. |
| `kanros-datasets` | CSV/JSONL/HF dataset loaders. |
| `kanros-report` | Terminal/JSON/JUnit/SARIF/HTML output. |
| `kanros-plugin` | WASM (component model) plugin host. |
| `kanros-share` | Optional self-hostable share endpoint. |
| `kanros-cli` | The `kanros` binary. |
| `kanros-tui` | Ratatui live view. |
| `kanros-webui-server` | axum + rust-embed Web UI server. |

See [`crates/`](./crates/) for the source.

## Configuration

YAML by default, TOML and JSON supported, all parsing through the same
serde struct. A minimal config:

```yaml
providers:
  - id: echo:identity
prompts:
  - "summarize: {{ article }}"
tests:
  - vars:
      article: "..."
    assert:
      - type: contains
        value: "key findings"
      - type: length
        max: 1000
```

For the full schema see [`crates/kanros-core/src/config.rs`](./crates/kanros-core/src/config.rs)
and [`crates/kanros-core/src/assertion.rs`](./crates/kanros-core/src/assertion.rs).

## Documentation

The documentation is built with [mdbook] from sources under
[`docs/`](./docs/). The deploy pipeline
([`.github/workflows/docs-deploy.yml`](./.github/workflows/docs-deploy.yml))
targets **<https://docs.kanros.dev>** (the API reference will be mounted
at `/api/`), but the `kanros.dev` domain was only registered on
2026-07-13 and the docs site is not serving yet — build locally in the
meantime.

To build and serve locally:

```bash
cargo install mdbook    # one-time
mdbook serve docs       # http://localhost:3000 with live reload
mdbook build docs       # static output in target/docs
```

Highlights:

- [Introduction](./docs/src/introduction.md) — what kanros is and how it differs from promptfoo.
- [Quickstart](./docs/src/getting-started/quickstart.md) — minimal `kanros.yaml` + `kanros run`.
- [Migrating from promptfoo](./docs/src/getting-started/from-promptfoo.md) — `kanros migrate` walkthrough.
- [Assertions catalogue](./docs/src/concepts/assertions.md) — every assertion variant.
- [WASM plugins](./docs/src/plugins/wasm.md) and [JavaScript plugins](./docs/src/plugins/javascript.md) — custom graders.
- [Troubleshooting](./docs/src/troubleshooting.md) — common failure modes and fixes.

[mdbook]: https://rust-lang.github.io/mdBook/

## License

Dual-licensed under Apache-2.0 or MIT, at your option.
