104 lines
4.4 KiB
Markdown
104 lines
4.4 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
|
|
|
|
```
|
|
┌───────────────────────── 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`](ARCHITECTURE.md). Además:
|
|
- [`docs/walkthrough.html`](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`](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`](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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up
|
|
```
|
|
|
|
Abre [http://localhost:8501](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)
|
|
|
|
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/` |
|
|
| 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`](.env.example).
|
|
|
|
## Roadmap
|
|
|
|
Ver [`docs/futuro.md`](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
|
|
|
|
```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).
|