Qual primitiva usar em cada caso

Toda pergunta ao Jev usa uma de três formas: Choice, Score ou Noul. A dúvida sobre qual usar aparece na primeira hora de trabalho e volta sempre, porque a resposta certa depende menos do assunto e mais de uma coisa: o que o seu código vai fazer com o resultado.

A documentação dá o critério em uma frase que vale adotar: se dois tipos parecem servir, prefira aquele cuja resposta o seu código consegue usar direto.

A tabela de decisão

Exemplos concretos, em português, de cada caso:

• Choice. Para qual time vai este ticket: cobrança, técnico ou cancelamento? Qual o tipo deste documento: contrato, nota fiscal ou procuração? Em que idioma está esta mensagem?
• Score. Qual a gravidade deste bug, de cosmético a bloqueio total? Quanta experiência com Python este currículo demonstra? Qual o nível de irritação do cliente?
• Noul. A mensagem pede estorno? O texto menciona prazo? O comentário contém dado pessoal identificável?

Os três testes rápidos

Existe ordem entre as respostas? Se sim, é Score. “Cobrança, técnico e cancelamento” não tem ordem — nenhum é “maior” que o outro. “Cosmético, quebrado com contorno, bloqueio” tem. Quando existe ordem e você consegue descrever cada degrau com uma situação, Score é a forma honesta.

A resposta é uma condição, e não uma categoria? Então é Noul. “Pede estorno” é condição: ou o texto pede, ou não pede, e a graduação interessante é a probabilidade. Repare que isso é diferente de perguntar “qual é o pedido do cliente”, que é Choice entre estorno, remarcação e informação.

O código vai ramificar, ordenar ou testar? Ramificar em N caminhos pede Choice. Ordenar uma fila pede Score, porque a nota é comparável entre casos. Testar uma condição pede Noul.

Onde cada tipo engana

Noul e o falso meio. Um Noul de 0,5 não significa “médio”: significa que sim e não recebem chance parecida. A documentação usa o exemplo de “o candidato é forte em Python?” — sem uma definição de “forte”, a probabilidade fica difícil de interpretar. Duas saídas: definir a condição com precisão (“o currículo declara uso de Python no trabalho?”) ou trocar para um Score com níveis de experiência.

Score e a dimensão escondida. Se o nível diz “pontual, inteligente e experiente”, a pergunta mede três coisas. Uma entrada alta em uma e baixa em outra não tem onde ser colocada: a confiança cai e a nota perde sentido. Uma dimensão por pergunta, e a combinação no seu código.

Choice e a lista incompleta. Sem uma opção “outro” ou “nenhuma das anteriores”, o modelo é obrigado a encaixar o que não encaixa. A documentação recomenda incluir essa saída sempre que a lista possa não cobrir toda entrada. Nos nossos testes em português, o caso de ironia caiu justamente em “outro”, com 79% de probabilidade e confiança 0,72 — a opção de escape foi o que permitiu ao modelo dizer que nada servia bem.

Trocar o tipo e manter o limiar. Este é o erro sutil. Limiar calibrado em um Noul não vale para um Choice. A documentação mostra a mesma pergunta sobre o mesmo ticket com Noul em 0,22 e o Choice de sim e não devolvendo não com 0,99 e confiança 0,97. Choice é relativo: resolve qual opção. Noul é absoluto: pode ser baixo para todas as opções. Os dois convivem bem no mesmo fluxo, desde que cada um tenha o seu próprio limiar.

O mesmo problema nas três formas

Vale ver como o desenho muda quando você troca a primitiva. Suponha uma fila de mensagens de clientes e a pergunta “isto é urgente?”.

from typesafe_sdk import Choice, Noul, Score

perguntas = {
    # Noul: condição, com a probabilidade como sinal contínuo
    "urgente": Noul(instructions="A mensagem exige resposta hoje?"),

    # Score: posição numa régua que dá para ordenar a fila
    "urgencia": Score(
        instructions="Qual o nível de urgência da mensagem?",
        criteria=[
            "Assunto informativo, sem pedido de retorno",
            "Pode esperar alguns dias sem prejuízo",
            "Espera resposta em um ou dois dias",
            "Espera resposta no mesmo dia",
            "Prejuízo em andamento; horas importam",
        ],
    ),

    # Choice: rota de atendimento, que o código usa como desvio
    "fila": Choice(
        instructions="Para qual fila esta mensagem deve ir?",
        criteria={
            "imediata": "Precisa de atendimento humano agora",
            "hoje": "Precisa de resposta hoje",
            "normal": "Entra na fila comum",
            "arquivo": "Não precisa de resposta",
        },
    ),
}

As três são legítimas e respondem coisas diferentes. O Noul dá um número para limiar. O Score dá uma nota para ordenar a fila inteira. O Choice dá uma rota pronta. Na prática, muitos sistemas mandam as três juntas na mesma chamada, porque o custo extra é pequeno, e o código decide qual usar em cada situação — é o fan-out descrito em padrões.

Uma regra de bolso

Comece pela ação. Escreva primeiro o if do seu código e veja de que valor ele precisa. Se precisa de um nome, é Choice. Se precisa de um número comparável, é Score. Se precisa de um booleano com margem, é Noul. Depois disso, o trabalho fica todo na redação dos critérios, e isso tem página própria em critérios que separam de verdade. O hub das três primitivas está em primitivas.