Cairn

Ein agentischer Incident-Analyse-Copilot. Fragen Sie auf Englisch „Warum ist die Checkout-Latenz um 3 Uhr morgens angestiegen?“; Cairn fragt den Observability-Stack ab, korreliert mit der Deployment-Zeitleiste, ruft das relevante Runbook ab und schlägt eine Ursache mit Belegen vor – und kann eine Behebung ausführen, hinter einem menschlichen Genehmigungs-Gate.

Dieses Repository implementiert docs/architecture.md.

Das Dashboard

Das begleitende npm-Paket (npx @nouman-amjad/cairn dashboard) stellt ein Live-Dashboard für jedes Projekt bereit – ohne Build-Schritt, ohne Abhängigkeiten, ohne Netzwerk.

Related MCP server: semley

Die vier Verpflichtungen und wo sie im Code umgesetzt sind

Aufbau

packages/
  cairn-core/          domain model, config, auth, DB, sensitivity, artifacts
  cairn-mcp-kit/       MCP scaffolding: identity, OPA guard, result capping, versioning
services/
  cairn-gateway/       OIDC, rate limits, cost budgets, circuit breaker, SSE fan-out
  cairn-orchestrator/  the agent loop as a state machine persisted to Postgres
  cairn-router/        model routing, cost accounting, vLLM + Anthropic clients
  cairn-approval/      approval state machine and the Slack gate
  cairn-mcp-observability/  metrics, logs, traces, deploys, artifacts
  cairn-mcp-runbooks/       hybrid search, ingest, past-incident recall
  cairn-mcp-actions/        approval-gated write tools
  cairn-eval/          30 scenarios, 7 metrics, the CI gate, a seeded stack
  cairn-cli/           `cairn ask "why did checkout spike?"`
ui/                    Next.js: chat, trajectory viewer, approvals
cairn-deploy/          Helm chart, ArgoCD app-of-apps, OPA bundle, prompts
cairn-infra/           Terraform: VPC, EKS, RDS, Karpenter, IRSA, S3
docker/                one Dockerfile for all Python services, plus vLLM
docs/adr/              14 architecture decision records

cairn-deploy und cairn-infra sind hier zur Überprüfung eingebunden. In Produktion sind sie separate Repositories mit separaten Lebenszyklen – siehe ADR-013.

Erste Schritte

make install     # uv sync + npm ci
make up          # Postgres (pgvector), Redis, MinIO, OPA
make migrate
make test        # 246 tests
make selfcheck   # 21 module self-checks
make eval        # 30 scenarios through the real agent loop

Für all das sind weder GPU noch API-Schlüssel erforderlich. make eval läuft im heuristischen Modus, der die gesamte Pipeline durchläuft – Schleife, Tool-Capping, Persistenz, die sieben Metriken, das Gate – mit einem skriptbasierten Stellvertreter anstelle eines Modells. Siehe die Einschränkungen.

Um mit echten Modellen zu laufen, setzen Sie CAIRN_ROUTER_ANTHROPIC_API_KEY und richten Sie CAIRN_ROUTER_VLLM_URL auf einen vLLM-Server.

Debugging mit einem MCP-Client

Jeder MCP-Server spricht sowohl stdio als auch Streamable HTTP:

make mcp-stdio
# or, the way an outside user would:
uvx cairn-mcp-observability --stdio

Richten Sie Cursor, Zed oder einen anderen MCP-Client darauf aus und Sie sehen genau das, was der Agent sieht. Das kostet etwa zwanzig Zeilen (ADR-002) und zahlt sich beim ersten Mal aus, wenn ein Tool-Ergebnis überhaupt nicht wie erwartet aussieht.

Was verifiziert ist und was nicht

Um konkret zu sein, denn „es funktioniert“ ist keine Behauptung, die man vage aufstellen sollte.

Verifiziert durch Ausführung hier:

• 246 Tests bestehen gegen eine echte PostgreSQL 16 + pgvector, einschließlich der Sicherheitseigenschaften des Genehmigungs-Gates (keine Selbstgenehmigung, keine doppelte Ausführung, keine Ausführung ohne Genehmigung, ein Append-only-Audit-Log, das durch einen Datenbank-Trigger erzwungen wird) und der Router-Eigenschaft, dass eingeschränkte Daten niemals ein Cloud-Modell erreichen – erschöpfend über jede Aufgabenklasse und jeden Tier-Zustand geprüft.

• 21 Modul-Selbstchecks bestehen.

• Die Alembic-Migration lässt sich sauber auf eine echte Datenbank anwenden.

• 12/12 OPA-Policy-Tests bestehen.

• Die 30-Szenarien-Eval läuft Ende-zu-Ende durch die echte Agent-Schleife; alle sieben Metriken liegen über dem Ziel und das Gate blockiert korrekt sowohl eine simulierte Regression als auch einen Lauf unter dem Ziel.

• Die UI besteht den Typprüfer und baut. Die fünf CLI-Befehle werden aufgelöst.

Hier nicht verifiziert, und warum:

• Eval-Genauigkeitszahlen. Die festgelegte Baseline ist der heuristische Modus, der die Harness statt des Agenten bewertet. Echte Zahlen erfordern make eval-record gegen einen Live-Router. Der LLM-Ursachen-Richter ist gebaut, aber nicht kalibriert – niemand hat 100 Läufe gelabelt, daher ist κ unbekannt.

• Terraform. Kein terraform-Binary in dieser Umgebung; fmt, validate und tflint laufen in CI. Es wurde nichts auf ein AWS-Konto angewendet.

• Helm-Rendering. helm lint, template und kubeconform laufen in CI für alle drei Umgebungen. Sie wurden nicht lokal ausgeführt.

• Jede Kostenangabe in docs/cost.md. Die Buchhaltung, die sie messen würde, ist gebaut und getestet; der Verkehr, um sie zu füllen, existiert nicht.

• Die vLLM-Leistungstabelle. Arithmetik aus Speicherbandbreite, nicht Messung. docs/inference.md gibt den Benchmark-Befehl und eine Falsifikationsschwelle an.

• Chaos-Tests. Phase 7 der Roadmap wurde nicht ausgeführt.

docs/roadmap.md verfolgt dies Phase für Phase.

Dokumentation

• docs/architecture.md — das Design, das dies implementiert

• docs/adr/ — 14 Entscheidungsprotokolle, jedes mit seiner Konsequenz

• docs/security.md — Bedrohungsmodell und wo jede Kontrolle lebt

• docs/inference.md — GPU-Dimensionierung, KV-Cache-Arithmetik, vLLM-Flags

• docs/cost.md — das Kostenmodell, einschließlich ob sich die GPU amortisiert

• docs/operations.md — Runbook: was alarmiert, was zu tun ist

• docs/roadmap.md — Phasen, Risiken und was tatsächlich erledigt ist

• services/cairn-eval/README.md — wie man einen Gate-Fehler liest