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 — decisiones técnicas.
docs/explicacion.md — explicación didáctica completa.
docs/componentes.md — referencia de cableado a bajo nivel.
docs/futuro.md — roadmap.

Quickstart

cp .env.example .env
docker compose up

Abre 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:

▶ 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.
Approve all (etapa 03) — el grafo se reanuda desde su checkpoint y la ejecución completa (aparece en la etapa 06 — Audit).
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.
Run evaluation (etapa 04) — ejecuta los escenarios canónicos del agente (agents/<name>/examples/) sobre la candidata v3; pasa si no hay violaciones bloqueantes.
Request promotion (etapa 04) — crea la petición de gobernanza, que aparece en la etapa 05.
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.

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.

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
UI copy and language: docs/product-voice.md (English only in the web app)

Tests

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