# 🔨 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, datasets, models, training runs, promotions).
- UI embebida de **una sola página** (HTMX + Tailwind + Jinja) que recorre el
  ciclo de vida completo en seis etapas: **Define → Run → Approve → Train →
  Promote → Audit**. Cada panel se refresca solo tras cada acción; las rutas
  antiguas (`/agents`, `/run`, ...) redirigen a su etapa.

```
┌───────────────────────────────────────────────────────────────┐
│                        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: el ciclo completo en 6 clicks

Todo ocurre en `http://localhost:8000`, de arriba abajo, sin escribir nada:

1. **▶ Run demo incident** (etapa 02) — lanza un incidente HSS pregrabado por el
   pipeline gobernado. La acción propuesta tiene risk 5 → la ejecución se pausa
   en el approval gate.
2. **Approve all** (etapa 03) — el grafo se reanuda desde su checkpoint y la
   ejecución completa (aparece en la etapa 06 — Audit).
3. **Submit training run** (etapa 04) — el formulario viene pre-rellenado con el
   dataset `incident_sft`, el modelo `gpt4o_lora_base` y la versión candidata
   `v3` (draft). Con `TRAINING_BACKEND=mock` termina al instante.
4. **Run evaluation** (etapa 04) — ejecuta los escenarios canónicos del agente
   (`agents/<name>/examples/`) sobre la candidata `v3`; pasa si no hay
   violaciones bloqueantes.
5. **Request promotion** (etapa 04) — crea la petición de gobernanza, que
   aparece en la etapa 05.
6. **Approve promotion** (etapa 05) — `v3` pasa a `active` en el registry;
   compruébalo en los chips de versión de la etapa 01.

## Capacidades implementadas

| Feature | Ubicación |
|---|---|
| Agent / Policy / Dataset / Model Registry | `core/src/forja_core/registry/` (base genérica `yaml_store.py`) |
| Versionado Git-like (YAML) | `agents/`, `policies/`, `datasets/`, `models/` |
| 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 (+fallback opcional) | `core/src/forja_core/llm/` |
| Training backends (mock / Azure ML) | `core/src/forja_core/training/` |
| Evaluación post-training (escenarios) | `core/src/forja_core/evaluation/` |
| Promoción gobernada draft → active | `core/src/forja_core/api/promotions.py` |
| 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).

### Azure ML training

Set `TRAINING_BACKEND=azure_ml` and fill `AZURE_ML_*` workspace settings. Forja submits an Azure ML **command job** via `azure-ai-ml` using `DefaultAzureCredential` (Azure CLI, managed identity, etc.). Replace the bundled script in `core/src/forja_core/training/_azure_job_bundle/` or override `AZURE_ML_COMMAND` for your fine-tuning pipeline. Without workspace config, the backend stays in **stub mode** for local development.

## 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)
├── datasets/             datasets para fine-tuning (YAML versionados)
├── models/               modelos base / destino de entrenamiento (YAML versionados)
├── data/                 runtime state (gitignored)
├── tests/
└── docs/                 (explicacion.md, componentes.md, futuro.md, ARCHITECTURE.md)
```

## Development

- Implementation guidelines: [`karpathy.md`](karpathy.md)
- UI copy and language: [`docs/product-voice.md`](docs/product-voice.md) (English only in the web app)

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