# 🔨 Forja

**Forja de agentes IA** — plataforma de gobernanza genérica para agentes de cualquier tipo.
Catalogación y versionado (estilo Git) de definiciones, políticas y guardrails;
ejecución controlada con runtime stateful, Human-in-the-Loop y observabilidad completa.
Úsala como plano de control en cualquier proyecto que necesite agentes gobernados.

## Arquitectura

Forja es un **único servicio** (FastAPI en :8000) que expone:

- API REST completa bajo `/api` (agentes, políticas, ejecuciones, aprobaciones, violaciones).
- UI embebida moderna (HTMX + Tailwind + Jinja) en rutas amigables (`/agents`, `/run`, `/approvals`, `/history`, `/policies`).

```
┌───────────────────────────────────────────────────────────────┐
│                        forja-core :8000                        │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  UI HTMX (navegador humano)  │  API REST (/api/*)       │  │
│  └─────────────────────────────────────────────────────────┘  │
│   Strategy factories (LLM / Guardrails / Registry)             │
│   LangGraph runtime + SQLite checkpoints (HITL real)           │
│   Persistencia: YAML versionado + JSONL + SQLite               │
└───────────────────────────────────────────────────────────────┘
```

Documentación viva:
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — decisiones técnicas.
- [`docs/explicacion.md`](docs/explicacion.md) — explicación didáctica completa.
- [`docs/componentes.md`](docs/componentes.md) — referencia de cableado a bajo nivel.
- [`docs/futuro.md`](docs/futuro.md) — roadmap.

## Quickstart

```bash
cp .env.example .env
docker compose up
```

Abre [http://localhost:8000](http://localhost:8000).

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 / Policy Registry | `core/src/forja_core/registry/` |
| Versionado Git-like (YAML) | `agents/<name>/` + `policies/<name>/` |
| Guardrails runtime (strategy) | `core/src/forja_core/guardrails/` |
| LangGraph + HITL + checkpoints | `core/src/forja_core/runtime/` |
| Observabilidad (trace + structlog) | `core/src/forja_core/observability/` |
| LLM abstraction | `core/src/forja_core/llm/` |
| UI embebida (HTMX) | `core/src/forja_core/web/` (ruta raíz) |
| API REST completa | bajo `/api` en forja-core :8000 |

## Variables de entorno

Ver [`.env.example`](.env.example).

## Roadmap

Ver [`docs/futuro.md`](docs/futuro.md).

## Estructura del repositorio

```
forja/
├── core/                 servicio FastAPI único (API + UI HTMX embebida)
├── agents/               definiciones de agentes (YAML versionados)
├── policies/             políticas de guardrails (YAML versionados)
├── data/                 runtime state (gitignored)
├── tests/
└── docs/                 (explicacion.md, componentes.md, futuro.md, ARCHITECTURE.md)
```

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