Saltar a contenido

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.