docs: añade docs/explicacion.md — guía didáctica del proyecto y sus módulos
Documento de alto nivel para terceros: las seis ideas clave, vista de los dos servicios y las capas del core, recorrido módulo a módulo con sus dependencias (quién depende de quién), el patrón Protocol+factory+Settings, el viaje completo de una petición (con diagrama de secuencia), la estrategia de persistencia (YAML/ JSON/JSONL/SQLite), glosario, mapa del repo y ruta de lectura. README enlaza a él. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Juan
@@ -28,7 +28,10 @@ necesita antes de operar agentes con impacto real.
|
|||||||
└────────────────────────────────────────────────────────────────────┘
|
└────────────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
Detalles completos en [`ARCHITECTURE.md`](ARCHITECTURE.md).
|
Detalles completos en [`ARCHITECTURE.md`](ARCHITECTURE.md). Para una explicación
|
||||||
|
didáctica de extremo a extremo (conceptos, recorrido por todos los módulos y sus
|
||||||
|
interrelaciones, y el viaje de una petición de principio a fin), ver
|
||||||
|
[`docs/explicacion.md`](docs/explicacion.md).
|
||||||
|
|
||||||
## Quickstart
|
## Quickstart
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,540 @@
|
|||||||
|
# AgentForge explicado de principio a fin
|
||||||
|
|
||||||
|
> **Para quién es esto.** Una guía didáctica para alguien que llega nuevo al
|
||||||
|
> proyecto —técnico o no— y quiere entender *qué hace*, *por qué está hecho así*
|
||||||
|
> y *cómo encajan las piezas* sin tener que leer todo el código primero.
|
||||||
|
>
|
||||||
|
> Si solo quieres arrancarlo, ve al [`README.md`](../README.md). Si quieres las
|
||||||
|
> decisiones técnicas en bruto, ve a [`ARCHITECTURE.md`](../ARCHITECTURE.md).
|
||||||
|
> Este documento está en medio: cuenta la historia.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. El problema, en una frase
|
||||||
|
|
||||||
|
> Poner agentes de 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 y ninguna auditoría de lo que decidió el agente.
|
||||||
|
|
||||||
|
**AgentForge es el "plano de control" que pones *delante* de tus agentes** antes de
|
||||||
|
dejarlos tocar nada importante. No es un framework para *construir* agentes; es la
|
||||||
|
capa que los **cataloga, versiona, valida, ejecuta de forma supervisada y audita**.
|
||||||
|
|
||||||
|
El caso de ejemplo que trae el repo es un agente de operaciones de telco
|
||||||
|
(`incident_analyzer`): recibe la descripción de un incidente de plataforma de voz
|
||||||
|
(caída de registros SIP, degradación de MOS, saturación de HSS...) y propone
|
||||||
|
acciones con análisis de riesgo y plan de rollback. Acciones de riesgo alto quedan
|
||||||
|
**pausadas esperando aprobación humana**. Todo queda registrado.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Las seis ideas grandes
|
||||||
|
|
||||||
|
Si entiendes estas seis ideas, entiendes el proyecto. Todo lo demás son detalles.
|
||||||
|
|
||||||
|
| # | Idea | Dónde vive |
|
||||||
|
|---|------|------------|
|
||||||
|
| 1 | **Agentes y políticas como ficheros declarativos, versionados como Git.** Un agente es un YAML (prompt, modelo, esquema de salida, umbral de aprobación). Cambias el YAML → nueva versión, con hash y diff. Sin redeploy. | `agents/`, `policies/`, `registry/` |
|
||||||
|
| 2 | **Los guardrails son una *política*, no código disperso.** Una política lista validadores de entrada y de salida con su configuración. El motor los aplica; "qué se valida" es configuración. | `policies/`, `guardrails/` |
|
||||||
|
| 3 | **La ejecución del agente es un grafo de estados con checkpoints.** No es "llama al LLM y ya"; es un flujo: validar entrada → razonar → validar salida → proponer acciones → puerta de aprobación → finalizar. Cada paso se persiste. | `runtime/` (LangGraph) |
|
||||||
|
| 4 | **Human-in-the-Loop (HITL) de verdad.** Si el agente propone algo arriesgado, el grafo **se pausa** en mitad de la ejecución, el estado se guarda en disco, y se reanuda más tarde —incluso tras reiniciar el proceso— cuando un humano aprueba o rechaza. | nodo `approve_gate` + endpoints `/approve`, `/reject` |
|
||||||
|
| 5 | **Trazabilidad obligatoria.** Cada petición lleva un `trace_id` (UUID) que se propaga por el middleware → los logs → la API → los ficheros de auditoría. Cada paso del grafo deja una entrada en el `decision_path` con su duración. | `observability/`, `domain/execution.py` |
|
||||||
|
| 6 | **Todo lo "intercambiable" está detrás de una interfaz + un factory.** El proveedor de LLM, el motor de guardrails, el registry... son `Protocol`s con varias implementaciones. Un factory elige cuál según la configuración. Cambias `.env`, no el código. | `llm/`, `guardrails/`, `registry/` (los `factory.py`) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Vista de pájaro: dos servicios
|
||||||
|
|
||||||
|
AgentForge son **dos procesos** que se hablan por HTTP/JSON:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌───────────────────────────── docker-compose ──────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────┐ HTTP/JSON ┌────────────────────────┐ │
|
||||||
|
│ │ agentforge-dashboard │ ───────────────► │ agentforge-core │ │
|
||||||
|
│ │ Streamlit :8501 │ ◄─────────────── │ FastAPI :8000 │ │
|
||||||
|
│ │ (la "consola") │ │ (el cerebro) │ │
|
||||||
|
│ └──────────────────────┘ └───────────┬────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌────────────────┬────────────────────┼───────────────┤
|
||||||
|
│ ▼ ▼ ▼ │
|
||||||
|
│ capa LLM capa Guardrails runtime LangGraph │
|
||||||
|
│ (Strategy+factory) (Strategy+factory) (grafo + checkpointer) │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ └────────────────┴──────────┬──────────┘ │
|
||||||
|
│ ▼ │
|
||||||
|
│ Persistencia: YAML · JSON · JSONL · SQLite │
|
||||||
|
└────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
- **`agentforge-core`** (FastAPI, puerto 8000) — todo el dominio: registry de
|
||||||
|
agentes, motor de guardrails, runtime de ejecución, persistencia. No tiene UI.
|
||||||
|
- **`agentforge-dashboard`** (Streamlit, puerto 8501) — una consola visual. **No
|
||||||
|
contiene lógica de negocio**: es un cliente HTTP del core con cinco páginas.
|
||||||
|
|
||||||
|
La separación importa: el core podría servir a una CLI, a otro servicio, a un
|
||||||
|
pipeline... el dashboard es solo una de las caras posibles.
|
||||||
|
|
||||||
|
### Las capas del core (de fuera hacia dentro)
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP ─► middlewares ─► routers (api/) ─► dependencias (deps.py)
|
||||||
|
│ │ ← aquí se inyectan los
|
||||||
|
│ │ objetos del dominio
|
||||||
|
▼ ▼
|
||||||
|
orchestrator ──► graph (LangGraph) ──► nodes
|
||||||
|
│ │
|
||||||
|
│ ├─► llm/ (¿qué dice el LLM?)
|
||||||
|
│ ├─► guardrails/ (¿pasa los filtros?)
|
||||||
|
│ └─► domain/ (¿qué forma tienen los datos?)
|
||||||
|
▼
|
||||||
|
checkpointer (SQLite) + persistence (JSONL) + registry (YAML/JSON)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Recorrido por los módulos (y quién depende de quién)
|
||||||
|
|
||||||
|
El código del core vive bajo `core/src/agentforge_core/`. Lo agrupo por capas, de
|
||||||
|
las más internas (sin dependencias) a las más externas.
|
||||||
|
|
||||||
|
### 4.1 `domain/` — el vocabulario del sistema
|
||||||
|
|
||||||
|
Modelos Pydantic puros. **No dependen de nada del proyecto**; todo lo demás depende
|
||||||
|
de ellos. Son el "idioma común".
|
||||||
|
|
||||||
|
| Fichero | Qué define |
|
||||||
|
|---------|------------|
|
||||||
|
| `agent.py` | `AgentDefinition` (prompt, modelo, `output_schema`, `guardrails`, `risk_threshold_for_hitl`, ...), `LLMConfig`, `AgentVersionMeta`. |
|
||||||
|
| `policy.py` | `PolicyDefinition` (listas de `PolicyValidator` de entrada y de salida, `on_validator_error`), `PolicyVersionMeta`. |
|
||||||
|
| `guardrail.py` | `GuardrailViolation` (trace_id, stage `input`/`output`, validator, severity, message, blocked). |
|
||||||
|
| `execution.py` | `AgentExecution` (el "expediente" de una ejecución: status, `decision_path`, `violations`, `proposed_actions`, `needs_human_for`, `final_output`, `error`), `ProposedAction`, `DecisionStep`, `AgentExecutionSummary`. |
|
||||||
|
|
||||||
|
> **Pista didáctica:** si quieres entender el sistema rápido, empieza leyendo
|
||||||
|
> `domain/execution.py`. Te dice exactamente qué información se produce y se guarda.
|
||||||
|
|
||||||
|
### 4.2 `config.py` y `observability/logging.py` — los cimientos transversales
|
||||||
|
|
||||||
|
- **`config.py` → `Settings`** (pydantic-settings): lee `.env` (proveedor LLM,
|
||||||
|
rutas de `agents/`/`policies/`/`data/`, nivel de log, claves de Azure/OpenAI,
|
||||||
|
flags de NeMo). Es el único sitio que sabe de variables de entorno. **Todos los
|
||||||
|
`factory.py` reciben un `Settings`.**
|
||||||
|
- **`observability/logging.py`**: configura `structlog` con salida JSON y un
|
||||||
|
contexto donde se "bind-ea" el `trace_id`. Lo usa todo el código que loguea
|
||||||
|
(`log = structlog.get_logger(__name__)`).
|
||||||
|
|
||||||
|
Dependen: de nada del proyecto. Dependen de ellos: prácticamente todo.
|
||||||
|
|
||||||
|
### 4.3 `llm/` — la capa de proveedores de LLM (Strategy pattern)
|
||||||
|
|
||||||
|
| Fichero | Rol |
|
||||||
|
|---------|-----|
|
||||||
|
| `base.py` | El `Protocol` `LLMProvider` (`async complete(messages, temperature, max_tokens) -> CompletionResult`) y los tipos `Message`, `CompletionResult`. **La interfaz.** |
|
||||||
|
| `mock.py` | `MockProvider`: determinista, sin claves. Elige una respuesta canónica buscando subcadenas (`"sip"`, `"mos"`, `"hss"`) en el input. Es lo que hace que el demo funcione out-of-the-box. |
|
||||||
|
| `azure.py`, `openai.py` | Implementaciones reales (Azure OpenAI / OpenAI) con reintentos exponenciales y, opcionalmente, *fallback* entre proveedores. |
|
||||||
|
| `factory.py` | `build_llm_provider(settings)`: devuelve el provider según `LLM_PROVIDER` (`mock` / `azure` / `openai`), y envuelve un *fallback* opcional. |
|
||||||
|
|
||||||
|
Depende de: `domain/`, `config.py`. Dependen de él: el `runtime/` (el nodo
|
||||||
|
`llm_reason`) y el `deps.py` de la API.
|
||||||
|
|
||||||
|
### 4.4 `registry/` — catálogo y versionado de agentes y políticas
|
||||||
|
|
||||||
|
| Fichero | Rol |
|
||||||
|
|---------|-----|
|
||||||
|
| `repository.py` | `FileSystemAgentRegistry`: lee `agents/<nombre>/index.yaml` + `versions/<id>.yaml`. CRUD de agentes y versiones, lectura de la versión "activa". |
|
||||||
|
| `policy_store.py` | `FileSystemPolicyStore`: lo mismo para `policies/`. Devuelve `PolicyDefinition`s. |
|
||||||
|
| `versioning.py` | `compute_hash(yaml_text)` (SHA-256 sobre el contenido normalizado) y el *diff unificado* entre dos versiones. Es la "magia tipo Git": versiones inmutables identificadas por hash, comparables. |
|
||||||
|
| `factory.py` | `build_registry(settings)` y `build_policy_store(settings)`. |
|
||||||
|
|
||||||
|
Depende de: `domain/`, `config.py`. Dependen de él: la API (`/agents`, `/policies`),
|
||||||
|
el `orchestrator` (para resolver qué agente/política ejecutó una traza dada).
|
||||||
|
|
||||||
|
### 4.5 `guardrails/` — el motor de validación
|
||||||
|
|
||||||
|
Aquí está el corazón del "gobierno". La estructura sigue otra vez **Protocol +
|
||||||
|
implementaciones + composite + factory**:
|
||||||
|
|
||||||
|
```
|
||||||
|
GuardrailEngine (Protocol) ← base.py: validate_input / validate_output
|
||||||
|
▲
|
||||||
|
┌────────────┼─────────────┐
|
||||||
|
│ │
|
||||||
|
GuardrailsAIEngine NeMoGuardrailsEngine ← guardrails_ai.py / nemo.py
|
||||||
|
(el real: aplica los (stub; desactivado
|
||||||
|
validadores de la por defecto)
|
||||||
|
política)
|
||||||
|
│
|
||||||
|
└──────────┐
|
||||||
|
▼
|
||||||
|
CompositeGuardrailEngine ← composite.py: corre N sub-engines
|
||||||
|
(corre los sub-engines en paralelo en paralelo (asyncio.gather) y
|
||||||
|
con asyncio y agrega las violaciones) une las listas de violaciones
|
||||||
|
|
||||||
|
factory.py: build_guardrail_engine(settings) → ensambla el Composite
|
||||||
|
validators.py: las funciones concretas — detect_pii, prompt_injection,
|
||||||
|
toxic_language, forbidden_topics, schema_match, pii_leakage,
|
||||||
|
forbidden_action_keywords, telco_safety_rules
|
||||||
|
```
|
||||||
|
|
||||||
|
**Cómo se conecta una política con un validador:** la política
|
||||||
|
(`policies/default/versions/v1.yaml`) lista, por ejemplo:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
input_validators:
|
||||||
|
- type: detect_pii
|
||||||
|
config: { entities: [EMAIL_ADDRESS, ES_NIF, IP_ADDRESS, IBAN_CODE], severity_on_match: block }
|
||||||
|
- type: prompt_injection
|
||||||
|
config: { severity_on_match: block }
|
||||||
|
...
|
||||||
|
on_validator_error: fail_closed
|
||||||
|
```
|
||||||
|
|
||||||
|
El `GuardrailsAIEngine` recorre esa lista, busca cada `type` en su registro de
|
||||||
|
funciones de `validators.py`, la llama con el texto y el `config`, y junta las
|
||||||
|
`GuardrailViolation` que devuelva. `on_validator_error: fail_closed` significa que
|
||||||
|
**si un validador peta, cuenta como bloqueo** (seguridad antes que disponibilidad).
|
||||||
|
|
||||||
|
> **Sobre `detect_pii`:** usa Presidio (con el modelo spaCy `en_core_web_sm`) si
|
||||||
|
> está instalado; si no, cae a una detección por regex (email, teléfono, NIF
|
||||||
|
> español, IP). Por eso el comportamiento en local (sin Presidio) y en Docker
|
||||||
|
> (con Presidio) puede diferir — la política solo pide *recognizers de patrón*
|
||||||
|
> fiables para evitar falsos positivos del NER.
|
||||||
|
|
||||||
|
Depende de: `domain/`, `config.py`. Dependen de él: el `runtime/` (los nodos
|
||||||
|
`validate_input`/`validate_output`) y el `deps.py`.
|
||||||
|
|
||||||
|
### 4.6 `runtime/` — la ejecución como grafo de estados (LangGraph)
|
||||||
|
|
||||||
|
Esta es la capa más "viva". Modela una ejecución del agente como un grafo dirigido.
|
||||||
|
|
||||||
|
| Fichero | Rol |
|
||||||
|
|---------|-----|
|
||||||
|
| `state.py` | `AgentState`: un `TypedDict` con todo lo que fluye por el grafo (input, salida del LLM, acciones propuestas, violaciones acumuladas, `decision_path`, status, decisión humana, ...). Algunos campos usan reducers (`Annotated[list, operator.add]`) para que cada nodo *añada* en vez de sobrescribir. |
|
||||||
|
| `nodes.py` | Las **funciones-nodo**, construidas por *factories* parametrizadas con el agente, la política, el motor de guardrails y el provider LLM: `validate_input`, `llm_reason`, `validate_output`, `propose_actions`, `approve_gate`, `finalize`. Cada nodo añade un `DecisionStep` con su duración. |
|
||||||
|
| `graph.py` | `build_graph(...)`: cablea los nodos y las **aristas condicionales** (p. ej. si `validate_input` bloqueó → salta directo al final). Compila el grafo con un `checkpointer`. |
|
||||||
|
| `checkpointer.py` | `build_checkpointer(data_dir)`: un `AsyncSqliteSaver` de LangGraph sobre `data_dir/checkpoints.sqlite`, expuesto como *context manager* asíncrono. Es lo que hace que un `awaiting_approval` **sobreviva a un reinicio**. |
|
||||||
|
| `orchestrator.py` | `AgentOrchestrator`: la **única puerta de entrada** al runtime. Tres operaciones: `invoke()` (lanza), `resume()` (reanuda un HITL con la decisión), `snapshot()` (lee el estado actual sin avanzarlo). Cada llamada abre su propio checkpointer y traduce el `StateSnapshot` de LangGraph a un `AgentExecution` del dominio. |
|
||||||
|
|
||||||
|
**El grafo, dibujado:**
|
||||||
|
|
||||||
|
```
|
||||||
|
START
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────┐ bloqueada (PII, injection...)
|
||||||
|
│ validate_input │ ─────────────────────────────────────────► END
|
||||||
|
└────────┬────────┘
|
||||||
|
│ ok
|
||||||
|
▼
|
||||||
|
┌─────────────────┐ LLM no disponible / error
|
||||||
|
│ llm_reason │ ─────────────────────────────────────────► END
|
||||||
|
└────────┬────────┘
|
||||||
|
│ ok
|
||||||
|
▼
|
||||||
|
┌─────────────────┐ salida no cumple el esquema / PII en la salida
|
||||||
|
│ validate_output │ ─────────────────────────────────────────► END
|
||||||
|
└────────┬────────┘
|
||||||
|
│ ok
|
||||||
|
▼
|
||||||
|
┌─────────────────┐
|
||||||
|
│ propose_actions │ (extrae las acciones propuestas del JSON del LLM)
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────┐ ¿hay alguna acción con risk_score ≥ umbral
|
||||||
|
│ approve_gate │ o requires_approval=True?
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
┌────┴───────────────────────────────┐
|
||||||
|
│ no │ sí
|
||||||
|
▼ ▼
|
||||||
|
┌──────────┐ interrupt({...}) ──► el grafo SE PAUSA aquí.
|
||||||
|
│ finalize │ El estado queda en checkpoints.sqlite.
|
||||||
|
└────┬─────┘ Más tarde llega resume(decision={...})
|
||||||
|
│ y se reanuda en este mismo punto.
|
||||||
|
▼ │
|
||||||
|
END ▼
|
||||||
|
┌──────────┐
|
||||||
|
│ finalize │ (filtra a las acciones aprobadas;
|
||||||
|
└────┬─────┘ si fue rechazo → status=failed)
|
||||||
|
▼
|
||||||
|
END
|
||||||
|
```
|
||||||
|
|
||||||
|
Depende de: `llm/`, `guardrails/`, `domain/`, `config.py` (vía los objetos que le
|
||||||
|
inyectan). Dependen de él: la API (`api/executions.py` solo conoce el
|
||||||
|
`AgentOrchestrator`, no LangGraph).
|
||||||
|
|
||||||
|
### 4.7 `api/` — la fachada HTTP (FastAPI)
|
||||||
|
|
||||||
|
| Fichero | Rol |
|
||||||
|
|---------|-----|
|
||||||
|
| `middlewares.py` | `TraceIdMiddleware`: lee `X-Trace-Id` de la petición (o genera uno), lo bind-ea al contexto de structlog, y lo devuelve en la respuesta. **Es el origen del hilo de trazabilidad.** |
|
||||||
|
| `deps.py` | Las **dependencias inyectables**. Cada `get_*` (`get_settings`, `get_registry`, `get_policy_store`, `get_llm_provider`, `get_guardrail_engine`, `get_orchestrator`) está cacheada con `lru_cache(maxsize=1)`: la app construye cada cosa **una sola vez**. Expone aliases (`RegistryDep = Annotated[..., Depends(get_registry)]`, etc.) que los routers piden por parámetro. Los tests llaman a `.cache_clear()` para reconstruir todo apuntando a un `DATA_DIR` temporal. |
|
||||||
|
| `persistence.py` | Helpers de **log append-only en JSONL**: `append_execution`, `append_violation`, `read_execution_summaries`. Inmutable, auditable, fácil de "shipear" a un sistema de logs. |
|
||||||
|
| `agents.py` | Router `/agents`: list, get, versiones, `GET /agents/{n}/versions/{a}/diff/{b}`. |
|
||||||
|
| `executions.py` | El más cargado: `POST /agents/{n}/invoke`, `GET /executions`, `GET /executions/{trace_id}`, `POST /executions/{trace_id}/approve`, `POST /executions/{trace_id}/reject`. Mantiene además `execution_index.json` (mapa `trace_id → agente/versión`) para poder reanudar tras un reinicio. |
|
||||||
|
| `policies.py`, `violations.py` | Routers `/policies` y `/violations` (este con filtros por severidad, stage, etc.). |
|
||||||
|
|
||||||
|
Y la **raíz de la app**: `core/src/agentforge_core/main.py` → `create_app()` instancia
|
||||||
|
`FastAPI`, añade el `TraceIdMiddleware`, monta los routers, y expone `/health`.
|
||||||
|
|
||||||
|
Depende de: todo lo de arriba (vía `deps.py`). Dependen de él: el dashboard (por
|
||||||
|
HTTP) y los tests de integración (`tests/integration/`, vía `TestClient`).
|
||||||
|
|
||||||
|
### 4.8 `dashboard/` — la consola Streamlit
|
||||||
|
|
||||||
|
| Fichero | Rol |
|
||||||
|
|---------|-----|
|
||||||
|
| `client.py` | `CoreClient`: un cliente HTTP síncrono (httpx, con reintentos) que envuelve **todos** los endpoints del core y mapea 404/409/422 a `{"error": ...}`. Es lo único que sabe hablar con el core. |
|
||||||
|
| `app.py` | La página raíz: sidebar de branding + un health-check del core. |
|
||||||
|
| `pages/1_🏛️_Registro.py` | Catálogo de agentes: detalle (prompt, esquema, LLM, guardrails), tabla de versiones, **diff coloreado v1↔v2**. |
|
||||||
|
| `pages/2_▶️_Ejecutar.py` | Lanza un agente: botones con los escenarios pregrabados, textarea, `invoke`, y render del status + output + violaciones + *timeline* del `decision_path`. Avisa si quedó en `awaiting_approval`. |
|
||||||
|
| `pages/3_🤝_Aprobaciones.py` | La cola de HITL: lista las ejecuciones `awaiting_approval`, muestra cada acción propuesta (risk_score coloreado, target, rollback_plan) con un checkbox, y aprueba el subconjunto elegido o rechaza con motivo. |
|
||||||
|
| `pages/4_📜_Historial.py` | Pestaña de ejecuciones (tabla + detalle por `trace_id`) y pestaña de violaciones (filtrable por severidad). |
|
||||||
|
| `pages/5_📐_Politicas.py` | Inventario de políticas: validadores de entrada/salida (cada uno expandible con su config) y versiones. |
|
||||||
|
| `components/` | Trozos reutilizables de UI: `diff_view` (pinta `+`/`-`/`@@`), `trace_view` (el timeline del `decision_path`), `violation_view` (badges de severidad). |
|
||||||
|
|
||||||
|
Depende de: el `agentforge-core` por HTTP (vía `AGENTFORGE_CORE_URL`). **Nadie del
|
||||||
|
core depende del dashboard.** No tiene tests unitarios (mal coste/beneficio para
|
||||||
|
Streamlit); su verificación es la checklist manual de [`docs/manual_qa.md`](manual_qa.md).
|
||||||
|
|
||||||
|
### 4.9 Lo que no es código: `agents/`, `policies/`, `data/`
|
||||||
|
|
||||||
|
- **`agents/incident_analyzer/`** — el agente de ejemplo: `index.yaml` (catálogo de
|
||||||
|
versiones), `versions/v1.yaml` y `v2.yaml`, y `examples/*.txt` (tres escenarios de
|
||||||
|
incidente de telco que el demo usa).
|
||||||
|
- **`policies/default/`** — la política de guardrails de ejemplo (`index.yaml` +
|
||||||
|
`versions/v1.yaml`).
|
||||||
|
- **`data/`** — estado *runtime* (gitignored): `checkpoints.sqlite`,
|
||||||
|
`executions.jsonl`, `violations.jsonl`, `execution_index.json`. Se crea sola.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. El patrón que se repite: `Protocol` + `factory` + `Settings`
|
||||||
|
|
||||||
|
Tres veces (LLM, guardrails, registry) verás la misma estructura:
|
||||||
|
|
||||||
|
```
|
||||||
|
base.py → un Protocol (la interfaz: "qué se puede hacer")
|
||||||
|
<impl_a>.py → una implementación (p. ej. mock)
|
||||||
|
<impl_b>.py → otra implementación (p. ej. azure)
|
||||||
|
factory.py → build_X(settings: Settings) -> X ← elige y monta
|
||||||
|
```
|
||||||
|
|
||||||
|
¿Por qué? Porque permite **cambiar el comportamiento sin tocar el código**: pones
|
||||||
|
`LLM_PROVIDER=azure` en `.env` y el factory te da el provider de Azure; pones
|
||||||
|
`mock` y tienes un demo determinista sin claves. Lo mismo con guardrails (puedes
|
||||||
|
añadir el engine de NeMo) y con el registry (hoy es de ficheros; mañana podría ser
|
||||||
|
de base de datos). Es el principio de **"configuración antes que código"**.
|
||||||
|
|
||||||
|
Y todo se enchufa **una sola vez** al arrancar, en `api/deps.py` (los `lru_cache`):
|
||||||
|
el registry, el policy store, el provider, el motor de guardrails y el orchestrator
|
||||||
|
son singletons del proceso. Los routers solo los *piden*; no saben construirlos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. El recorrido de UNA petición, de principio a fin
|
||||||
|
|
||||||
|
Esta es la sección que conviene leer despacio: aquí se ve cómo encaja todo. Sigamos
|
||||||
|
`POST /agents/incident_analyzer/invoke` con el escenario SIP (el que dispara HITL).
|
||||||
|
|
||||||
|
### Acto 1 — la petición entra y se ejecuta el grafo
|
||||||
|
|
||||||
|
```
|
||||||
|
Cliente (dashboard o curl)
|
||||||
|
│ POST /agents/incident_analyzer/invoke { "input": "<texto del incidente SIP>" }
|
||||||
|
▼
|
||||||
|
TraceIdMiddleware ............ genera trace_id = UUID, lo bind-ea al log
|
||||||
|
▼
|
||||||
|
router invoke_agent (api/executions.py)
|
||||||
|
│ pide por inyección: RegistryDep, PolicyStoreDep, OrchestratorDep, SettingsDep
|
||||||
|
│ registry.get_agent("incident_analyzer") → AgentDefinition (versión activa = v2)
|
||||||
|
│ policies.get_policy(agent.guardrails[0]) → PolicyDefinition ("default")
|
||||||
|
▼
|
||||||
|
orchestrator.invoke(agent_def, policy, user_input)
|
||||||
|
│ abre el checkpointer (AsyncSqliteSaver sobre data/checkpoints.sqlite)
|
||||||
|
│ build_graph(agent_def, policy, provider, engine, checkpointer)
|
||||||
|
│ graph.ainvoke(estado_inicial, config={thread_id: trace_id})
|
||||||
|
▼
|
||||||
|
┌──── el grafo ────────────────────────────────────────────────────────────┐
|
||||||
|
│ validate_input → engine.validate_input(texto, policy, trace_id) │
|
||||||
|
│ recorre los input_validators de la política en paralelo │
|
||||||
|
│ (detect_pii, prompt_injection, ...) → 0 violaciones │
|
||||||
|
│ añade DecisionStep("validate_input", ...) │
|
||||||
|
│ llm_reason → provider.complete([system_prompt, user_input], ...) │
|
||||||
|
│ (MockProvider ve "sip" → respuesta canónica SIP) │
|
||||||
|
│ añade DecisionStep("llm_reason", model, tokens, ...) │
|
||||||
|
│ validate_output → parsea el JSON del LLM; engine.validate_output(...) │
|
||||||
|
│ (schema_match, pii_leakage, forbidden_action_keywords, │
|
||||||
|
│ telco_safety_rules) → 0 violaciones │
|
||||||
|
│ propose_actions → extrae proposed_actions del JSON: [act-1 (risk 4, │
|
||||||
|
│ requires_approval), act-2 (risk 3)] │
|
||||||
|
│ approve_gate → ¿alguna acción con risk ≥ 4 (umbral del agente) o │
|
||||||
|
│ requires_approval? SÍ (act-1) → interrupt({...}) │
|
||||||
|
│ ⇒ el grafo SE DETIENE. El estado se escribe en SQLite. │
|
||||||
|
└──────────────────────────────────────────────────────────────────────────┘
|
||||||
|
▼
|
||||||
|
orchestrator._snapshot(...) → LangGraph reporta "hay un nodo pendiente"
|
||||||
|
⇒ status = "awaiting_approval"
|
||||||
|
⇒ needs_human_for = [act-1] (y devuelve un AgentExecution)
|
||||||
|
▼
|
||||||
|
router: status no es terminal → NO se escribe en executions.jsonl,
|
||||||
|
pero SÍ se registra en execution_index.json: { trace_id → (incident_analyzer, v2) }
|
||||||
|
▼
|
||||||
|
respuesta 200 { status: "awaiting_approval", trace_id, needs_human_for: [act-1], decision_path: [...], ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
En el dashboard, la página **Ejecutar** muestra el timeline y un aviso "ve a
|
||||||
|
Aprobaciones". La página **Aprobaciones** hace `GET /executions`, encuentra esta
|
||||||
|
ejecución (el endpoint reconstruye las `awaiting_approval` desde el índice + el
|
||||||
|
checkpointer) y muestra `act-1` con su risk_score, target y rollback_plan.
|
||||||
|
|
||||||
|
### Acto 2 — el humano decide; el grafo se reanuda
|
||||||
|
|
||||||
|
```
|
||||||
|
Humano (en la página Aprobaciones, o curl)
|
||||||
|
│ POST /executions/<trace_id>/approve { approved_action_ids: ["act-1"], comment: "ok rollback" }
|
||||||
|
▼
|
||||||
|
router approve_execution (api/executions.py)
|
||||||
|
│ _resolve(...) → lee execution_index.json → sabe que fue (incident_analyzer, v2)
|
||||||
|
│ reconstruye el AgentDefinition y la PolicyDefinition
|
||||||
|
│ _ensure_awaiting(...) → orchestrator.snapshot(...) confirma que sigue en awaiting_approval
|
||||||
|
▼
|
||||||
|
orchestrator.resume(agent_def, policy, trace_id, decision={approved_action_ids:["act-1"], rejected:false})
|
||||||
|
│ abre OTRA VEZ el checkpointer (mismo data_dir) — el estado pausado sigue ahí,
|
||||||
|
│ aunque hubiera habido un reinicio del proceso entremedias
|
||||||
|
│ graph.ainvoke(Command(resume=decision), config={thread_id: trace_id})
|
||||||
|
▼
|
||||||
|
┌──── el grafo continúa desde donde se quedó ──────────────────────────────┐
|
||||||
|
│ approve_gate → el interrupt() devuelve la `decision` del humano │
|
||||||
|
│ finalize → final_actions = acciones cuyo id está aprobado = [act-1] │
|
||||||
|
│ final_output = { ...salida del LLM..., approved_actions:[act-1] }│
|
||||||
|
│ status = "completed" │
|
||||||
|
└──────────────────────────────────────────────────────────────────────────┘
|
||||||
|
▼
|
||||||
|
router: status terminal → append_execution(...) escribe el AgentExecution en executions.jsonl
|
||||||
|
▼
|
||||||
|
respuesta 200 { status: "completed", final_output: { ..., approved_actions: [act-1] }, ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
(Si en vez de `approve` se llama a `reject`, el nodo `finalize` ve `rejected: true` →
|
||||||
|
`status = "failed"`, `error = "rejected_by_human"`. También terminal → al JSONL.)
|
||||||
|
|
||||||
|
### El mismo recorrido, como diagrama de secuencia
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant U as Cliente / Dashboard
|
||||||
|
participant MW as TraceIdMiddleware
|
||||||
|
participant API as router (api/executions.py)
|
||||||
|
participant ORCH as AgentOrchestrator
|
||||||
|
participant G as Grafo LangGraph
|
||||||
|
participant CP as checkpoints.sqlite
|
||||||
|
participant LOG as executions.jsonl / index.json
|
||||||
|
|
||||||
|
U->>MW: POST /agents/incident_analyzer/invoke {input}
|
||||||
|
MW->>API: + trace_id
|
||||||
|
API->>API: registry.get_agent · policies.get_policy
|
||||||
|
API->>ORCH: invoke(agent, policy, input)
|
||||||
|
ORCH->>G: ainvoke(estado, thread_id=trace_id)
|
||||||
|
G->>G: validate_input → llm_reason → validate_output → propose_actions
|
||||||
|
G->>G: approve_gate: hay riesgo alto → interrupt()
|
||||||
|
G->>CP: persiste estado pausado
|
||||||
|
ORCH-->>API: AgentExecution(status=awaiting_approval, needs_human_for=[act-1])
|
||||||
|
API->>LOG: index.json[trace_id] = (incident_analyzer, v2)
|
||||||
|
API-->>U: 200 {status: awaiting_approval, trace_id, ...}
|
||||||
|
|
||||||
|
Note over U,CP: ...más tarde (incluso tras reiniciar el core)...
|
||||||
|
|
||||||
|
U->>API: POST /executions/{trace_id}/approve {approved_action_ids:[act-1]}
|
||||||
|
API->>LOG: lee index.json → (incident_analyzer, v2)
|
||||||
|
API->>ORCH: resume(agent, policy, trace_id, decision)
|
||||||
|
ORCH->>CP: reabre checkpointer (estado pausado sigue ahí)
|
||||||
|
ORCH->>G: ainvoke(Command(resume=decision), thread_id=trace_id)
|
||||||
|
G->>G: approve_gate (recibe decisión) → finalize → status=completed
|
||||||
|
ORCH-->>API: AgentExecution(status=completed, final_output)
|
||||||
|
API->>LOG: append a executions.jsonl
|
||||||
|
API-->>U: 200 {status: completed, final_output, ...}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Persistencia: cuatro formas, cuatro razones
|
||||||
|
|
||||||
|
AgentForge no usa una sola base de datos; usa la herramienta adecuada para cada cosa.
|
||||||
|
|
||||||
|
| Qué | Cómo | Por qué así |
|
||||||
|
|-----|------|-------------|
|
||||||
|
| Definiciones de agentes y políticas | **YAML** por versión + `index.yaml` | Lo escribe un humano (legible, comentable) y lo cataloga la máquina. |
|
||||||
|
| Identidad de versiones / comparación | **hash SHA-256** del contenido + `difflib` | Versiones inmutables identificables y comparables — "tipo Git". |
|
||||||
|
| Mapa `trace_id → agente/versión` | **JSON** (`execution_index.json`) | Necesario para reanudar un HITL sabiendo qué configuración lo ejecutó; debe sobrevivir a reinicios. |
|
||||||
|
| Log de ejecuciones terminales y de violaciones | **JSONL append-only** | Inmutable, auditable, trivial de "shipear" a un sistema de logs. |
|
||||||
|
| Estado intermedio del grafo (incl. pausas HITL) | **SQLite** (`checkpoints.sqlite`, vía LangGraph) | Es lo que LangGraph espera; permite reanudar una ejecución pausada entre reinicios del proceso. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Glosario
|
||||||
|
|
||||||
|
| Término | Significado en este proyecto |
|
||||||
|
|---------|------------------------------|
|
||||||
|
| **Agente** | Una configuración declarativa (YAML): prompt de sistema, modelo LLM, esquema de salida, lista de políticas de guardrails, umbral de riesgo para HITL. No es código. |
|
||||||
|
| **Política (de guardrails)** | Un YAML con la lista de validadores de entrada y de salida y su configuración, más `on_validator_error` (`fail_closed`/`fail_open`). |
|
||||||
|
| **Validador / guardrail** | Una función que mira el texto de entrada o la salida del LLM y devuelve cero o más `GuardrailViolation`. Ej.: `detect_pii`, `prompt_injection`, `schema_match`, `telco_safety_rules`. |
|
||||||
|
| **Violación** | El resultado de un validador: `stage` (input/output), `validator`, `severity` (`info`/`warning`/`block`), `message`, `blocked`. |
|
||||||
|
| **Ejecución (`AgentExecution`)** | El "expediente" de una invocación: `trace_id`, status, `decision_path`, `violations`, `proposed_actions`, `needs_human_for`, `final_output`, `error`. |
|
||||||
|
| **`decision_path`** | La lista de pasos por los que pasó el grafo, cada uno con su `step`, `timestamp`, `duration_ms` y un `detail`. La "caja negra" de la ejecución. |
|
||||||
|
| **HITL (Human-in-the-Loop)** | El patrón de pausar la ejecución cuando hay una acción arriesgada y esperar a que un humano apruebe o rechace. Implementado con `interrupt()` de LangGraph. |
|
||||||
|
| **Checkpointer** | El componente de LangGraph que persiste el estado del grafo (aquí, en SQLite). Lo que hace posible reanudar un HITL tras un reinicio. |
|
||||||
|
| **`trace_id`** | UUID que identifica una petición/ejecución y se propaga por middleware → logs → API → ficheros de auditoría. |
|
||||||
|
| **Orchestrator** | La única clase que habla con LangGraph (`invoke`/`resume`/`snapshot`); aísla al resto del sistema del runtime. |
|
||||||
|
| **Factory** | Función `build_X(settings)` que monta la implementación de `X` adecuada según la configuración. |
|
||||||
|
| **Status de ejecución** | `running`, `awaiting_approval` (pausada en HITL), `blocked_by_guardrail` (la frenó un validador), `completed`, `failed`. |
|
||||||
|
| **Estados de un agente** | `draft`, `active`, `deprecated` (metadato en su YAML). |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Mapa del repositorio y por dónde empezar a leer
|
||||||
|
|
||||||
|
```
|
||||||
|
agentforge/
|
||||||
|
├── core/
|
||||||
|
│ ├── src/agentforge_core/
|
||||||
|
│ │ ├── domain/ ← los modelos de datos (empieza por execution.py)
|
||||||
|
│ │ ├── config.py · observability/ ← cimientos transversales
|
||||||
|
│ │ ├── llm/ ← proveedores LLM (Protocol + impls + factory)
|
||||||
|
│ │ ├── registry/ ← catálogo y versionado (YAML/JSON, hash, diff)
|
||||||
|
│ │ ├── guardrails/ ← motor de validación (Protocol + composite + validators)
|
||||||
|
│ │ ├── runtime/ ← el grafo LangGraph (state, nodes, graph, checkpointer, orchestrator)
|
||||||
|
│ │ ├── api/ ← FastAPI (middlewares, deps, routers, persistence)
|
||||||
|
│ │ └── main.py ← create_app(): ensambla la app
|
||||||
|
│ ├── Dockerfile · requirements.txt
|
||||||
|
├── dashboard/
|
||||||
|
│ ├── src/agentforge_dashboard/ ← Streamlit (client + app + pages + components)
|
||||||
|
│ ├── Dockerfile · requirements.txt
|
||||||
|
├── agents/incident_analyzer/ ← el agente de ejemplo (YAMLs + escenarios .txt)
|
||||||
|
├── policies/default/ ← la política de guardrails de ejemplo
|
||||||
|
├── data/ ← estado runtime (gitignored)
|
||||||
|
├── tests/ ← pytest: tests/unit/ y tests/integration/ (88 tests en total; el demo Streamlit no se testea con unit tests)
|
||||||
|
├── docs/ ← este documento, manual_qa.md, futuro.md, superpowers/
|
||||||
|
├── docker-compose.yml ← levanta core + dashboard
|
||||||
|
├── Makefile ← install / test / test-all / lint / smoke / up / down
|
||||||
|
├── README.md · ARCHITECTURE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ruta de lectura sugerida (1 hora):**
|
||||||
|
1. `domain/execution.py` y `domain/agent.py` — qué datos hay.
|
||||||
|
2. `policies/default/versions/v1.yaml` y `agents/incident_analyzer/versions/v2.yaml` — cómo se declara todo.
|
||||||
|
3. `runtime/nodes.py` y `runtime/graph.py` — el flujo de ejecución.
|
||||||
|
4. `api/executions.py` — cómo se expone (invoke / approve / reject).
|
||||||
|
5. `tests/integration/test_invoke_hitl.py` — el ciclo completo, en ~40 líneas.
|
||||||
|
6. Levanta `docker compose up` y haz clic por las cinco páginas del dashboard.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Lo que aún no hace (a propósito)
|
||||||
|
|
||||||
|
Es un MVP. La detección de PII más fina (modelos grandes, español), autenticación,
|
||||||
|
OpenTelemetry, multi-tenant, persistencia en Postgres, evaluadores LLM-as-judge,
|
||||||
|
una cola de aprobaciones con SLA... están en el roadmap: [`docs/futuro.md`](futuro.md).
|
||||||
|
El estado actual y cómo verificarlo: [`README.md`](../README.md) y [`docs/manual_qa.md`](manual_qa.md).
|
||||||
Reference in New Issue
Block a user