# 🔨 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

```
┌───────────────────────── docker-compose ──────────────────────────┐
│                                                                    │
│  ┌─────────────────────┐     HTTP/JSON     ┌────────────────────┐ │
│  │ forja-dashboard     │ ────────────────► │ forja-core         │ │
│  │ Streamlit  :8501    │ ◄──────────────── │ FastAPI    :8000   │ │
│  └─────────────────────┘                   └────────────────────┘ │
│                                                                    │
│   Strategy pattern para LLMProvider, GuardrailEngine, Registry.   │
│   Persistencia: YAML (defs versionadas), JSONL (logs), SQLite     │
│   (checkpoints LangGraph + HITL).                                  │
└────────────────────────────────────────────────────────────────────┘
```

Detalles completos en [`ARCHITECTURE.md`](ARCHITECTURE.md). Además:
- [`docs/walkthrough.html`](docs/walkthrough.html) — **walkthrough HTML autocontenido**
  (de alto a bajo nivel, con diagramas). Ábrelo directamente en el navegador
  (`xdg-open docs/walkthrough.html`); no requiere servidor.
- [`docs/explicacion.md`](docs/explicacion.md) — 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).
- [`docs/componentes.md`](docs/componentes.md) — referencia de cableado a bajo nivel
  (grafo de dependencias de módulos, inyección de dependencias, firmas de los
  contratos entre capas, cadenas de llamada de cada endpoint).

## 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 / 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/` |
| Editores gráficos (nuevo) | dashboard páginas Forjar Agente / Política |
| API REST + dashboard | forja-core :8000 + forja-dashboard :8501 |

## Variables de entorno

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

## Roadmap

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

## Estructura del repositorio

```
forja/
├── core/                 servicio FastAPI (gobernanza + runtime)
├── dashboard/            Streamlit (UI + editores gráficos)
├── agents/               definiciones de agentes (YAML versionados)
├── policies/             políticas de guardrails (YAML versionados)
├── data/                 runtime state (gitignored)
├── tests/
└── docs/
```

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