decision-models-benchmark/docs/02-desenho-experimental.md

02 — Desenho experimental

Escopo do primeiro ciclo. O ciclo avalia a classificação de intenções (D1) no domínio de atendimento de telefonia móvel, com a taxonomia data/taxonomy/intents-v1.yaml (42 intenções em 13 domínios). Pedidos fora de escopo, enunciados emocionais e casos com várias intenções entram como exemplos de D1, com rótulo sem_correspondencia ou a intenção principal. D2 a D5 ficam descritas abaixo para os próximos ciclos, quando houver agentes implementados. Os dados são 100% sintéticos e a anotação é feita por três modelos generativos (ver §4).

1. Hipóteses

• H1 (acurácia). Pelo menos um candidato atinge, em PT-BR, uma acurácia de roteamento (D1/D2) compatível com o uso no orquestrador. O critério é a não inferioridade em relação ao baseline LLM (margem de 3 p.p.); ver 04, Q5.
• H2 (calibração). As probabilidades e a confiança devolvidas permitem uma política de abstenção (encaminhar para desambiguação) que melhora a acurácia seletiva sem derrubar demais a cobertura.
• H3 (desempenho). O candidato cabe no orçamento de latência por turno (p95 com lote 1) com um custo por mil decisões menor que o de uma chamada a um LLM generalista.

2. Tarefas de decisão

Cada tarefa tem pergunta, opções com descrição e regra de decisão (tarefa 21). No primeiro ciclo, cada questão tem no máximo 16 opções, incluindo sem_correspondencia (tarefas 22–23; ver Q2).

D1 — Classificação de intenção

• Pergunta: "Qual intenção do usuário este enunciado expressa?"
• Opções: as intenções elegíveis do exemplo, de 1 a 15, mais sem_correspondencia. Cada opção tem uma descrição curta, do mesmo jeito que viria do catálogo de agentes ou intenções.
• Regra: escolher a intenção principal que o próximo agente precisa atender. Se nenhuma se aplica, escolher sem_correspondencia.

D2 — Continuidade de sessão

• Pergunta: "Como o orquestrador deve tratar este turno, considerando o estado da conversa?"
• Opções: continuar_agente_ativo, retomar_sessao:<agent_id> (uma opção para cada sessão suspensa), iniciar_novo_agente, desambiguar.
• Regra: continuar_agente_ativo quando o enunciado dá sequência à tarefa em curso, mesmo que seja curto ("sim", "o segundo", "pode ser"). retomar_sessao quando o usuário volta a um assunto anterior. iniciar_novo_agente quando aparece uma intenção nova. desambiguar quando não dá para decidir com segurança.

D3 — Necessidade de desambiguação

• Pergunta: "O enunciado tem informação suficiente para rotear sem perguntar ao usuário?"
• Tipo: noul (P(sim) = "dá para rotear sem perguntar").
• Uso: comparar a abstenção explícita (D3) com a abstenção derivada da confiança de D1 (tarefa 60).

D4 — Várias intenções

• Aplica-se só a enunciados anotados com mais de uma intenção.
• Executa várias perguntas noul sobre o mesmo texto, uma por intenção candidata ("O enunciado pede X?"), na mesma requisição JEV (tarefa 65).
• Métrica: F1 por conjunto de intenções e custo total, que soma as latências.

D5 — Guardrail de entrada (opcional)

• Opções: no_escopo, fora_do_escopo, requer_bloqueio. Só entra se houver dados anotados suficientes.

3. Formato canônico de entrada (tarefa 36)

{
  "id": "conv-000123-t04-D2",
  "group_id": "conv-000123",
  "task": "D2",
  "state": {
    "active_agent": "agente_a",
    "suspended_sessions": ["agente_b"],
    "recent_turns": [
      {"role": "user", "text": "..."},
      {"role": "agent", "agent_id": "agente_a", "text": "..."}
    ],
    "eligible_intents": ["intencao_1", "intencao_2"]
  },
  "utterance": "...",
  "question": "Como o orquestrador deve tratar este turno?",
  "question_type": "choice",
  "options": {
    "continuar_agente_ativo": "...",
    "retomar_sessao:agente_b": "...",
    "iniciar_novo_agente": "...",
    "desambiguar": "..."
  },
  "gold_label": "retomar_sessao:agente_b",
  "metadata": {
    "taxonomy_version": "v0.1",
    "domain": "...",
    "length_bucket": "curto",
    "ambiguity": "media",
    "turn_index": 4,
    "adversarial": ["abreviacao"],
    "n_options": 4,
    "n_tokens": {"laya": 0, "semif": 0, "gliner": 0, "rizzo_flow": 0}
  }
}

Conversão para JEV. question vira questions.<task>.instructions e options vira criteria (contrato jev-compat-v1, em contracts/jev/schemas/). O state enviado é sempre o texto serializado descrito abaixo, nunca o objeto estruturado.

Serialização do estado. Alguns candidatos aceitam só texto, e não state estruturado. Por isso, uma única regra de serialização de state + utterance em texto vale para todos os adaptadores (um bloco "Contexto:" com o agente ativo, as sessões suspensas e os N últimos turnos, seguido de "Mensagem:"; N calculado como em 04, Q8). A regra é versionada junto com a política de truncamento (tarefa 53). Um adaptador não pode usar informação de state que não esteja nessa serialização.

4. Dados

Primeiro ciclo: pipeline sintético (datagen/).

Etapa	Implementação	Tarefas
Geração	datagen.generate: 42 intenções × 7 perfis + 5 categorias fora de escopo × 9 lotes; 12 enunciados por lote. Geradores alternados meta.llama-4-maverick e cohere.command-a (fornecedores distintos dos anotadores). Perfis: curto/neutro, informal/abreviado, erros de digitação, regionalismo, emocional, longo com contexto, indireto ou com várias intenções	24, 27
Preparação	datagen.prepare: mascaramento de dados pessoais (CPF, CNPJ, cartão, telefone, e-mail, CEP), deduplicação exata e aproximada (Jaccard ≥ 0,85 em 5-gramas), limites de comprimento	25, 28
Anotação	datagen.annotate: três modelos (openai.gpt-5.5, google.gemini-2.5-pro, xai.grok-4.3) em rodízio por lote; dois anotam de forma independente, sem ver o rótulo de geração, e o terceiro desempata. Três rótulos distintos → exemplo excluído. Instruções: 06-guia-de-anotacao.md	29–32
Montagem	datagen.build: partição por lote de geração (3/2/2 lotes por intenção para teste/calibração/dev), conjuntos de 4, 8, 12 ou 16 opções simulando a elegibilidade (10% sem a intenção correta → sem_correspondencia), lint e congelamento com SHA-256 em dmb-entrada e dmb-logs-imutaveis	33–36

Conjunto d1-v1: 4.068 gerados → 4.057 após a preparação → 4054 após a anotação (62 por desempate; 3 excluídos). Partições: dev 1183, calibração 1127, teste 1744, com 43 rótulos em todas. Kappa entre anotadores de 0.98 a 0.99: a concordância muito alta sugere que parte dos casos sintéticos é fácil. Para o relatório, os cortes por perfil (erros, regionalismo, emocional, indireto) e por gold_eligible=false devem receber atenção.

Itens abaixo descrevem o desenho geral (válido também para dados reais em ciclos futuros).

• Unidade de amostragem: conversa (group_id). Cada turno anotado gera um ou mais exemplos (um por tarefa de decisão).
• Fontes: enunciados representativos do domínio de destino, anonimizados (tarefas 24–25). Se houver dados sintéticos, eles ficam identificados em metadata e são reportados em separado.
• Estratificação (tarefa 26): domínio, comprimento, ambiguidade, classe esperada, posição do turno e presença de agente ativo ou de sessões suspensas.
• Adversariais (tarefa 27): abreviações, erros de ortografia, regionalismos, enunciados muito curtos e dependentes de contexto ("sim", "o outro"), várias intenções, troca de assunto no meio da conversa, retorno a um assunto anterior e pedidos fora de escopo.
• Anotação (tarefas 29–32): dois anotadores independentes e um terceiro para adjudicação. Para cada exemplo se registram o rótulo, a justificativa e a versão da taxonomia. A concordância (kappa de Cohen ou alfa de Krippendorff) vai para o relatório.
• Partições (tarefas 33–35): desenvolvimento, calibração e teste final, separadas por group_id. O teste final é congelado (hash registrado) antes de qualquer ajuste.

5. Protocolo de execução

Etapa	Partição	O que pode mudar	Tarefas
Conformidade e sanidade	fixtures	adaptadores	41, 49–51
Piloto CPU/GPU (50 ex.)	dev	só parâmetros operacionais	55–58
Desenvolvimento	dev	nada além do operacional; sem calibração	59
Calibração	calibração	limiares de confiança, regra de abstenção, calibradores por candidato	60–61
Congelamento	—	nada daqui em diante	62
Teste final	teste	—	63–66

• Seeds, ordem dos exemplos, lote, precisão numérica (fp32, bf16 ou fp16 por candidato, registrada) e limite de tokens fixos por execução (tarefa 52).
• As medições de desempenho são feitas depois do aquecimento, com no mínimo três execuções independentes (tarefa 66).
• Cenários de execução: CPU com lote 1, GPU com lote 1 e GPU com lote de produção (escolhido automaticamente, ver Q6). O lote 1 representa o caminho síncrono do orquestrador; o lote maior mede a vazão.

6. Métricas

Qualidade (tarefas 67–68)

• Accuracy, macro F1, precision e recall por classe, matriz de confusão.
• Taxa de rota errada com confiança alta (erro que não seria desambiguado): é a métrica de maior impacto operacional.
• Brier score, ECE, curva cobertura × acurácia seletiva e AURC, calculados sobre max(probabilities) calibrado. A confidence nativa do JEV não é calibrada e só é registrada.
• D4: F1 por conjunto de intenções.

Desempenho (tarefas 69–70)

• Latência p50, p95 e p99 por decisão e por turno (soma das decisões do turno).
• Vazão, uso de GPU, RAM, VRAM, tempo de carga, tempo de aquecimento e armazenamento dos artefatos.
• Custo estimado por mil decisões em cada cenário, a partir do preço do shape OCI e da vazão medida.

Cortes (tarefa 71): tarefa de decisão, número de opções, comprimento, ambiguidade, posição do turno, com ou sem agente ativo e categoria adversarial.

Análise de erros (tarefas 72–73): taxonomia, contexto insuficiente, ambiguidade, linguagem, truncamento, instrução ou desempenho do modelo.

7. Ameaças à validade

• Vantagem de formato. Cada modelo pode ter sido treinado com um estilo de prompt diferente. Por isso há um contrato único e uma serialização única, e os desvios ficam documentados por adaptador.
• Vazamento entre partições. É controlado pela partição por group_id e pelo congelamento com hash.
• Truncamento desigual. Todos usam a mesma política, baseada no menor contexto efetivo, e a contagem de tokens de cada entrada é registrada.
• Representatividade. Dados sintéticos e reais são reportados em separado.
• Elegibilidade simulada. Em produção, o conjunto de opções vem de um serviço. Aqui ele é fixado por exemplo.