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>
This commit is contained in:
Juan
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user