grahama1970/batch-quality

Batch Quality Skill (Habilidad de Calidad por Lotes)

Previene llamadas desperdiciadas al LLM validando la calidad ANTES de ejecutar operaciones por lotes completas.

Lo Que Esta Habilidad Realmente Hace

A diferencia de simples verificaciones de existencia de archivos, esta habilidad:

1. Ejecuta realmente el LLM en N muestras usando scillm
2. Valida la estructura de la respuesta JSON (extractos, source_quality, etc.)
3. Utiliza contratos SPARTA para consultas de validación en DuckDB
4. Se integra con task-monitor para puertas de calidad forzadas

Inicio Rápido

cd .pi/skills/batch-quality

# Pre-vuelo: Probar 3 muestras con el LLM real
uv run python cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# Si el pre-vuelo pasa, ejecutar su lote
# ...operación por lotes...

# Validar: Verificar DuckDB contra el contrato
uv run python cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Comandos

preflight (pre-vuelo)

Prueba N muestras con el LLM real antes de ejecutar el lote completo.

uv run python cli.py preflight \
    --stage <nombre-de-etapa> \
    --run-id <id-de-ejecución-sparta> \
    --samples 3 \
    --prompt <archivo-de-prompt-opcional>

Lo que realmente hace:

1. Carga el contrato SPARTA para la etapa (si existe)
2. Verifica las variables de entorno (CHUTES_API_KEY, CHUTES_TEXT_MODEL)
3. Se conecta a DuckDB para la ejecución
4. Toma una muestra de N elementos de la cola de entrada
5. Ejecuta cada muestra a través de scillm (llamada real al LLM)
6. Valida la estructura de la respuesta JSON
7. Requiere que más del 50% de las muestras pasen

Códigos de salida:

• 0: APROBADO - seguro continuar
• 1: FALLIDO - corregir problemas primero

validate (validar)

Valida la salida del lote usando contratos SPARTA.

uv run python cli.py validate \
    --stage <nombre-de-etapa> \
    --run-id <id-de-ejecución-sparta> \
    --task-name <nombre-del-monitor-de-tarea>

Lo que realmente hace:

1. Carga el contrato SPARTA (ej., 05_extract_knowledge.json)
2. Ejecuta todas las validation_queries del contrato contra DuckDB
3. Verifica el resultado de cada consulta contra expected_min
4. Notifica a task-monitor si pasó o falló

Ejemplo de contrato (05_extract_knowledge.json):

{
  "validation_queries": [
    {"name": "url_knowledge_count", "query": "SELECT COUNT(*) FROM url_knowledge", "expected_min": 10},
    {"name": "urls_processed", "query": "SELECT COUNT(*) FROM url_extraction_log WHERE ok = true", "expected_min": 5}
  ]
}

status (estado)

Verifica el estado actual del pre-vuelo (salida JSON).

uv run python cli.py status

clear (limpiar)

Limpia el estado del pre-vuelo (requiere un nuevo pre-vuelo).

uv run python cli.py clear

Integración con el Pipeline SPARTA

# 1. Registrar tarea con requisito de validación
uv run python .pi/skills/task-monitor/monitor.py register \
    --name "sparta-stage-05" \
    --require-validation

# 2. Ejecutar pre-vuelo (PRUEBA realmente el LLM)
uv run python .pi/skills/batch-quality/cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# 3. Ejecutar lote (solo si el pre-vuelo pasó)
uv run python -m sparta.pipeline_duckdb.05_extract_knowledge \
    --run-id run-recovery-verify

# 4. Validar usando consultas del contrato
uv run python .pi/skills/batch-quality/cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Configuración

Variables de entorno:

• SPARTA_ROOT: Ruta al proyecto SPARTA (por defecto: ~/workspace/experiments/sparta)
• CHUTES_API_KEY: Clave API para llamadas al LLM
• CHUTES_API_BASE: URL base de la API (por defecto: https://llm.chutes.ai/v1)
• CHUTES_TEXT_MODEL: ID del modelo para extracción de texto

Ubicación del contrato: $SPARTA_ROOT/tools/pipeline_gates/fixtures/D3-FEV/contracts/

Dependencias

• typer - Framework CLI
• duckdb - Consultas a bases de datos
• scillm - Procesamiento por lotes del LLM (para pruebas reales de muestras)

Puertas de Calidad en Vuelo Obligatorias (NO NEGOCIABLES)

Para operaciones por lotes de larga duración (especialmente generación QRA, extracción, etc.), el pre-vuelo por sí solo es insuficiente. DEBE ejecutar puertas de calidad durante la ejecución, no solo antes.

El Bucle Pausa-Evalúa-Diagnostica-Ajusta-Reanuda

Después de cada N puntos de control del lote (ej., cada 5 lotes KNN / ~1000 QRAs):

1. PAUSA — SIGSTOP el proceso de generación
2. INSTANTÁNEA — Copia DuckDB para análisis sin conexión, SIGCONT inmediatamente
3. MUESTRA — Muestra aleatoria estratificada (estratos de anclaje alto/medio/bajo)
4. EVALÚA — Verifica cada muestra: anclaje de entidades, calidad de respuesta, razonamiento
5. DIAGNOSTICA — Análisis de tendencias: ¿Está disminuyendo el anclaje? ¿Aumentan las fallas de entidades?
6. AJUSTA — Si se degrada: ajusta prompt, umbrales de filtro, puntuaciones de relaciones
7. REANUDA — Solo si la calidad cumple los umbrales
8. DETENER + NOTIFICAR — Si la calidad está por debajo del mínimo, detener y notificar a un humano

Esto no es opcional. Un lote que se ejecuta hasta 100k QRAs sin puertas de calidad producirá basura que lleva más tiempo limpiar que regenerar correctamente.

Script de Puerta de Calidad QRA

# Vigilancia continua (se ejecuta junto con la generación QRA)
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
    --run-id run-recovery-verify \
    --batch-interval 5 \
    --samples 10

# Evaluación única
python $SPARTA_ROOT/scripts/qra_quality_gate.py assess \
    --run-id run-recovery-verify \
    --samples 20

# Ver tendencia a través de puntos de control
python $SPARTA_ROOT/scripts/qra_quality_gate.py trend \
    --run-id run-recovery-verify

Umbrales de Calidad

Métrica	Advertencia	Detener
Anclaje Promedio	< 0.65	< 0.55
% Fallo de Entidad	> 5%	> 10%
Tasa de Fallo de Muestra	> 15%	> 30%
Disminución de Anclaje (por punto de control)	> 0.05	> 0.10

Por Qué Esto Importa

La puntuación de anclaje QRA se desvió de 0.74 a 0.62 durante horas sin intervención porque el vigilante era pasivo. Una puerta de calidad adecuada habría detectado la disminución en 0.70 → 0.65 y la habría diagnosticado (KNN agotando relaciones fáciles, desviación del prompt, etc.) en lugar de dejarla caer a 0.62.

Principio Clave

El pre-vuelo es barato. Los lotes fallidos son caros.

Probar 3 muestras cuesta ~$0.01 y toma 30 segundos. Ejecutar 1000 elementos con un prompt roto cuesta ~$3 y toma horas.

Las puertas en vuelo son más baratas que regenerar. Pausar durante 10 segundos cada 1000 QRAs para verificar la calidad no cuesta nada. Ejecutar 100k QRAS a ciegas y descubrir que la mitad no sirve cuesta todo.