From 6216689511ef04f02f603ed988cccc732c476b7c Mon Sep 17 00:00:00 2001 From: Juan Date: Mon, 11 May 2026 13:02:06 +0200 Subject: [PATCH] docs: README, ARCHITECTURE, roadmap futuro y manual de QA del dashboard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: pitch, arquitectura, quickstart, demo guiada en 3 pasos, tabla de capacidades, estructura del repo, comandos de tests. - ARCHITECTURE.md: patrones (Strategy, config-over-code, fail-closed, trazabilidad), tabla de persistencia, patrón HITL, observabilidad, errores. - docs/futuro.md: roadmap post-MVP. - docs/manual_qa.md: checklist del smoke manual del dashboard (5 páginas + PII + persistencia). Co-Authored-By: Claude Opus 4.7 --- ARCHITECTURE.md | 71 ++++++++++++++++++++++++++++++++ README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++ docs/futuro.md | 15 +++++++ docs/manual_qa.md | 58 ++++++++++++++++++++++++++ 4 files changed, 245 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 README.md create mode 100644 docs/futuro.md create mode 100644 docs/manual_qa.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..e647f2c --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,71 @@ +# AgentForge — Arquitectura técnica + +> Documento "vivo" con las decisiones técnicas. El spec original está en +> [`docs/superpowers/specs/2026-05-09-agentforge-design.md`](docs/superpowers/specs/2026-05-09-agentforge-design.md). + +## Visión general + +Two-tier: +- `agentforge-core` — FastAPI 8000. Dominio de gobierno, runtime LangGraph, + guardrails y persistencia. +- `agentforge-dashboard` — Streamlit 8501. Cliente HTTP del core. + +## Diagrama + +``` +┌─────────────────────┐ HTTP/JSON ┌─────────────────────┐ +│ Dashboard (Stream.) │ ───────────► │ Core (FastAPI) │ +└─────────────────────┘ └─────────┬───────────┘ + │ + ┌─────────────────────────┬────────┴──────┬────────────┐ + ▼ ▼ ▼ ▼ + LLM layer Guardrails layer LangGraph State + (Strategy pattern) (Strategy pattern) Runtime JSON+SQL+JSONL +``` + +## Patrones aplicados + +- **Strategy / Plugin**: `LLMProvider`, `GuardrailEngine`, `AgentRegistry`, + `PolicyStore` son `Protocol`s con varias implementaciones intercambiables + vía factory que lee `Settings`. +- **Configuration over code**: agentes y políticas como YAML versionados; + cambios sin redeploy. +- **Fail-closed por defecto**: errores en validadores cuentan como bloqueo. +- **Trazabilidad obligatoria**: `trace_id` UUID propagado por + middleware → structlog → API → JSONL. + +## Persistencia + +| Capa | Tecnología | Por qué | +|---|---|---| +| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). | +| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. | +| Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. | +| Logs de ejecuciones | JSONL append-only | Idem. | +| Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). | + +## HITL — Patrón + +Se usa la API dinámica `interrupt(payload)` de LangGraph ≥0.2 dentro del +nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo +(`risk_score >= threshold` o `requires_approval=True`). El cliente envía +`Command(resume={"approved_action_ids": [...]})` vía +`POST /executions/{trace_id}/approve`. + +## Observabilidad + +- `structlog` con renderer JSON. +- Middleware FastAPI inyecta `X-Trace-Id` y bind-ea contexto. +- Cada nodo del grafo añade un step a `decision_path` con `duration_ms`. + +## Errores + +- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego + `status=failed`. +- Validador: `fail_closed` por defecto. +- Schema mismatch en LLM output: 1 retry, luego `failed`. +- Checkpoint corrupto: 500 explícito (sin auto-recovery). + +## Decisiones pospuestas + +Ver [`docs/futuro.md`](docs/futuro.md). diff --git a/README.md b/README.md new file mode 100644 index 0000000..3817b34 --- /dev/null +++ b/README.md @@ -0,0 +1,101 @@ +# 🛡️ AgentForge + +Plataforma profesional de **gobernanza de agentes IA**: catalogación, versionado +de prompts y políticas, guardrails runtime, ejecución stateful con +Human-in-the-Loop, observabilidad y trazabilidad end-to-end. + +## ¿Por qué? + +Poner agentes IA en producción sin una capa de gobierno produce sistemas +opacos: prompts que cambian sin historial, validaciones inconsistentes, +acciones de alto impacto sin supervisión, sin auditoría de decisiones. +AgentForge aporta el plano de control mínimo que un equipo de plataforma +necesita antes de operar agentes con impacto real. + +## Arquitectura + +``` +┌───────────────────────── docker-compose ──────────────────────────┐ +│ │ +│ ┌─────────────────────┐ HTTP/JSON ┌────────────────────┐ │ +│ │ agentforge-dashboard│ ────────────────► │ agentforge-core │ │ +│ │ Streamlit :8501 │ ◄──────────────── │ FastAPI :8000 │ │ +│ └─────────────────────┘ └────────────────────┘ │ +│ │ +│ Strategy pattern (Protocol) para LLMProvider, GuardrailEngine, │ +│ AgentRegistry. Persistencia mixta: YAML (definiciones), JSON │ +│ (registry), JSONL (logs append-only), SQLite (checkpoints). │ +└────────────────────────────────────────────────────────────────────┘ +``` + +Detalles completos en [`ARCHITECTURE.md`](ARCHITECTURE.md). + +## Quickstart + +```bash +cp .env.example .env +docker compose up +``` + +Abre [http://localhost:8501](http://localhost:8501). + +Funciona out-of-the-box (`LLM_PROVIDER=mock`, sin API keys). Si quieres usar +Azure OpenAI real, edita `.env`. + +## Demo guiada (3 pasos) + +1. **Registro** → ver `incident_analyzer` y comparar `v1` vs `v2`. +2. **Ejecutar** → seleccionar el escenario `01_sip_registration_drop` y + pulsar *Invocar*. Verás el grafo recorrer validate_input → llm_reason + → validate_output → propose_actions → approve_gate y pausarse en HITL. +3. **Aprobaciones** → revisar las acciones propuestas (con risk_score y + rollback_plan), aprobar las seguras y comprobar que la ejecución + completa. + +## Capacidades implementadas + +| Feature | Ubicación | +|---|---| +| Agent Registry | `core/src/agentforge_core/registry/repository.py` | +| Versionado tipo Git | `agents//versions/` + `registry/versioning.py` | +| Guardrails runtime | `core/src/agentforge_core/guardrails/` | +| LangGraph stateful + checkpointing | `core/src/agentforge_core/runtime/` | +| Human-in-the-Loop | nodo `approve_gate` + endpoints `/approve` y `/reject` | +| Observabilidad | `observability/logging.py` (structlog + trace_id) | +| LLM provider abstraction | `core/src/agentforge_core/llm/` | +| Política versionada | `policies/default/versions/v1.yaml` | + +## Variables de entorno + +Ver [`.env.example`](.env.example). + +## Roadmap + +Ver [`docs/futuro.md`](docs/futuro.md). + +## Estructura del repositorio + +``` +agentforge/ +├── core/ servicio FastAPI +├── dashboard/ servicio Streamlit +├── agents/ definiciones declarativas (YAML) +├── policies/ políticas de guardrails +├── data/ estado runtime (gitignored) +├── tests/ pytest unit + integration +└── docs/ documentación adicional +``` + +## Tests + +```bash +make install +make test # solo unit +make test-all # unit + integration +make lint # ruff + mypy +make smoke # docker-compose + curl health +``` + +## Licencia + +MIT (a confirmar). diff --git a/docs/futuro.md b/docs/futuro.md new file mode 100644 index 0000000..d300cec --- /dev/null +++ b/docs/futuro.md @@ -0,0 +1,15 @@ +# Roadmap (post-MVP) + +- **NeMo Guardrails full**: configuración Colang con KB embedding + dialog rails. +- **Autenticación**: OAuth2/OIDC con MSAL para entornos Azure AD. +- **OpenTelemetry**: spans por nodo del grafo, métricas de violaciones por validador. +- **Multi-tenant**: `tenant_id` aislado por registry, política y datos. +- **Evaluadores LLM-as-judge**: regression suite que ejecuta cada agente + sobre escenarios canónicos y mide deriva. +- **UI de aprobación con SLA**: cola Kanban, reasignación entre operadores, + alertas cuando un HITL rebasa SLA. +- **Persistencia migrable a Postgres + pgvector**: requerido para alta + disponibilidad multi-instance. +- **Esquema de prompts mejorado**: variables tipadas en system_prompt + (Jinja-like), valores por entorno. +- **Promoción explícita draft → active** vía PR/aprobación. diff --git a/docs/manual_qa.md b/docs/manual_qa.md new file mode 100644 index 0000000..8e32f05 --- /dev/null +++ b/docs/manual_qa.md @@ -0,0 +1,58 @@ +# Smoke manual del dashboard + +> Esta lista cubre los flujos no automatizados (Streamlit). Ejecutar tras +> cambios visuales o estructurales del dashboard. + +## Setup + +```bash +cp .env.example .env +docker compose up -d +sleep 15 +``` + +Abrir [http://localhost:8501](http://localhost:8501). + +## 1) Registro + +- [ ] Aparece `incident_analyzer` en el desplegable. +- [ ] Detalle muestra version, owner, propósito, guardrails, system_prompt. +- [ ] Tabla de versiones lista `v1` y `v2`. +- [ ] Diff `v1 → v2` muestra cambios coloreados. + +## 2) Ejecutar + +- [ ] Botones de escenarios cargan texto en el textarea. +- [ ] Invocar `02_mos_degradation_pool_sbc` → status=`completed`, sin HITL, + decision_path con 6 steps. +- [ ] Invocar `01_sip_registration_drop` → status=`awaiting_approval`, + banner amarillo redirige a Aprobaciones. + +## 3) Aprobaciones + +- [ ] La ejecución pendiente aparece en el desplegable. +- [ ] Cada acción muestra risk_score con color, target y rollback_plan. +- [ ] Aprobar acciones seleccionadas → status=`completed`. +- [ ] Rechazo con razón → status=`failed`, error=`rejected_by_human`. + +## 4) Historial + +- [ ] Tab "Ejecuciones" lista todas las ejecuciones con summary. +- [ ] Detalle muestra trace + violations. +- [ ] Tab "Violaciones" filtrable por severity. + +## 5) Politicas + +- [ ] `default` aparece con sus validadores de input/output. +- [ ] Cada validador expandible con su config. + +## Bloqueo por PII (input) + +- [ ] Pegar `El cliente con NIF 12345678Z reporta caída`. +- [ ] Invocar → status=`blocked_by_guardrail`, violación `DetectPII`. + +## Persistencia + +- [ ] `docker compose down && docker compose up` → ejecuciones previas + siguen accesibles vía Historial; aprobaciones pendientes siguen + pendientes.