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. Además:

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 — 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 — 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

cp .env.example .env
docker compose up

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

Registro → ver incident_analyzer y comparar v1 vs v2.
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.
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.

Roadmap

Ver 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

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