setup environment

docs/02-desenho-experimental.md

@@ -0,0 +1,131 @@
+# 02 — Desenho experimental
+
+## 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](04-questoes-em-aberto.md#q5--critérios-de-sucesso-pré-registrados).
+- **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 20 opções**, incluindo `sem_correspondencia` (tarefas 22–23).
+
+### 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 2 a 19, 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)
+
+```json
+{
+  "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/](../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](04-questoes-em-aberto.md#q8--turnos-no-state-e-orçamento-de-tokens)). 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
+
+- **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.