101 lines
4.1 KiB
Markdown
101 lines
4.1 KiB
Markdown
# 🔨 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`](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 (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`](.env.example).
|
|
|
|
## 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)
|
|
├── data/ runtime state (gitignored)
|
|
├── tests/
|
|
└── docs/ (explicacion.md, componentes.md, futuro.md, ARCHITECTURE.md)
|
|
```
|
|
|
|
## 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).
|