docs: README, ARCHITECTURE, roadmap futuro y manual de QA del dashboard

- 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 <noreply@anthropic.com>
2026-05-11 13:02:06 +02:00
parent 03941acb52
commit 6216689511
4 changed files with 245 additions and 0 deletions
@@ -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/<name>/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).