Modelos de orquestación en el engine
Los 4 modelos de orquestación explica, sin tecnicismos, quién decide el flujo y quién lo ejecuta en cada modelo. Esta guía baja ese concepto al engine: cómo funcionan por dentro los Modelos 4 y 2, que son los dos que ejecuta el engine.
1. Los 4 modelos de un vistazo
| Modelo | ¿Quién decide qué plan se ejecuta? | ¿Quién ejecuta los pasos? | ¿Usa el engine? |
|---|---|---|---|
| 1 — Improvisado | El asistente de IA | El asistente de IA | No |
| 2 — Híbrido adaptativo | Una skill clasificadora, entre planes ya escritos | El engine | Sí: neo run --input "<texto>" |
| 3 — Human-in-the-loop | Una persona, con un playbook | El asistente de IA, paso a paso | No |
| 4 — Declarativo puro | Una regla fija (por ejemplo, del CI) | El engine | Sí: neo run <plan.yaml> |
En los Modelos 2 y 4 el flujo nunca lo improvisa la IA. La diferencia entre los dos está solo en cómo se elige el plan: en el 4 lo elige una regla escrita de antemano; en el 2, una skill que lee el pedido.
2. Modelo 4 — Declarativo puro
2.1 Cómo funciona
flowchart LR
T[Evento fijo<br/>MR con label feature] --> CI[Regla del CI<br/>rules / if]
CI --> P[neo run plans/feature-new-end-to-end.yaml]
P --> S1[Paso 1] --> S2[Paso 2] --> SN[Paso N] --> R[Resultado]
- Pasa algo concreto en el repositorio: se abre un MR con el label
feature, se hace un push amain, llega la hora de una ejecución nocturna. - La regla del CI (el
rules:de GitLab o elif:de GitHub) decide qué plan corresponde. Esa decisión vive en el pipeline, no en el plan ni en el engine. - El engine recibe el plan ya elegido y lo ejecuta paso a paso, siempre igual.
2.2 Cuándo usarlo
- Pipelines de CI/CD que tienen que reaccionar solos ante un evento técnico.
- Cualquier caso donde el plan correcto se sabe de antemano y no hace falta "entender" un pedido.
2.3 Ejemplo
El plan feature-new-end-to-end ejecuta el playbook completo de una feature nueva (leer historia → plan de pruebas → exploración → suite → ejecutar y reparar → reporte) cada vez que un MR tiene el label feature:
# Regla del CI (GitLab), generada por lippia-neo-ci-bootstrap
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_LABELS =~ /feature/'
script:
- neo event --provider gitlab --out input.json
- neo run plans/feature-new-end-to-end.yaml --input-file input.json --workspace . --out result.json
Este es el modelo que usan hoy los templates de CI de NEO. Ver Configurar el CI.
3. Modelo 2 — Híbrido adaptativo
3.1 Cómo funciona
flowchart TD
I["Pedido en texto libre<br/>'retesteá el flujo de pago'"] --> R[Registro de planes<br/>--plans-dir + --overlay-dir]
R --> C[lippia-neo-classify-task<br/>devuelve plan + confianza]
C --> Q{¿confianza >= 0.7<br/>y el plan existe?}
Q -- No --> H1[Escala a un humano<br/>código 2]
Q -- Sí --> B[lippia-neo-build-plan-input<br/>arma el input del plan]
B --> K{¿Están todas las<br/>required_keys?}
K -- No --> H2[Escala a un humano<br/>código 2]
K -- Sí --> O[El engine ejecuta el plan<br/>igual que en el Modelo 4]
- Arma el pool de planes. Lee todos los
*.yamlde--plans-dir. Si se indica--overlay-dir, los planes de esa carpeta reemplazan a los de la base que tengan el mismoname. Los YAML inválidos se saltean con un aviso. - Clasifica. Le pasa a la skill
lippia-neo-classify-taskel pedido y, de cada plan, sunamey sudescription. La skill devuelve qué plan elige, qué tan segura está (de 0 a 1) y por qué. - Aplica la regla de negocio. Si la confianza es menor al umbral (0,7 por defecto, configurable con
--threshold) o el plan elegido no existe, escala a un humano y no ejecuta nada. El umbral vive en el engine, no en la skill: la skill solo informa qué tan segura está. - Arma el input. Le pasa a la skill
lippia-neo-build-plan-inputel pedido y la lista derequired_keysdel plan elegido. La skill extrae del texto los datos que necesita el plan. Si falta alguno, escala a un humano. - Ejecuta. A partir de acá, el plan se ejecuta exactamente igual que en el Modelo 4.
3.2 Cuándo usarlo
- Cuando el disparador es ambiguo y necesita criterio para saber qué plan corresponde: un comentario en un MR, un mensaje en un canal, un ticket.
- Cuando hay varios planes posibles y no conviene escribir una regla de CI para cada combinación.
3.3 Ejemplo
neo run --input "el bug PROJ-123 ya está en QA, armá la cobertura" \
--plans-dir plans --workspace .
pool: 4 plans considered (0 from overlay)
dispatched to qa-bug-coverage (confidence 0.91) -> run qa-bug-coverage-7c1e9a40: success (cost $0.6120)
Si el pedido fuera vago ("fijate si anda"), la salida sería:
escalated to human: plan=feature-new-end-to-end confidence=0.42 (reason: ...)
3.4 Cómo escribir planes que el clasificador elija bien
El clasificador decide solo con el name y la description de cada plan. Para que elija bien:
| Hacé | Evitá |
|---|---|
Una description que diga qué hace el plan y cuándo corresponde ("se dispara cuando un bug pasa a QA o una rama fix/*...") |
Descripciones genéricas ("plan de QA") |
| Planes con propósitos claramente distintos | Dos planes casi iguales: el clasificador va a dudar entre los dos y va a escalar |
required_keys con descripción (ver Anatomía de un plan) |
Claves sin descripción: la skill que arma el input no sabe qué buscar en el texto |
3.5 Planes base y overlay
El overlay sirve para que un proyecto reemplace un plan genérico por su propia versión sin tocar la carpeta base:
plans/ ← base (por ejemplo, la de la organización)
├── feature-new-end-to-end.yaml
└── qa-bug-coverage.yaml
plans-proyecto/ ← overlay (del proyecto)
└── qa-bug-coverage.yaml ← mismo name: reemplaza al de la base
neo run --input "..." --plans-dir plans --overlay-dir plans-proyecto
El reemplazo es total: se usa el plan del overlay entero, no se mezclan pasos.
4. Comparación entre M2 y M4
| Modelo 4 | Modelo 2 | |
|---|---|---|
| Comando | neo run <plan.yaml> |
neo run --input "<texto>" |
| Quién elige el plan | Una regla del CI | La skill lippia-neo-classify-task |
| Input del plan | Un JSON (--input-file, --data o neo event) |
Lo extrae lippia-neo-build-plan-input del texto |
| Costo extra | Ninguno | Dos llamadas al modelo antes de ejecutar el plan |
| Si no está claro qué hacer | No aplica: el plan ya está elegido | Escala a un humano (código de salida 2) |
| Reproducibilidad | Total | Total una vez elegido el plan; la elección puede variar entre pedidos parecidos |