pagina unica

ARCHITECTURE.md

@@ -35,11 +35,24 @@ Forja es un **único servicio FastAPI** (:8000):
 
 | Capa | Tecnología | Por qué |
 |---|---|---|
-| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). |
-| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. |
+| Registries (agents/policies/datasets/models) | YAML por versión + index.yaml | Humano lo escribe; diff legible; hash SHA-256 normalizado. Base común en `registry/yaml_store.py`. |
 | Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. |
 | Logs de ejecuciones | JSONL append-only | Idem. |
 | Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). |
+| Training runs / evaluaciones / promociones | JSON por entidad bajo `data/` | Estado mutable consultable por id; los registros de promoción aprobada van además a JSONL append-only. |
+
+## Ciclo MLOps (training → evaluación → promoción)
+
+1. `POST /api/training/runs` envía un job al backend configurado
+   (`TRAINING_BACKEND=mock|azure_ml`) con dataset, modelo base y, opcionalmente,
+   el agente y su **versión candidata**.
+2. `POST /api/training/runs/{id}/evaluate` ejecuta los escenarios canónicos
+   (`agents/<name>/examples/*.txt`) contra la versión candidata por el runtime
+   gobernado completo; pasa si no hay violaciones bloqueantes ni fallos.
+3. `POST /api/promotions` crea la petición; exige run `succeeded`, evaluación
+   `passed` y que la evaluación cubra **exactamente** la versión a promocionar.
+4. Un operador aprueba/rechaza (UI `/promotions`); al aprobar, la versión pasa a
+   `active` en el registry y queda un registro de auditoría append-only.
 
 ## HITL — Patrón
 
@@ -57,7 +70,8 @@ nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo
 
 ## Errores
 
-- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego
+- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s; si `LLM_FALLBACK_PROVIDER`
+  está configurado, `FallbackLLMProvider` delega en el secundario; luego
   `status=failed`.
 - Validador: `fail_closed` por defecto.
 - Schema mismatch en LLM output: 1 retry, luego `failed`.