As primitivas do Jev: Choice, Score e Noul

Perguntar bem para o Jev é uma habilidade de projeto, e ela começa escolhendo a forma certa da pergunta. A API aceita exatamente três — a documentação chama de primitivas, no sentido de primitivas de software: blocos pequenos, tipados e componíveis. Esta página explica as três, como misturá-las e o que a orientação oficial diz sobre escrever perguntas que funcionam.

As três primitivas em uma tabela

Toda pergunta tem um identificador (que só o seu código vê), um type e as instructions — a pergunta em si, escrita em português se você quiser. Choice e Score também exigem criteria: as opções de uma, os níveis da outra. Noul aceita critérios opcionais que esclarecem o que conta como sim e como não.

Uma chamada, todas as perguntas

A regra de ouro da documentação: envie juntas todas as perguntas que usam o mesmo estado. As perguntas de uma requisição são avaliadas em paralelo e em isolamento — uma resposta não vira contexto da outra. Adicionar perguntas quase não muda o tempo de resposta, e o custo extra é só dos tokens que as perguntas adicionam.

Isso muda o hábito de quem vem de LLMs. Não existe “fazer outra pergunta na mesma conversa”: existe outra pergunta na mesma chamada. Um exemplo real — classificar uma mensagem, checar urgência e medir frustração de uma vez:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

state = {
    "ticket_message": "Meu voo foi cancelado. Consigo o reembolso?",
    "refund_policy": "Voos cancelados dão direito a reembolso integral.",
}

with TypeSafeClient() as client:
    response = client.system_one(
        state=state,
        questions={
            "reembolso_pediu": Noul(
                instructions="`ticket_message` pede reembolso?",
            ),
            "tipo_pedido": Choice(
                instructions="Qual é o pedido principal de `ticket_message`?",
                criteria={
                    "reembolso": "O cliente quer o dinheiro de volta.",
                    "remarcar": "O cliente quer outro voo.",
                    "informacao": "O cliente só quer informação.",
                },
            ),
            "frustracao": Score(
                instructions="Qual o nível de frustração em `ticket_message`?",
                criteria=[
                    "Calma, apenas fatos.",
                    "Preocupado, mas civil.",
                    "Muito irritado ou linguagem forte.",
                ],
            ),
        },
    )

Repare no detalhe das crases: quando o estado é estruturado (JSON), a documentação orienta apontar nas instructions o caminho do campo avaliado, como `ticket_message` — o modelo sabe exatamente qual parte julgar.

Perguntas atômicas, compostas no código

A orientação central dos docs é tratar cada pergunta como um julgamento rápido: aquele que uma pessoa competente faria em poucos segundos com o contexto certo. “Esta mensagem transmite urgência?” é uma boa pergunta. “Analise esta mensagem e determine o melhor curso de ação” não é — isso exige raciocínio lento e é sinal de decompor.

Se o julgamento depende de vários fatores, a receita oficial é uma pergunta por fator e a combinação no seu código, com pesos seus. Em vez de “avalie este ticket”, pergunte a severidade, a frustração e a qualidade do relato; combine as notas normalizadas com os pesos que o seu time define. Quando a prioridade resultante não bater com o que o time decidiria, mude um coeficiente no código — não reescreva um prompt.

A documentação chama essa técnica de composite scoring, e lista outros padrões nomeados: speculative fan-out (perguntas especulativas cujas respostas você só usa quando importam), confidence-gated routing (usar a confiança como segundo eixo de decisão) e intent routing (classificar a intenção e rotear o fluxo).

Quando uma pergunta depende da outra

Perguntas na mesma chamada são independentes por construção. Se um julgamento posterior depende de uma resposta anterior, a documentação é clara: faça uma segunda requisição — mas só quando o código realmente precisar da primeira resposta para montar a segunda (buscar mais dados, decidir o estado, escolher as opções seguintes). Duas chamadas são a exceção, não a regra.

O orçamento de tokens de uma requisição, segundo os docs, fica em torno de 32 mil tokens — estado e perguntas dividem o mesmo orçamento, o que dá cerca de 150 mil caracteres de texto em inglês. É muito espaço para quase todo caso real.

Por onde continuar

Cada primitiva tem a sua página neste guia, com exemplos em português e os detalhes que a documentação espalha: as três páginas saem dos links na tabela acima. Para ver as três trabalhando juntas em um caso brasileiro, o playground roda as seis perguntas clássicas de triagem em uma chamada só — e o pilar O que é Jev explica por que essa arquitetura muda o contrato entre software e IA.