forja/README.md

🔨 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 — 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 (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.

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)
├── data/                 runtime state (gitignored)
├── tests/
└── docs/                 (explicacion.md, componentes.md, futuro.md, ARCHITECTURE.md)

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