Protocolo de avaliação experimental¶

Unidade de avaliação¶

Cada execução da cadeia:

pergunta -> tools MCP -> SQL(s) (até 5) -> validação -> execução -> registro

1 pergunta = 1 sessão = 1 corrida. Resposta agregada na trilha e no gabarito.

Orçamento de tool calls¶

• Limite máximo fixado: 10 chamadas por sessão (equivalente a 10 por pergunta).
• O consumo efetivo é registrado em metrics.json (toolCalls) e na trilha session.jsonl.
• Exceder o limite classifica a corrida como budget_exceeded.
• O catálogo MCP expõe quinze tools de descoberta (ver Contratos MCP v1). A avaliação MVP prioriza as três basais (catalog.listTables, catalog.describeTable, catalog.listRelationships); as doze complementares ficam disponíveis sob o mesmo orçamento.

Configuração LLM (pré-requisito de cada corrida)¶

Antes das etapas do protocolo, fixar configuração conforme Inferência e prompts:

Checklist por corrida (modo MCP)¶

• Receber pergunta e inicializar runId.
• Consultar metadados via tools MCP (máximo 10 chamadas).
• Gerar até cinco SQLs candidatos por pergunta.
• Validar sintaxe (Calcite/Hive) de cada statement.
• Validar aderência estrutural contra catálogo canônico.
• Executar SQLs aprovados no cluster controlado.
• Registrar trilha (session.jsonl), métricas (metrics.json) e contexto (context.json).

Etapas do protocolo¶

1. Receber pergunta e inicializar runId.
2. Consultar metadados via tools MCP sob orçamento fixado (máximo de 10 chamadas).
3. Gerar até cinco SQLs candidatos por pergunta.
4. Executar validação sintática (parse Calcite, dialeto Hive) de cada statement.
5. Executar validação estrutural contra catálogo canônico (Atlas governa o subconjunto PS, 92 tabelas).
6. Executar SQLs no banco de testes (subconjunto fixo do PS).
7. Classificar desfecho agregado, registrar trilha completa e gravar metrics.json.

Métricas essenciais (modo MCP)¶

Métricas essenciais (modo baseline)¶

Taxonomia MCP (success, partial_success, erros estruturais, rastreabilidade Atlas, orçamento) não se aplica ao baseline. Latência, tokens e FinOps não são métricas do modo baseline.

Protocolo do comparativo simples (baseline-static)¶

1. Auditar executabilidade das colas \(G_i\) (§ Auditoria em Gabarito da bateria).
2. Anexar Schema massa de teste ao prompt (injecção estática; 0 tool calls).
3. Submeter cada pergunta de Bateria de 30 perguntas com modelVersion gemini-3.5-flash (campanha v1, um único provedor).
4. Comparar resposta agregada final com \(G_i\) em Gabarito da bateria.
5. Registrar métricas em Métricas baseline v1 (30 corridas).

Detalhes operacionais: Runbook de reprodutibilidade (seção baseline-static).

Infraestrutura (separada)¶

• \(C_{\mathrm{infra}}\): estimativa de custo cluster AWS no período da campanha.
• Não entra em \(C_i\) nem em comparativos FinOps.

Classificação de desfecho (6 classes, modo MCP)¶

Ordem de precedência:

1. budget_exceeded — \(k_i > 10\)
2. syntax_error
3. structural_error
4. execution_error — falha Hive ou nenhum SQL bate gabarito
5. partial_success — parte dos SQLs bate gabarito
6. success — todos os SQLs exigidos batem gabarito

Tarifas FinOps (referência)¶

Fontes: documentação Spring AI para integração OpenAI e Google (Gemini).

Ameaças à validade¶

• sobreajuste de prompt à massa fixa do PS;
• variação temporal de comportamento da API de LLM;
• simplificações do laboratório AWS frente a cenário corporativo real;
• viés de domínio do PS (domínios comerciais e operacionais) frente a outros domínios.

Evidência mínima por corrida¶

• runId, campaignId (mcp ou baseline-static)
• pergunta original
• chamadas de tool e payloads resumidos (MCP)
• snapshot de metadados usados (MCP)
• lista de SQLs (até 5) e desfechos por statement (MCP)
• resultado de parse e execução
• metrics.json conforme Métricas e fórmulas
• context.json conforme Schema context.json v1
• seed, modelVersion, promptVersion, commitHash