Cairn

Un copiloto agéntico de análisis de incidentes. Pregunte «¿por qué la latencia del checkout se disparó a las 3 de la madrugada?» en lenguaje natural; Cairn consulta la pila de observabilidad, la correlaciona con la cronología de despliegues, recupera el runbook relevante y propone una causa raíz con evidencia — y puede ejecutar una remediación, tras una compuerta de aprobación humana.

Este repositorio implementa docs/architecture.md.

El panel

El paquete npm complementario (npx @nouman-amjad/cairn dashboard) sirve un panel local en vivo para cualquier proyecto — sin paso de compilación, sin dependencias, sin red.

Related MCP server: IncidentIQ

Los cuatro compromisos y dónde residen en el código

Estructura

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 y cairn-infra están incorporados aquí para su revisión. En producción son repositorios separados con ciclos de vida independientes — consulte ADR-013.

Primeros pasos

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

No se necesitan GPU ni claves de API para nada de lo anterior. make eval se ejecuta en modo heurístico, que ejercita todo el pipeline — el bucle, el límite de herramientas, la persistencia, las siete métricas, la compuerta — con un sustituto preprogramado en lugar de un modelo. Véanse las advertencias a continuación.

Para ejecutar contra modelos reales, configure la variable CAIRN_ROUTER_ANTHROPIC_API_KEY y apunte CAIRN_ROUTER_VLLM_URL a un servidor vLLM.

Depuración con un cliente MCP

Cada servidor MCP se comunica tanto mediante stdio como mediante Streamable HTTP:

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

Apunte a él Cursor, Zed o cualquier otro cliente MCP y verá exactamente lo que ve el agente. Eso son unas veinte líneas (ADR-002) y se amortiza la primera vez que el resultado de una herramienta no se parece en nada a lo esperado.

Qué está verificado y qué no

Para ser concretos: «funciona» no es una afirmación que valga la pena hacer de forma vaga.

Verificado ejecutándolo aquí:

• 246 pruebas pasan contra un PostgreSQL 16 + pgvector real, incluidas las propiedades de seguridad de la compuerta de aprobación (sin autoaprobación, sin doble ejecución, sin ejecución sin aprobación, un registro de auditoría de solo añadido impuesto por una base de datos) y la propiedad del router de que los datos restringidos nunca llegan a un modelo en la nube — comprobado exhaustivamente en toda clase de tarea y estado de nivel.

• 21 autocomprobaciones de módulo ejecutan correctamente.

• La migración de Alembic se aplica limpiamente a una base de datos real.

• 12/12 pruebas de políticas de OPA pasan.

• La evaluación de 30 escenarios se ejecuta de extremo a extremo através del bucle real del agente; las siete métricas están por encima del objetivo y la compuerta bloquea correctamente tanto una regresión simulada como una ejecución por debajo del objetivo.

• La interface válida el tipado y compila. Los cinco comandos de la CLI se resuelven correctamente.

No verificado aquí, y por qué:

• Cifras de exactitud de la evaluación. La línea base establecida es el modo heurístico, que puntúa el banco de pruebas en lugar del agente. Los números reales requieren ejecutar make eval-record contra un enrutador en vivo. El juez de causas LLM está construido pero no calibrado — nadie ha etiquetado 100 ejecuciones de referencia, por lo que κ es desconocida.

• Terraform. No hay binario terraform en este entorno; fmt, validate y tflint se ejecutan en CI. No se ha aplicado nada a una cuenta de AWS.

• Rendering de Helm. helm lint, template y kubeconform se ejecutan en CI para los tres entornos; no se han ejecutado localmente.

• Cada cifra de coste en docs/cost.md. La contabilidad que las mediría está construida y probada; el tráfico para poblarlas aún no existe.

• La tabla de rendimiento de vLLM. Es aritmética a partir del ancho de banda de la memoria, no medición. En docs/inference.md se indica el comando de evaluación comparativa y un umbral de falsación.

• Pruebas de caos. La fase 7 de la hoja de ruta no se ha ejecutado.

docs/roadmap.md hace seguimiento de esto fase por fase.

Documentación

• docs/architecture.md — el diseño que este repositorio implementa

• docs/adr/ — 14 registros de decisión, cada uno con su consecuencia

• docs/security.md — modelo de amenazas y dónde reside cada control

• docs/inference.md — dimensionado de GPU, aritmética de la cached de KV-cache, flags de vLLM

• docs/cost.md — el modelo de costes, incluyendo si la GPU se amortiza por sí sola

• docs/operations.md — runbook: qué alertas, qué hacer

• docs/roadmap.md — fases, riesgos y lo que se ha hecho realmente

• services/cairn-eval/README.md — cómo leer un fallo de la compuerta