El engine de NEO
Esta sección explica qué es el engine (el "motor") de NEO, para qué sirve y cómo usarlo. Es la pieza que hace posibles los Modelos 2 y 4 (ver Los 4 modelos de orquestación): ejecutar el trabajo de QA sin un asistente de IA abierto, desde una terminal o desde un pipeline de CI.
1. Qué es
El engine es un programa de línea de comandos, neo, que vive en el repositorio crowdar-engine-mvp. Su trabajo es ejecutar planes: un plan es un archivo YAML que dice qué skills ejecutar, en qué orden y cómo pasarse la información de una a otra.
La idea central es separar dos cosas:
| Pieza | Qué hace | Quién la provee |
|---|---|---|
| Skills | La inteligencia: leer una historia, armar un plan de pruebas, generar tests, repararlos | El repositorio neo-releases |
| Engine | La coreografía: qué skill se ejecuta, en qué orden, con qué datos, y qué pasa si algo falla | El repositorio crowdar-engine-mvp |
El modelo de IA (LLM) aparece solo adentro de cada paso. El orden de los pasos, las condiciones y los cortes los decide el código del engine, siempre de la misma forma. Por eso dos ejecuciones del mismo plan siguen el mismo camino.
2. Cuándo usar el engine y cuándo no
| Situación | Qué usar |
|---|---|
| Trabajo interactivo del día a día, exploración, pedidos puntuales | Modelo 1: pedíselo al asistente de IA. No hace falta el engine |
| Un flujo repetible que una persona sigue paso a paso | Modelo 3: un playbook. No hace falta el engine |
Un pipeline de CI que se ejecuta solo ante un evento fijo (un MR con label feature, un push, un horario) |
Modelo 4 con el engine: neo run <plan.yaml> |
| Un pedido en texto libre que hay que derivar al plan correcto sin intervención humana | Modelo 2 con el engine: neo run --input "<texto>" |
En resumen: si hay una persona conversando con el asistente, no hace falta el engine. Si no hay nadie (un pipeline, un script), el engine es el que ejecuta.
3. Las 4 garantías del engine
El engine se diseñó alrededor de cuatro reglas que no se negocian:
| Garantía | Qué significa en la práctica |
|---|---|
| Validación de schema | Cada skill declara qué devuelve (output_schema). El engine valida la salida y, si el paso tiene guard: true, corta el plan si no cumple |
| Auditoría | Cada ejecución, cada paso, su costo, sus tokens y cada dato que se escribió quedan registrados en una base SQLite (audit.db) |
| Idempotencia | Si un plan ya terminó bien con exactamente el mismo input, no se vuelve a ejecutar: devuelve el resultado anterior sin gastar créditos |
| Tracking de costo | Cada ejecución informa cuánto costó en dólares, sumando todos los llamados al modelo |
4. Agnóstico de proveedor de IA
El engine habla con los modelos a través de LiteLLM, una capa que unifica proveedores. La misma skill se ejecuta en Anthropic (Claude), OpenAI (GPT) u otros cambiando solo el nombre del modelo en el plan:
default_model: anthropic/claude-haiku-4-5-20251001 # o openai/gpt-5.4, etc.
Incluso se puede usar un modelo distinto en cada paso del plan (ver Anatomía de un plan).
5. Cómo está armado (vista general)
flowchart TD
A[Evento o pedido] --> B{¿Hay plan elegido?}
B -- Sí, M4 --> D[Orquestador]
B -- No, M2 --> C[Clasificador<br/>lippia-neo-classify-task]
C -- confianza >= 0.7 --> D
C -- confianza < 0.7 --> H[Escala a un humano]
D --> E[Paso 1: skill]
E --> F[Paso 2: skill]
F --> G[Paso N: skill]
G --> R[result.json + audit.db]
| Componente | Responsabilidad |
|---|---|
| Orquestador | Recorre los pasos del plan en orden, resuelve las referencias ${...}, aplica when, guard y stop_unless, y registra todo |
| Dispatcher (solo M2) | Le pide a una skill clasificadora que elija el plan, y escala a un humano si la confianza es baja |
| Contexto compartido | Donde cada paso deja su resultado para que los siguientes lo lean. Es append-only: nada se pisa |
| Herramientas | Lo que una skill puede usar mientras trabaja: archivos, terminal, navegador, Jira, Azure DevOps |
| Adapters | Resuelven la parte específica del framework (Playwright, Cypress, Lippia, Pytest) leyendo qa-stack.yaml |
6. Guías de esta sección
| Guía | Qué vas a aprender |
|---|---|
| Requisitos e instalación | Qué hace falta para ejecutar el engine en tu computadora, con Docker o en el CI |
| Cómo ejecutarlo | Los comandos (run, event, report, matrix), sus opciones, los códigos de salida y qué archivos deja |
| Modelos de orquestación en el engine | Cómo funcionan por dentro el Modelo 4 (declarativo) y el Modelo 2 (híbrido) |
| Anatomía de un plan | La referencia completa del archivo YAML: cada campo, las referencias ${...} y las herramientas |
| Patrones de composición | Los 7 patrones para combinar skills, con un ejemplo de cada uno y cuál usar en cada caso |
Para ejecutar el engine en un pipeline (GitLab, GitHub, Bitbucket), ver además Configurar el CI.