128 lines
6.0 KiB
Markdown
128 lines
6.0 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, 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).
|