Docs

Get running.

Requires Python 3.11+ and uv. Offline by default — no API key.

Quick start

git clone https://github.com/dibakshya01/blue-kakapo.git
cd blue-kakapo          # a path without spaces avoids a uv editable-install quirk
uv sync
uv run bk serve         # http://127.0.0.1:8713  — the coworker dashboard

Then triage from the CLI, or score the bundled dataset honestly:

echo '{"title":"C2 beacon","severity":"high","dst_ip":"198.51.100.23"}' | uv run bk triage -
uv run bk eval          # prints precision / recall / FALSE-NEGATIVE RATE

Run with a real model (switchable anytime)

BK_PROVIDER=anthropic BK_ANTHROPIC_API_KEY=... uv run bk serve
BK_PROVIDER=ollama   BK_MODEL=qwen3:8b        uv run bk serve   # local, in-network

Docker & Kubernetes

docker compose -f deploy/compose/docker-compose.yml up        # api + pgvector
helm install blue-kakapo deploy/helm/blue-kakapo -n blue-kakapo --create-namespace

Hardened chart (non-root, read-only rootfs), OIDC SSO, secrets via OpenBao, cosign-signed images + SBOM, and a Zarf air-gap package. See deploy/helm/README.md.

CLI

Command	Does
`bk serve`	Run the control plane + dashboard.
`bk triage <file\|->`	Triage one alert (JSON) and print the verdict.
`bk eval [--dataset] [--json]`	Run the evaluation harness (reports the FNR).
`bk info`	Show resolved config (secrets redacted).

HTTP API (selected)

Endpoint	Purpose
`POST /api/ingest`	Triage a raw alert → Case (+verdict).
`GET /api/cases[/{id}[/ledger]]`	List / detail / replay the verified ledger trail.
`POST /api/cases/{id}/respond`	Run RESP — Guardian-gated containment.
`GET /api/agents`	The 14-agent roster + each AgBOM + Rule-of-Two.
`GET /api/eval`	Evaluation report (precision/recall/FNR/cost).
`POST /api/provider/switch`	Switch LLM provider/model at runtime.
`WS /api/ws`	Live case/run events for the dashboard.
`/scim/v2/Users`	SCIM provisioning/deprovisioning (admin).

The module map

Package	What's inside
`core/`	deterministic kernel, hash-chained ledger, crypto-shred, store, bus
`agents/`	Agent SDK + the 14-agent roster + orchestrator
`guardian/`	ACS policy engine, approvals, injection + Rule-of-Two
`connectors/`	connector SDK, mock/Wazuh/Elastic, MCP client
`memory/`	opt-in case memory (folder/pgvector) + poisoning defenses
`providers/`	model-agnostic gateway (offline/anthropic/openai/ollama)
`security/`	authn (open/local/OIDC), RBAC, secrets, SCIM
`eval/`	evaluation harness + documented dataset

Full guides in the repo's docs/, including the security model + AISVS self-assessment and what it can & cannot do.