Especificaciones
L · Orquestación de IA
Épica L — Orquestación de IA
Estado: Borrador · Última actualización: 2026-08-24 · Índice: README
Cubre la mecánica común de todas las operaciones de IA: ejecución asíncrona como jobs, selección de modelo por tarea, degradación graceful si el proveedor no responde, caché por contenido y aviso de costo previo obligatorio. Es un bloque transversal: no deriva de un caso de uso de actor, sino que sirve a toda operación que invoque IA (análisis, generación de casos, generación del plan). Reglas de negocio del bloque: RN-064 a RN-068.
HU-026 — Orquestar las operaciones de IA
Épica: L · Orquestación de IA · Deriva de: Transversal · Cubre: RF-125, RF-128–RF-130 · Reglas: RN-064, RN-065, RN-066, RN-067, RN-068 · Decisiones: DEC-017, DEC-018, DEC-056 · Estado: Borrador
Historia
Como plataforma, quiero orquestar cada operación de IA como un job asíncrono, con el modelo adecuado, degradación si el proveedor falla, caché y aviso de costo previo, para que la IA acelere el trabajo sin volverse condición para avanzar ni una fuente de gasto sin control.
Objetivo / valor. Que las operaciones de IA sean gobernables: se disparan siempre por acción explícita del usuario, corren fuera de la interacción síncrona, eligen el modelo más económico que resuelve la tarea, no bloquean la plataforma si el proveedor cae y avisan del costo antes de gastar.
Alcance
- Dentro: la ejecución asíncrona como jobs, el model routing por tarea configurable, la
degradación graceful sin IA, la caché por hash de contenido/prompt/versión, el aviso de costo previo a operaciones grandes y la validación estructurada de la respuesta.
- Fuera: qué produce cada operación concreta (análisis de requerimiento, generación de
casos, generación del plan viven en sus HU: HU-007, HU-008, HU-012), el registro de cada invocación como job —RF-124, cubierto en HU-007— y el contrato fino del proveedor (documentado, no diseñado; PA-011).
Actores y permisos (comportamiento del sistema)
- Toda operación de IA la dispara un usuario con una acción explícita; **nada se dispara
de forma automática** (RN-064).
- El sistema ejecuta el job, aplica el routing, gestiona la degradación y la caché: eso es
comportamiento del sistema, no una acción de rol.
- El aviso de costo previo requiere confirmación del usuario que dispara la operación
antes de procesar (DEC-056).
Precondiciones
- El usuario ejecuta una acción que invoca IA sobre un artefacto de un proyecto donde tiene
rol habilitado para esa acción.
- El proveedor de IA está configurado (región y modelos; PA-011). Su indisponibilidad activa
la degradación, no un bloqueo.
Comportamiento funcional
- Principal. Ante una acción de usuario que invoca IA, el sistema encola un **job
asíncrono, selecciona el modelo según la complejidad de la tarea (el más económico capaz de resolverla), envía el contexto directo al modelo —sin RAG ni recuperación vectorial (DEC-018)— y solicita salida estructurada. Al recibir la respuesta la valida contra la estructura esperada**; si valida, alimenta el artefacto; el usuario sigue trabajando mientras el job corre.
- Alternativo A1 — aviso de costo. Antes de procesar un documento extenso, el sistema
muestra una estimación de costo y exige confirmación; sin confirmación no procesa (RF-130, DEC-056).
- Alternativo A2 — caché. Si ya existe un resultado para el mismo hash de contenido, prompt
y versión, el sistema lo reutiliza y no reprocesa (RF-129).
- Error E1 — proveedor no disponible. La plataforma no se detiene: todas las funciones
de creación y edición manual siguen operando; la operación de IA queda no realizada y visible como tal (RF-128, RN-065, DEC-027).
- Error E2 — respuesta que no valida. La respuesta se descarta íntegra y se informa; no
se persiste parcialmente. Los reintentos son acotados y visibles, sin reintento automático ilimitado (RN-068).
Datos y campos (funcional, no esquema)
- Del job: tarea, modelo seleccionado, estado del job (encolado, en proceso, completado,
fallido), estimación de costo previa, resultado (validado / descartado).
- Del routing: mapa tarea → modelo, mantenido como configuración, no como código
- De la caché: hash de entrada (contenido + prompt + versión) y resultado asociado.
- Del aviso de costo: estimación mostrada y confirmación del usuario.
Reglas de negocio aplicables
- RN-064 — ninguna operación de IA es automática; siempre media una acción explícita del
usuario.
creación y edición manual siguen operando.
- RN-066 — toda invocación se registra como job con tarea, modelo, tokens, duración,
costo estimado, usuario y proyecto (el registro en sí se especifica en HU-007, RF-124).
- RN-067 — se usa el modelo más económico capaz de resolver la tarea; el mapa
tarea → modelo es configuración, no código.
- RN-068 — una respuesta que no valida se descarta íntegra y se informa; los reintentos
son acotados y visibles.
Estados y transiciones. No aplica una máquina de estados de dominio; el ciclo relevante es el interno del job: Encolado → En proceso → Completado, con Fallido ante error del proveedor o respuesta inválida.
Integraciones (documentado, el dev implementa)
- Proveedor de IA (Bedrock) — recibe el contexto directo y devuelve la respuesta
estructurada. Qué se toca: invocación del modelo seleccionado por el routing. La capa de IA debe especificarse tras una interfaz de proveedor para no quedar amarrada a Bedrock si su habilitación se demora (PA-011); región, modelos disponibles (Nova, Claude) y una eventual restricción de residencia de datos se cierran con PA-011. Sin RAG ni pgvector en el MVP: el contexto va directo al modelo (DEC-018).
Eventos que emite. Ninguno propio de esta HU. Los eventos de dominio que acompañan a una operación de IA (por ejemplo use_case.generated en HU-008) los emite la HU dueña del hito.
Criterios de aceptación
- CA-360
> Dado una acción de usuario que invoca IA > Cuando el sistema la procesa > Entonces la operación corre como un job asíncrono y el usuario puede seguir trabajando mientras el job se ejecuta.
- CA-361
> Dado una tarea de IA de complejidad conocida > Cuando el sistema selecciona el modelo > Entonces usa el más económico capaz de resolverla, según un mapa tarea → modelo configurable sin desplegar código.
- CA-362
> Dado que el proveedor de IA no está disponible > Cuando el usuario intenta crear o editar un artefacto a mano > Entonces la creación y edición manual siguen operando y la plataforma no se detiene.
- CA-363
> Dado una respuesta de IA que no valida contra la estructura esperada > Cuando el sistema la recibe > Entonces la descarta íntegra, lo informa y no persiste nada parcialmente.
- CA-364
> Dado una operación de IA que ya fue reintentada el número acotado de veces > Cuando vuelve a fallar > Entonces el sistema deja de reintentar automáticamente y muestra el fallo al usuario.
- CA-365
> Dado una operación de IA sobre un documento extenso > Cuando el usuario la dispara > Entonces el sistema muestra una estimación de costo y exige confirmación antes de procesar; sin confirmación no procesa.
- CA-366
> Dado una entrada cuyo hash de contenido, prompt y versión ya tiene resultado en caché > Cuando se solicita la misma operación > Entonces el sistema reutiliza el resultado cacheado y no reprocesa.
- CA-367
> Dado cualquier operación de IA > Cuando se dispara > Entonces media siempre una acción explícita del usuario; ninguna operación de IA se inicia de forma automática.
Dependencias y bloqueos
- PA-011 (región y modelos de Bedrock) — condiciona el model routing completo, la
latencia y una posible restricción de residencia de datos; la capa de IA se especifica tras una interfaz de proveedor para no amarrarse a Bedrock.
- PA-010 (techo de gasto mensual) — mientras no se fije, el aviso de costo previo es la
única contención de gasto; el umbral de "documento extenso" se define junto con ese techo (DEC-056).
- HU-007 (analizar requerimiento con IA) especifica el registro de cada invocación como
job (RF-124); esta HU define la mecánica común que HU-007, HU-008 y HU-012 invocan.
Casos borde / notas. "Descartar íntegra" es literal: una respuesta parcialmente válida no se guarda a medias ni se completa a mano desde el fragmento; se descarta y el usuario reintenta o crea el artefacto manualmente. El aviso de costo es Must, no Should: mientras PA-010 no fije el techo de gasto, avisar antes de gastar es la única contención (DEC-056).