# 🛡️ 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). 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

```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).