Saltar a contenido

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]
  1. Pasa algo concreto en el repositorio: se abre un MR con el label feature, se hace un push a main, llega la hora de una ejecución nocturna.
  2. La regla del CI (el rules: de GitLab o el if: de GitHub) decide qué plan corresponde. Esa decisión vive en el pipeline, no en el plan ni en el engine.
  3. 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]
  1. Arma el pool de planes. Lee todos los *.yaml de --plans-dir. Si se indica --overlay-dir, los planes de esa carpeta reemplazan a los de la base que tengan el mismo name. Los YAML inválidos se saltean con un aviso.
  2. Clasifica. Le pasa a la skill lippia-neo-classify-task el pedido y, de cada plan, su name y su description. La skill devuelve qué plan elige, qué tan segura está (de 0 a 1) y por qué.
  3. 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á.
  4. Arma el input. Le pasa a la skill lippia-neo-build-plan-input el pedido y la lista de required_keys del plan elegido. La skill extrae del texto los datos que necesita el plan. Si falta alguno, escala a un humano.
  5. 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