grahama1970/batch-quality

Skill de Qualidade de Lote

Evite chamadas desperdiçadas ao LLM validando a qualidade ANTES de executar operações em lote completas.

O Que Esta Skill Realmente Faz

Diferente de verificações simples de existência de arquivo, esta skill:

1. Executa realmente o LLM em N amostras usando scillm
2. Valida a estrutura da resposta JSON (excertos, source_quality, etc.)
3. Utiliza contratos SPARTA para consultas de validação no DuckDB
4. Integra-se com task-monitor para portões de qualidade obrigatórios

Início Rápido

cd .pi/skills/batch-quality

# Preflight: Testa 3 amostras através do LLM real
uv run python cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# Se o preflight passar, execute seu lote
# ...operação em lote...

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

Comandos

preflight

Testa N amostras através do LLM real antes de executar o lote completo.

uv run python cli.py preflight \
    --stage <nome-do-estágio> \
    --run-id <sparta-run-id> \
    --samples 3 \
    --prompt <arquivo-de-prompt-opcional>

O que ele realmente faz:

1. Carrega o contrato SPARTA para o estágio (se existir)
2. Verifica variáveis de ambiente (CHUTES_API_KEY, CHUTES_TEXT_MODEL)
3. Conecta ao DuckDB para a execução
4. Amostra N itens da fila de entrada
5. Executa cada amostra através do scillm (chamada real ao LLM)
6. Valida a estrutura da resposta JSON
7. Exige que 50%+ das amostras passem

Códigos de saída:

• 0: APROVADO - seguro prosseguir
• 1: REPROVADO - corrija os problemas primeiro

validate

Valida a saída do lote usando contratos SPARTA.

uv run python cli.py validate \
    --stage <nome-do-estágio> \
    --run-id <sparta-run-id> \
    --task-name <nome-do-task-monitor>

O que ele realmente faz:

1. Carrega o contrato SPARTA (ex.: 05_extract_knowledge.json)
2. Executa todas validation_queries do contrato contra DuckDB
3. Verifica cada resultado de consulta contra expected_min
4. Notifica o task-monitor sobre aprovação/reprovação

Exemplo 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

Verifica o status atual do preflight (saída JSON).

uv run python cli.py status

clear

Limpa o estado do preflight (requer novo preflight).

uv run python cli.py clear

Integração com Pipeline SPARTA

# 1. Registra tarefa com exigência de validação
uv run python .pi/skills/task-monitor/monitor.py register \
    --name "sparta-stage-05" \
    --require-validation

# 2. Executa preflight (REALMENTE testa o LLM)
uv run python .pi/skills/batch-quality/cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# 3. Executa lote (apenas se o preflight passou)
uv run python -m sparta.pipeline_duckdb.05_extract_knowledge \
    --run-id run-recovery-verify

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

Configuração

Variáveis de ambiente:

• SPARTA_ROOT: Caminho para o projeto SPARTA (padrão: ~/workspace/experiments/sparta)
• CHUTES_API_KEY: Chave de API para chamadas LLM
• CHUTES_API_BASE: URL base da API (padrão: https://llm.chutes.ai/v1)
• CHUTES_TEXT_MODEL: ID do modelo para extração de texto

Localização dos contratos: $SPARTA_ROOT/tools/pipeline_gates/fixtures/D3-FEV/contracts/

Dependências

• typer - Framework CLI
• duckdb - Consultas ao banco de dados
• scillm - Processamento em lote LLM (para teste real de amostras)

Portões de Qualidade Durante a Execução (NÃO NEGOCIÁVEIS)

Para operações em lote de longa duração (especialmente geração de QRA, extração, etc.), apenas o preflight é insuficiente. Você DEVE executar portões de qualidade durante a execução, não apenas antes.

O Loop Pausa-Avaliação-Diagnóstico-Ajuste-Retomada

Após cada N pontos de verificação do lote (ex.: a cada 5 lotes KNN / ~1000 QRAs):

1. PAUSE — SIGSTOP o processo de geração
2. SNAPSHOT — Copie o DuckDB para análise offline, SIGCONT imediatamente
3. SAMPLE — Amostragem aleatória estratificada (estratos alto/médio/baixo de fundamentação)
4. ASSESS — Verifique cada amostra: fundamentação de entidade, qualidade da resposta, raciocínio
5. DIAGNOSE — Análise de tendência: a fundamentação está diminuindo? Falhas de entidade aumentando?
6. TWEAK — Se degradando: ajuste prompt, limiares de filtro, pontuações de relacionamento
7. RESUME — Apenas se a qualidade atender aos limiares
8. STOP + NOTIFY — Se a qualidade estiver abaixo do piso, pare e notifique um humano

Isto não é opcional. Um lote que executa até 100k QRAs sem portões de qualidade produzirá lixo que leva mais tempo para limpar do que para regenerar corretamente.

Script de Portão de Qualidade QRA

# Vigia contínuo (executa junto com a geração de QRA)
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
    --run-id run-recovery-verify \
    --batch-interval 5 \
    --samples 10

# Avaliação única
python $SPARTA_ROOT/scripts/qra_quality_gate.py assess \
    --run-id run-recovery-verify \
    --samples 20

# Visualizar tendência entre pontos de verificação
python $SPARTA_ROOT/scripts/qra_quality_gate.py trend \
    --run-id run-recovery-verify

Limiares de Qualidade

Métrica	Alerta	Parar
Fundamentação Média	< 0.65	< 0.55
% de Falha de Entidade	> 5%	> 10%
Taxa de Falha de Amostra	> 15%	> 30%
Queda na Fundamentação (por checkpoint)	> 0.05	> 0.10

Por Que Isso Importa

A pontuação de fundamentação QRA caiu de 0.74 para 0.62 ao longo de horas sem intervenção porque o vigia estava passivo. Um portão de qualidade adequado teria captado a queda em 0.70 → 0.65 e a diagnosticado (KNN esgotando relacionamentos fáceis, deriva de prompt, etc.) em vez de deixá-la deslizar até 0.62.

Princípio Chave

Preflight é barato. Lotes com falha são caros.

Testar 3 amostras custa ~$0.01 e leva 30 segundos. Executar 1000 itens com um prompt quebrado custa ~$3 e leva horas.

Portões durante a execução são mais baratos que regenerar. Pausar por 10 segundos a cada 1000 QRAs para verificar a qualidade não custa nada. Executar 100k QRAs cegamente e descobrir que metade é inutilizável custa tudo.