Como explicar para o usuário final uma decisão tomada pelo Jev?

O Jev decide, mas não te diz por quê

E pode apostar: o cliente vai perguntar 😅

Se liga no contexto: o Jev é da TypeSafe AI, foi apresentado em 15 de setembro de 2026 e é o primeiro modelo da categoria que a empresa chama de System One Models

Ele recebe o estado de um programa (texto ou JSON) e devolve uma decisão tipada com a probabilidade de cada opção

Nada de prosa, nada de ‘escolhi isso porque…’

E isso não é bug, é escolha de design: o Jev não escreve resposta de chat, código nem explicação, e esse design é o próprio produto

Então o trabalho de comunicar a decisão fica com o SEU código

Neste post eu te mostro como explicar a decisão do Jev pra um cliente ou pra um analista sem inventar um motivo que o modelo nunca deu, beleza?

O que você precisa entender antes de explicar uma decisão do Jev

Antes de escrever qualquer mensagem, você precisa saber exatamente o que o Jev te entrega

Só dá pra explicar o que existe na saída 🙂

Quais são os tipos de pergunta do Jev e o que cada um devolve?

São três tipos, e cada um devolve uma coisa diferente:

Repara no Noul: ele não tem confiança separada, então a própria probabilidade é o que você tem pra trabalhar

O Jev pode devolver uma resposta fora das opções?

Não

As opções são declaradas no schema, e o Jev não devolve valor fora desse conjunto nem JSON quebrado

Pra quem vai montar mensagem pro usuário isso é ótimo: todas as saídas possíveis são conhecidas de antemão, então dá pra preparar o texto de cada uma

O que acontece quando nenhuma opção serve?

Aqui mora o perigo…

Quando as opções não cobrem a situação, o Jev escolhe uma das categorias oferecidas mesmo assim, só que com confiança baixa

Não existe um sinal de ‘nenhuma se aplica’

Tome cuidado! Se o seu sistema pegar a categoria escolhida e jogar direto na mensagem, você pode acabar explicando pro cliente uma decisão que nem faz sentido pro caso dele

Onde o Jev costuma errar?

A TypeSafe publica uma página de limitações pra versão 1.13 do Jev, com as fraquezas conhecidas:

• aritmética
• contagem
• comparação de datas
• perguntas indiretas
• contexto que distrai
• entrada adversarial

Vale ler isso ANTES de prometer qualquer explicação ao cliente

Se a sua decisão depende de ‘quantas parcelas estão em atraso’ ou ‘o contrato é anterior a tal data’, faz mais sentido calcular isso no seu código e entregar pro Jev como fato pronto, em vez de pedir pra ele fazer a conta

Passo a passo: da decisão tipada a uma mensagem que o usuário entende

Um aviso antes de começar: todo código abaixo é da SUA camada de aplicação

São estruturas ilustrativas pra mostrar a ideia, não a sintaxe da API do Jev nem os nomes dos campos que ela devolve

Passo 1: quebre a decisão em perguntas menores

Por quê? Porque o Jev não te dá motivo, mas te dá respostas

Se em vez de perguntar ‘aprova ou não aprova?’ você faz várias perguntas menores sobre o mesmo estado, cada resposta vira um fator REAL da explicação

E isso sai barato: dá pra fazer várias perguntas sobre o mesmo estado numa única requisição, elas são avaliadas em paralelo e acrescentar perguntas quase não muda o tempo de resposta

Depois você recombina tudo no seu próprio código

Um jeito de organizar isso do seu lado, pensando numa análise de crédito:

{
  "decisao": "analise_de_credito",
  "perguntas": [
    { "id": "renda_comprovada", "tipo": "Noul", "texto": "A renda informada está comprovada nos documentos enviados?" },
    { "id": "documentacao", "tipo": "Choice", "opcoes": ["completa", "incompleta", "ilegivel"] },
    { "id": "risco", "tipo": "Score", "niveis": ["muito_baixo", "baixo", "medio", "alto", "muito_alto"] }
  ]
}

A regra de recombinação também é sua, e fica explícita:

se documentacao == "incompleta" ou documentacao == "ilegivel":
    resultado = "pendente_documentos"
senao se renda_comprovada for baixa:
    resultado = "em_analise"
senao:
    resultado = decidir_pelo_risco(risco)

O erro comum deste passo: fazer uma única pergunta gigante (‘aprova esse cliente?’) e depois inventar os motivos pra justificar a resposta

Se o motivo não saiu de uma pergunta, ele não existe

Passo 2: monte um template fixo pra cada categoria do schema

Como o Jev só devolve opções do schema, você já conhece todas as saídas possíveis

Então cada opção ganha um texto fixo, escrito e revisado por gente (produto, atendimento, jurídico, quem for)

{
  "documentacao": {
    "completa": null,
    "incompleta": "Faltam documentos para concluir sua análise, confira a lista na sua área de cliente e envie o que estiver pendente",
    "ilegivel": "Não conseguimos ler um ou mais documentos enviados, você pode reenviar uma versão mais nítida?"
  },
  "status": {
    "decisao_automatica": "Sua solicitação foi analisada",
    "em_analise": "Sua solicitação está em análise com a nossa equipe"
  }
}

É tipo tabela de mensagens de erro de formulário: ninguém escreve o texto na hora que o erro acontece, ele já está pronto pra cada caso

O erro comum deste passo: deixar texto livre ser gerado a cada decisão, sem nada amarrando ao que o Jev respondeu

Aí cada cliente recebe uma explicação diferente pra mesma categoria, e algumas vêm com motivo inventado

Passo 3: transforme confiança em faixa de linguagem

Que confiança? É o número que o Choice e o Score devolvem junto com a resposta, indicando o quanto o modelo está seguro da escolha

No Noul, você olha a própria probabilidade

O cliente não precisa ver esse número, ele precisa saber se a decisão está tomada ou se ainda está em análise

faixa = classificar(confianca, limites_calibrados_com_seus_dados)

se faixa == "alta":
    status = "decisao_automatica"
se faixa == "baixa":
    status = "em_analise"

E os limites? Esses VOCÊ define, com os seus dados

A TypeSafe treina a calibração com um método que chama de RLCD (Reinforcement Learning for Calibrated Decisions), e a meta é que, se o Jev disser 0,9 em cem entradas, cerca de noventa sejam verdadeiras

Meta, não garantia: 90% de confiança não garante 90% de acerto no SEU caso

Então pega um lote de decisões já revisadas por pessoas, compara com a confiança que o Jev deu e só depois define onde fica o corte

E continua acompanhando depois de colocar no ar, que é o assunto de medir o acerto do Jev ao longo do tempo

O erro comum deste passo: mostrar a porcentagem crua ao cliente

Uma porcentagem de ‘chance de reprovação’ na tela assusta, confunde e ainda passa uma precisão que você nem validou

Passo 4: mande a confiança baixa pra uma pessoa

O padrão de roteamento é simples: confiança alta segue direto, confiança baixa vai pra revisão humana

E nesse caso quem escreve a justificativa é a pessoa, olhando o caso e as respostas das perguntas auxiliares

se status == "em_analise":
    enviar_para_fila_humana(caso, respostas, confianca)
    mensagem = templates["status"]["em_analise"]

O mesmo roteamento aparece em outros fluxos, tipo quando você usa o Jev pra moderar conteúdo enviado por usuários

O erro comum deste passo: tratar confiança baixa como resposta válida

Lembra que o Jev não tem sinal de ‘nenhuma’? Confiança baixa pode ser exatamente isso: nenhuma opção do schema serve pro caso

Passo 5 (opcional): peça pra um LLM de fronteira redigir, amarrado aos dados

Se os templates ficarem engessados demais, dá pra colocar um LLM de fronteira pra redigir

Faz sentido: pra texto, código ou justificativa escrita, a indicação é usar um LLM de fronteira, e ele combina bem com o Jev, que fica como camada rápida de decisão: classifica, pontua e encaminha os casos difíceis

Ou seja, cada um no seu papel: o Jev decide e o LLM de fronteira escreve o texto que o cliente vai ler

O segredo (que não é segredo nenhum haha) é alimentar o LLM SÓ com os campos estruturados e proibir que ele acrescente motivos:

Você vai redigir uma mensagem curta para um cliente
Use SOMENTE os fatos abaixo
Não acrescente motivos, hipóteses nem critérios que não estejam na lista

Status: pendente_documentos
Fatores: documentacao = incompleta
Próximo passo: enviar documentos pendentes pela área de cliente

O erro comum deste passo: pedir pro LLM ‘explicar o raciocínio do Jev’

Esse raciocínio não existe na saída, então o LLM vai inventar um, e vai soar convincente (o que é muiiito pior)

Passo 6: registre tudo

O Jev devolve um número, não uma justificativa, e isso pesa em debug e em auditoria

Então o seu log precisa guardar o caminho completo da decisão:

{
  "caso_id": "12345",
  "entrada": "estado enviado ao Jev",
  "perguntas": ["renda_comprovada", "documentacao", "risco"],
  "respostas": { "documentacao": "incompleta" },
  "confianca": "valor devolvido",
  "faixa": "baixa",
  "rota": "fila_humana",
  "mensagem_enviada": "texto exato que o cliente recebeu"
}

Quando alguém pedir revisão ou quando uma decisão estranha aparecer, é aqui que você vai procurar

O erro comum deste passo: salvar só a mensagem final

Sem as perguntas e as respostas, você sabe o que disse pro cliente, mas não sabe de onde aquilo saiu

Exemplos: a mesma decisão explicada para o cliente e para o analista

A saída do Jev é uma só, mas quem lê muda tudo

Bora ver na prática com o mesmo caso de crédito?

Como fica a mensagem para o cliente final?

Curta, baseada nos fatores das perguntas decompostas, sem porcentagem e com caminho pra revisão:

Sua solicitação está em análise

Faltam documentos para concluir a avaliação, confira a lista na sua área de cliente e envie o que estiver pendente

Se quiser que uma pessoa da nossa equipe revise o seu caso, é só pedir por aqui

Repara que não tem nenhum ‘porque o modelo achou que…’

O único motivo citado é a documentação incompleta, que veio de uma pergunta real

O que o analista interno precisa ver?

O analista quer o oposto: tudo aberto, pra entender e debugar

• a probabilidade de cada opção nas perguntas do tipo Choice
• a distribuição do Score de risco, não só o nível escolhido
• a confiança de cada resposta (e a probabilidade pura nas do tipo Noul)
• as respostas de todas as perguntas auxiliares
• a faixa calculada e a rota que o caso seguiu

Se o risco veio ‘médio’ com a distribuição espalhada entre vários níveis, isso é sinal pro analista olhar com calma

Pro cliente, a mesma informação vira só ‘em análise’ 🙂

E em setores regulados, o que a LGPD pede?

Aqui não é parecer jurídico, beleza? É só o que a lei diz e como o seu sistema ajuda

Pelo art. 20 da LGPD, o titular pode pedir revisão de decisões tomadas só com base em tratamento automatizado de dados pessoais que afetem os interesses dele, como perfil pessoal, profissional, de consumo e de crédito

E o §1º obriga o controlador a fornecer, quando solicitado, informações claras e adequadas sobre os critérios e procedimentos da decisão, respeitados os segredos comercial e industrial

Ou seja: a lei não exige revelar o modelo nem a fórmula

Mas exige que você consiga dizer, de forma clara, quais critérios pesaram

E é exatamente isso que as perguntas decompostas do passo 1 e o log do passo 6 te dão: critérios nomeados, respostas registradas e o caminho que o caso percorreu

Sem isso, você teria só uma categoria e um número pra mostrar

Conclusão: o Jev decide, e a explicação é responsabilidade do seu sistema

Recapitulando a divisão de papéis:

• o Jev é a camada rápida de decisão: classifica, pontua e encaminha
• os templates escrevem o texto de cada categoria do schema
• as pessoas escrevem a justificativa dos casos de confiança baixa
• um LLM de fronteira pode redigir, desde que amarrado aos campos estruturados

Ninguém nessa cadeia inventa motivo

O próximo passo é concreto: pega uma decisão que você já usa, quebra em 3 ou 4 perguntas e valida a calibração da confiança num lote dos seus próprios dados

Só depois disso expõe qualquer mensagem ao cliente

Ficou alguma dúvida ou tem um caso diferente aí? Bora trocar uma ideia nos comentários

Até o próximo post!