Jev errou em produção: ajustar o state, o schema da pergunta ou o threshold?

Chegou o primeiro feedback humano dizendo que o rótulo saiu errado, e o reflexo é quase sempre o mesmo: reescrever a pergunta, engordar o state e baixar o corte de confiança, tudo no mesmo commit

Aí o número melhora e você não faz a menor ideia do que resolveu 😅

O Jev é o primeiro modelo público da TypeSafe AI, lançado em setembro de 2026 em early access, e é um modelo da família System One: decisões estruturadas para software, sem geração de texto. É justamente por ser estruturado que dá pra fazer diagnóstico de verdade aqui. Quase todo erro que um humano aponta em produção cai em UMA de três alavancas: o state (o que o modelo viu), o schema (o que você perguntou e que formatos de resposta ofereceu) ou o threshold (o corte que o seu código aplica antes de agir). E quando não cai em nenhuma das três, costuma ser limitação já conhecida da versão, que tem página própria e a gente vê mais pra frente

Bora separar essas três antes de sair mexendo?

As três alavancas: o que é state, o que é schema e o que é threshold

Antes do diagnóstico, a anatomia da chamada, porque ela já entrega metade do caminho

Uma requisição ao System One tem duas partes. O campo state carrega o conteúdo a ser avaliado: a mensagem de suporte, o texto, o estado atual da aplicação, mais os fatos de apoio. O campo questions carrega os julgamentos que você quer fazer sobre aquele material

E tem um detalhe que muda TUDO no jeito de depurar: as perguntas são avaliadas de forma independente e em paralelo contra o mesmo state. O resultado de uma não vira contexto escondido que empurra a outra. A composição acontece depois, no seu código

Ou seja: se uma pergunta saiu errada, o problema está naquela pergunta ou no state, nunca numa "conversa" entre perguntas que você não viu acontecer

Como o state costuma ser conteúdo real de cliente, vale ter resolvido antes a parte de anonimizar dados sensíveis no state, senão a rodada de ajuste vira outro tipo de problema

Schema é a escolha da primitiva mais o desenho das opções

Existem três tipos de pergunta, chamadas de primitivas, cada uma devolvendo um formato diferente de resposta tipada:

• Choice: uma opção de um conjunto conhecido, sem ordem entre elas (roteamento de ticket, tipo de documento, linguagem de programação)
• Score: uma nota
• Noul: sim/não, onde a resposta é a probabilidade da afirmação ser verdadeira

Quando eu falo "schema" aqui, não é só escolher entre Choice, Score e Noul. É também o desenho das opções do Choice, dos níveis do Score e do campo criteria do Noul (que é opcional e aceita descrições estruturadas de verdadeiro e falso pra fixar a fronteira)

No Choice, as opções são mutuamente exclusivas: exatamente uma se aplica. Cada uma carrega uma descrição curta, e a resposta traz a opção escolhida, a probabilidade de cada opção e a confiança

E o threshold? Não é a probabilidade do vencedor

Aqui mora o mal-entendido mais comum

Confiança é um número de 0 a 1 calculado a partir do FORMATO da distribuição de probabilidades. Não é a probabilidade da opção vencedora

Distribuição espalhada = confiança baixa. Pico único numa opção = confiança alta. É isso que separa o caso "vencedor com 0,45 e o segundo colado com 0,44" do caso "vencedor com 0,45 e o resto pulverizado". Nos dois o vencedor tem a mesma probabilidade, mas a segunda situação é MUITO mais decidida que a primeira

O threshold, então, é o corte que o seu código aplica em cima desse número pra decidir se age sozinho ou escala

Tabela de diagnóstico: do sintoma observado para a alavanca certa

A regra é: classifica primeiro, confirma a hipótese com um teste barato, só depois mexe. E mexe em uma coisa só

Repare que a coluna da confiança faz um trabalho pesado nesse diagnóstico. Erro com confiança ALTA quase nunca é threshold, é pergunta mal desenhada ou limitação da versão. Erro com confiança BAIXA quase nunca se resolve reescrevendo prompt, o modelo já te avisou que estava em cima do muro

Sintoma: o Jev responde com confiança alta, mas o humano discorda do rótulo

Esse é o caso que mais irrita, porque parece que o modelo "mentiu com convicção"

Causa provável: a pergunta está ampla ou ambígua, e o modelo respondeu literalmente o que você escreveu, não o que você quis dizer. Isso não é achismo meu: leitura literal da pergunta é uma limitação documentada do jev-1.13. Palavras de escopo, negações e condições implícitas são lidas ao pé da letra

Alavanca: schema

A orientação oficial é fazer as perguntas o mais explícitas, estreitas, específicas e atômicas possíveis, quebrando julgamentos amplos em perguntas separadas, cada uma avaliando UMA propriedade. A própria documentação chama isso de provavelmente o conceito mais importante do guia de construção, e dá pra ver o raciocínio completo no guia de como construir com System One

Na prática:

1. Pegue a pergunta que errou e liste quantas propriedades diferentes ela está avaliando ao mesmo tempo
2. Quebre em uma pergunta por propriedade, cada uma com instrução e critério explícito
3. Nas opções de Choice, troque a descrição curta por um objeto estruturado dizendo o que a opção cobre E o que ela não cobre (instructions, opções de Choice, níveis de Score e criteria de Noul aceitam estrutura JSON)
4. No Noul, preencha o criteria com as descrições de verdadeiro e falso pra fixar a fronteira

O erro comum deste passo: quebrar a pergunta em cinco e esquecer que elas rodam independentes, sem enxergar umas às outras. Se a sua pergunta 4 só faz sentido depois da resposta da pergunta 2, essa dependência tem que virar if no seu código, não pressuposto dentro do texto da pergunta

Como prevenir: antes de culpar o modelo, leia a pergunta como um advogado leria, ao pé da letra, sem boa vontade. Se sobrou espaço pra interpretação, o espaço é seu problema, não dele

Sintoma: o erro muda conforme o ticket, mesmo com a mesma pergunta

Mesma pergunta, mesmo schema, e o acerto oscila de caso pra caso

Causa provável: o state. Ou falta ali a informação necessária pra decidir, ou sobra contexto irrelevante. Os dois doem, e o segundo dói de um jeito que pouca gente imagina: queda de acurácia com state grande e irrelevante é uma das limitações conhecidas do jev-1.13

Alavanca: state

A documentação do campo state orienta três coisas bem diretas:

1. Incluir só o contexto relevante pras perguntas atuais
2. Agrupar informações relacionadas quando a decisão exige comparar uma com a outra
3. Usar JSON aninhado e apontar a pergunta para caminhos específicos com crases

O erro comum deste passo: montar um state genérico "que serve pra tudo" e reaproveitar em todas as chamadas. Você acha que está economizando trabalho e está injetando ruído em toda decisão

E tem um efeito colateral simpático: state enxuto custa menos, já que a cobrança é por token de entrada. Se a sua conta anda subindo junto com o erro, vale olhar a parte de enxugar o state do Jev na mesma passada

Como prevenir: monte o state A PARTIR das perguntas, nunca o contrário. Escreve as questions primeiro, depois pergunta pra cada campo do state: qual pergunta precisa disso? Se nenhuma precisa, fora

Sintoma: o erro só aparece em casos limítrofes e a confiança estava baixa

Esse aqui é o mais fácil de resolver e o mais fácil de resolver errado 😀

Causa provável: o schema tá ok, o state tá ok, e o modelo até sinalizou a dúvida. O que está errado é o seu código, que liberou automaticamente uma decisão que deveria ter escalado

Alavanca: threshold, sem tocar em pergunta nem em state

Primeiro, mate a ideia de "o threshold do sistema". Não é um número único. Ações diferentes dentro do MESMO sistema devem ser liberadas em níveis diferentes, conforme a consequência do erro

O exemplo de banking da documentação deixa isso didático: ação de baixo risco (ver saldo) passa com 0,6 de confiança, ação de alto risco exige confiança acima de 0,85, e na faixa intermediária o sistema confirma a intenção com o usuário em vez de chutar. Esse é o padrão de roteamento por confiança, documentado direitinho pela TypeSafe

Quanto você ganha subindo o corte?

Tem um número público bom pra calibrar expectativa. O cookbook oficial de self-consistency com Choice roda a mesma rubrica 15 vezes sobre um post limítrofe e mede quanto o rótulo se mantém

• Sem corte, o Jev repete o rótulo majoritário em 90,8% das repetições
• Exigindo pelo menos 0,60 de probabilidade na opção vencedora (repare: o corte do cookbook é a probabilidade do vencedor, não a confiança) pra decidir automaticamente, a concordância sobe pra 99,2%
• E o rótulo automático passa a cobrir 74,2% das respostas

Olha o trade-off aí escancarado: você compra quase 9 pontos de concordância pagando com um quarto da automação. Esse é exatamente o tipo de conta que só você consegue fazer, porque depende do custo do seu erro e do custo da sua revisão humana

Como prevenir: a doc orienta testar thresholds plotando confiança contra acurácia nos SEUS dados, e definir os limites de produção a partir de exemplos rotulados. Código com caminho pra resposta confiante e caminho pra resposta não confiante, e os casos incertos escalando pra pessoa ou pra um modelo de raciocínio mais caro

Sem exemplos rotulados, mexer no threshold é chute com cara de engenharia

Sintoma: o erro se concentra em números, datas, negações ou cores

Antes de abrir uma rodada de ajuste, checa se você não está brigando com algo já mapeado

Causa provável: não é bug do seu prompt, é limitação conhecida da versão. A TypeSafe publica uma página de jaggedness do jev-1.13, revisada em 17 de setembro de 2026, com nove modos de falha conhecidos, muitos previstos pra correção em versões futuras

Entre eles:

• Leitura literal da pergunta
• Contagem e precisão numérica não confiáveis
• Datas lidas como texto, não como quantidades ordenadas
• Dupla negativa e indireção
• Cores em hex/RGB
• Queda de acurácia com state grande e irrelevante

Se o seu erro casa com um desses, parar de reescrever a pergunta pela décima vez é o movimento inteligente

Solução: resolver em código antes da chamada

• Precisa saber se a data A é depois da data B? Compara no seu código e manda o resultado pronto no state, em vez de pedir pro modelo ordenar texto
• Precisa contar ocorrências? Conta você e manda o número
• A pergunta tem dupla negativa? Reescreve em afirmativa, direto
• Precisa julgar cor? Converte o hex pra um nome ou categoria antes

O erro comum deste passo: tentar consertar limitação de versão com "prompt melhor". Não é teimosia do modelo, é característica conhecida da versão, e a página de jaggedness existe justamente pra te poupar essa semana

Como prevenir: leia a lista de jaggedness ANTES de abrir a rodada de ajuste, não depois. Leva cinco minutos

Sintoma: taxonomia profunda com opções que se confundem entre si

Classificação de ticket em árvore de categoria, tipo de documento com subtipo, esse tipo de coisa

Causa provável: um único Choice com opções demais e fronteiras borradas. Lembra que no Choice as opções são mutuamente exclusivas, exatamente uma se aplica. Quando você empilha vinte opções de níveis diferentes da taxonomia no mesmo conjunto, essa exclusividade some na prática, mesmo que continue verdadeira no papel

Alavanca: schema

A recomendação pra taxonomia profunda é fazer um Choice por nível e caminhar a árvore em código, com as opções sendo os filhos do nó atual. Está detalhado nas opções avançadas das primitivas, na doc

O fluxo fica assim:

1. Choice no nível 1, com os filhos da raiz como opções
2. Seu código lê a opção escolhida e a confiança
3. Se passou no corte daquele nível, monta o Choice do nível 2 com os filhos do nó escolhido
4. Repete até chegar na folha

O erro comum deste passo: aplicar o mesmo corte de confiança em todos os níveis. Errar o nível 1 joga fora a árvore inteira abaixo dele, então esse nível costuma merecer um corte mais duro que os de baixo

Como prevenir: em cada nó, cada opção com descrição curta, ou com objeto estruturado delimitando o que ela cobre e o que NÃO cobre. Se você não consegue escrever o "não cobre" de duas opções sem elas se tocarem, elas não são mutuamente exclusivas de verdade e o problema está no desenho da taxonomia, não no modelo

Como aplicar o diagnóstico no Pydantic AI e na API direta

Beleza, e onde cada alavanca aparece na prática?

Na API direta

Todos os modelos são servidos pelo mesmo endpoint: POST https://api.typesafe.ai/v1/systemone, com o state e as questions no corpo da requisição

Pra descobrir os nomes aceitos no campo model, tem o GET /v1/models:

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Detalhe útil quando você está comparando versões durante um diagnóstico: IDs versionados como jev-1.13.0 são aceitos no campo model mesmo sem aparecer na lista. Isso importa porque, se você não fixa a versão, uma mudança de comportamento pode aparecer no meio da sua rodada de ajuste e contaminar a conclusão

O erro comum aqui: rodar o lote rotulado com o nome genérico do modelo e comparar com um resultado antigo. Fixa o ID versionado dos dois lados, senão você não está medindo o seu ajuste, está medindo duas coisas ao mesmo tempo

No Pydantic AI

É aqui que a alavanca threshold fica mais explícita. A documentação do Pydantic AI para o TypeSafe descreve dois pontos que interessam direto pro diagnóstico

Primeiro, a confiança de cada resposta vem em provider_details['confidence'], de 0 a 1, um número por campo. E tem uma sutileza importante: ali ela é medida como distância do threshold, não como probabilidade da resposta estar certa. Vai de 0 (em cima do threshold) até 1 (certeza)

Segundo, o corte sim/não é o parâmetro typesafe_boolean_threshold, de 0 a 1, com padrão 0.5. Ele vale pra todo campo bool e pra cada opção de lista de Literal ou Enum, com um sim/não por opção

# corte sim/não: 0 a 1, padrão 0.5
settings = TypeSafeModelSettings(typesafe_boolean_threshold=0.9)

# settings vai pro Agent, conforme a doc do Pydantic AI
# e a confiança de cada campo volta em:
#   result.provider_details['confidence']

O erro comum deste passo: subir o typesafe_boolean_threshold e esperar que os erros de interpretação da pergunta sumam junto. Não somem. Threshold mexe em quando você age, nunca em como o modelo entendeu o que você perguntou

O custo de reprocessar o lote é baixo

E isso muda o comportamento de quem depura. Reavaliar o mesmo conjunto de exemplos rotulados a cada mudança sai por US$ 0,042 por 1 milhão de tokens de entrada, com tokens de saída não cobrados

Ou seja: rodar o lote inteiro de novo depois de mexer em UMA alavanca é barato. O caro é mexer em três de uma vez e perder a capacidade de atribuir o ganho

Vídeo: IA em produção e o custo de errar

Pra começar do zero na conversa sobre decisões automatizadas e o tamanho da conta quando a IA erra fora do laboratório, este vídeo do canal mostra o caso do primeiro ataque hacker com IA e o que ele significa pra quem coloca modelo em produção

O que fazer na próxima vez que o feedback humano chegar

O protocolo é curto e cabe num card de tarefa:

1. Registre o caso com a resposta completa E a confiança devolvida, não só o rótulo errado. Sem a confiança, metade do diagnóstico morre
2. Classifique o sintoma pela tabela lá de cima, em state, schema ou threshold (ou na quarta caixa, limitação conhecida da versão)
3. Confirme a hipótese com o teste barato daquela linha antes de escrever código
4. Mude UMA coisa só
5. Reavalie contra o mesmo lote rotulado, com o ID de versão fixo dos dois lados

O erro comum do processo inteiro: começar sem lote rotulado. Aí cada rodada vira opinião sobre três ou quatro casos que alguém lembrou

Próximo passo natural, então: junte os erros já reportados pelos humanos num conjunto de exemplos rotulados, plote confiança contra acurácia em cima deles e só DEPOIS defina os cortes de produção, ação por ação, pelo custo do erro e pelo custo da revisão

Depois disso, quando o Jev errou de novo, você não vai perguntar "o que eu mudo?"

Você vai olhar a confiança e já saber em qual das três alavancas mexer 😉

até o próximo post!