Como transformar comentários de NPS e feedback em temas priorizados com o Jev?

Toda empresa que roda NPS tem a mesma pasta esquecida: milhares de comentários abertos que ninguém leu inteiros

Alguém exportou pro CSV, alguém tentou ler 200 linhas na sexta à tarde, e aí virou aquele slide com três frases escolhidas a dedo

O problema nunca foi falta de dado, foi que comentário é texto solto e texto solto não agrega

Você não soma "o app trava no login" com "não consigo entrar desde ontem"

É exatamente aí que entra o Jev, o modelo de decisão estruturada da TypeSafe AI: em vez de gerar um resumão bonito, ele devolve a decisão já tipada, com as probabilidades (e confiança, dependendo do tipo de pergunta), no formato que o teu código consome direto

Bora ver como montar isso?

O que é o Jev e por que ele muda a classificação de feedback

O Jev é o primeiro modelo System One público da TypeSafe AI, apresentado em setembro de 2026

Repercutiu rápido na imprensa técnica: The Register em 16/09 e TechCrunch em 18/09 do mesmo mês

Segundo a ficha do modelo na Wikipedia), a empresa foi fundada em 2024 por Diogo Almeida, Erik Gafni e Sasha Sheng

Almeida é o CEO e passou cerca de quatro anos na OpenAI trabalhando em RLHF, InstructGPT, ChatGPT e GPT-4, então a casa não é de amadores

Agora a parte que realmente importa pro nosso caso

O Jev não escreve texto e não explica raciocínio

Ele é um modelo de decisão estruturada, não conversacional

Se você conhece a rotina de pedir JSON pra um LLM e rezar pra ele não inventar um campo novo, a diferença é essa: aqui a saída tipada é o produto, não um efeito colateral do prompt

E quando a saída é tipada, cada comentário vira linha de tabela sem passar por regex, sem "limpar" resposta e sem aquele parsing frágil que quebra na terça

Se você ainda tá na dúvida entre as duas abordagens, vale olhar essa comparação de Jev contra saída estruturada de LLM antes de escolher o caminho

As três primitivas em uma tabela

A API tem três tipos de pergunta, chamadas de primitivas, e elas podem compartilhar a mesma requisição

Um detalhe pra guardar: uma Choice aceita no máximo 255 opções

Parece muito, mas taxonomia de temas de NPS cresce rápido, então já anota isso 🙂

O que você precisa antes de começar

Requisitos, do jeito chato mas necessário:

• Conta na TypeSafe com uma API key exportada na variável de ambiente TYPESAFE_API_KEY (o cliente lê ela sozinho e chama jev-latest por padrão)
• SDK Python instalado com pip install typesafe-sdk (ou uv add typesafe-sdk), exigindo Python 3.10 ou superior
• Se o teu stack for Node, o caminho é npm install @typesafe-ai/sdk, com Node.js 20 ou mais novo, e vem ESM, CommonJS e declarações TypeScript
• Um export dos teus comentários de NPS, pode ser CSV mesmo, com o texto aberto e a nota

E tem um atalho MUITO bom antes de escrever qualquer linha de código: o playground no console da TypeSafe, em console.typesafe.ai

Você faz login, cola qualquer texto como state e vai adicionando perguntas na mão

É ali que você descobre se a tua taxonomia faz sentido, sem gastar uma tarde montando script

Passo a passo: de comentário solto a tema, severidade e área responsável

A meta do fluxo é uma linha de tabela por comentário, com tema, severidade, área responsável e alguns sinais binários

1. Desenhe a taxonomia de temas antes de tudo

Abra os teus últimos comentários e escreva a lista de temas que realmente existe no teu produto

Algo como Bug, Performance, Preço, Onboarding, Atendimento, Pedido de funcionalidade, Elogio

Essa lista vira as opções de uma Choice, e o teto é 255 opções

O erro comum deste passo: criar temas que se sobrepõem, tipo "Bug" e "App travando"

Quando duas opções cobrem a mesma coisa, a probabilidade se divide entre elas e a confiança cai, e você vai culpar o modelo por uma taxonomia mal desenhada

2. Monte o state com o comentário

O state pode ser uma string, um objeto JSON ou um array de textos

Pra feedback de NPS, objeto JSON é o mais confortável, porque você leva a nota e o plano junto do texto

A doc recomenda separar a pergunta em um campo e os dados em outros, referenciando os campos pelo nome entre crases dentro da instrução

state = {
    "comentario": "Uso o app todo dia, mas desde a última atualização o login cai sozinho e já perdi o carrinho duas vezes",
    "nota_nps": 3,
    "plano": "Pro",
}

Aí, na pergunta, você escreve algo como "classifique o tema principal do comentario"

O erro comum deste passo: jogar a planilha inteira dentro do state achando que vai classificar tudo de uma vez

É um state por comentário, e a chamada avalia muitas perguntas sobre aquele state

3. Escreva as perguntas escolhendo a primitiva certa

Tema e área responsável são Choice, porque a resposta é uma de uma lista fechada

Severidade é Score, porque é posição num espectro descrito em níveis, e o Jev pode devolver um valor caindo entre dois níveis

Risco de churn e pedido de reembolso são Noul, que é sim ou não e volta como probabilidade entre 0 e 1

O erro comum deste passo: usar Choice pra severidade com opções "baixa, média, alta"

Funciona, mas você joga fora a graça do Score, que é justamente a posição contínua entre níveis, e é ela que ordena a fila de priorização

4. Faça a chamada com uma requisição só

No SDK Python você importa as primitivas e o cliente, e chama client.system_one(state, questions)

As chaves do mapa de perguntas são escolhidas por você, e as respostas voltam sob as mesmas chaves

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

# o cliente lê TYPESAFE_API_KEY do ambiente e chama jev-latest por padrão
client = TypeSafeClient()

questions = {
    "tema": Choice(...),          # opções: a tua taxonomia de temas
    "area": Choice(...),          # opções: os times donos de cada área
    "severidade": Score(...),     # níveis: de irritação leve a bloqueio total
    "pede_reembolso": Noul(...),  # critério: o cliente pede dinheiro de volta?
}

result = client.system_one(state, questions)

Os campos exatos de cada primitiva estão na documentação das primitivas, então não chuta: abre a página e copia a assinatura certa

Se preferir bater na API na mão, é um POST para https://api.typesafe.ai/v1/systemone, com header Authorization: Bearer <API_KEY> e corpo carregando state, model e o mapa de questions

O erro comum deste passo: esquecer de exportar a chave e ficar caçando bug no código

Se a variável TYPESAFE_API_KEY não estiver no ambiente, o cliente não tem como autenticar, e o erro vem da autenticação, não da tua pergunta

5. Leia a resposta e monte a linha da tabela

As respostas vêm separadas por tipo: result.choices, result.scores e result.nouls

tema = result.choices["tema"]
area = result.choices["area"]
severidade = result.scores["severidade"]
reembolso = result.nouls["pede_reembolso"]

linha = {
    "comentario": state["comentario"],
    "nota_nps": state["nota_nps"],
    "tema": tema,
    "area": area,
    "severidade": severidade,
    "pede_reembolso": reembolso,
}

Repare que em nenhum momento teve split, json.loads numa string duvidosa ou aquele tratamento pra quando o modelo resolveu escrever "Claro! Aqui está a classificação:" antes do JSON

É isso que "saída tipada" significa na prática

O erro comum deste passo: guardar só a opção escolhida e descartar as probabilidades e a confiança

Essas colunas extras são o que te deixa separar depois o que vai direto pro relatório do que precisa de revisão humana

Como rodar em escala: uma chamada, muitas perguntas

Aqui tá a sacada que muda o custo do projeto inteiro

O Jev ingere o state uma vez e avalia todas as perguntas contra ele em paralelo

Adicionar perguntas quase não muda o tempo de resposta e custa apenas os tokens das perguntas extras

O nome disso na doc é speculative fan-out: você manda numa única chamada todas as perguntas que o código pode precisar, incluindo as especulativas, e deixa o código decidir quais respostas usar

O exemplo da própria documentação é perguntar a categoria do ticket e a severidade do bug ao mesmo tempo, e simplesmente ignorar a severidade se o ticket não for bug

Traduzindo pro NPS: pergunta risco de churn, pedido de reembolso e área responsável pra TODO comentário, mesmo os elogios

Depois o teu código filtra

1. Respeite os dois limites de contexto

No Jev 1.13 são dois tetos: 64k cobrindo o state mais todas as perguntas juntas, e 32k para o state mais a pergunta mais longa

O erro comum deste passo: olhar só o total de 64k e esbarrar no segundo limite com uma pergunta gigante, cheia de exemplos colados dentro da instrução

2. Use o cliente assíncrono pra varrer o lote

O SDK Python traz o AsyncTypeSafeClient pra configurar requisições assíncronas à API

Como é um state por requisição, é ele que faz a planilha de 5 mil comentários terminar em tempo humano

O erro comum deste passo: soltar 5 mil requisições de uma vez sem limitar concorrência

3. Trate o 429 como parte normal do fluxo

Os limites de uso são medidos em tokens por segundo e requisições por minuto, e uma requisição acima de qualquer um dos dois recebe 429 Too Many Requests

Os SDKs fazem retry com backoff por padrão e respeitam o header retry-after quando ele vem na resposta

O erro comum deste passo: implementar um retry próprio agressivo por cima do retry do SDK, e transformar um pico momentâneo numa tempestade de requisições

Taxonomia de temas com mais de um nível

Um tempo depois de rodar, todo time quer detalhar mais

Não basta "Bug", quer saber se é bug de login, de pagamento ou de sincronização

E aí a Choice única começa a ficar apertada

A orientação da doc para taxonomia profunda é direta: faça uma Choice por nível e caminhe a árvore no código

Em cada passo, as opções são os filhos do nó atual e o valor de cada opção é a subárvore daquele filho

Então você pergunta o nível 1, pega a resposta, monta as opções do nível 2 com os filhos dela, pergunta de novo, e segue descendo

Tem um detalhe elegante aqui: escolher o vencedor guloso em cada nível pode te levar pro galho errado logo no primeiro passo

Por isso o cookbook de classificação hierárquica mostra como rodar um beam search sobre as probabilidades das Choices, mantendo os K melhores caminhos candidatos em cada nível em vez de fixar um só

É mais código, sim

Mas é o tipo de coisa que só dá pra fazer porque a saída vem com probabilidade por opção, e não como frase

O que dá pra fazer com a saída tipada

Lembra do problema do começo, de comentário que não soma?

Agora cada comentário virou: uma opção escolhida, um vetor de probabilidades, um score contínuo e alguns números entre 0 e 1

Isso é tabela

E tabela vira gráfico sem passar por parsing de texto solto

O que dá pra montar direto:

• Ranking de temas por volume, usando a opção de choice
• Ranking de temas por dor, ponderando volume pelo score de severidade
• Fila de atendimento urgente filtrando pelos Nouls de churn e reembolso acima de um corte que você define
• Recorte por área responsável, pra cada time ver só o que é dele
• Série temporal por semana, porque as colunas são as mesmas em toda leva

E isso conversa com os casos de uso que a TypeSafe documenta: classificar tickets por problema, área de produto e intenção do cliente, detectar urgência, frustração, risco de churn e pedido de reembolso, e rotear o caso para o time, fila ou fluxo certo

Tem ainda um caminho mais avançado pra quem já trabalha com modelo supervisionado

O cookbook de autoresearch mostra perguntas da TypeSafe virando features numéricas de um CatBoost treinado sobre texto livre, com um loop que propõe, avalia e descarta perguntas

Ou seja: as respostas do Jev deixam de ser o fim da linha e viram entrada de um modelo teu

Muito massa isso 😀

Como confiar no resultado antes de priorizar

Classificação automática sem checagem é jeito rápido de priorizar a roadmap errada

Então, antes de levar a tabela pra reunião, tem três coisas pra fazer

1. Use confiança e probabilidades como filtro de triagem

Choice devolve confiança da opção selecionada e probabilidade para cada opção

O que vier com confiança alta segue direto pro agregado, o resto entra numa fila de revisão humana

Não precisa revisar tudo, só a cauda duvidosa

O erro comum deste passo: definir o corte no chute e nunca mais olhar

Revise o corte depois de ver uma amostra revisada na mão

2. Meça estabilidade com self-consistency

O cookbook de consistência com Nouls faz exatamente isso: pega um sinistro de seguro de automóvel, roda uma rubrica de 14 perguntas sobre ele 15 vezes, e verifica se cada resposta se mantém estável entre as repetições

A ideia vale igual pro teu caso: escolhe uns comentários representativos, repete a rubrica e vê quais perguntas oscilam

Pergunta que oscila é pergunta mal escrita, quase sempre

O erro comum deste passo: rodar a repetição só nos casos fáceis e concluir que tá tudo redondo

3. Conheça as limitações registradas

A documentação de jaggedness do Jev 1.13 registra três pontos conhecidos: dificuldade com tarefas que exigem camadas extras de indireção, entendimento bastante literal, e dificuldade com tarefas que exigem precisão numérica

Traduzindo pro nosso contexto: pergunta indireta do tipo "o cliente está insinuando que o concorrente resolveu isso melhor?" tende a sofrer

Pergunta literal e específica tende a ir bem

4. Trate comentário de NPS como texto não confiável

Esse aqui é importante e pouca gente pensa nisso

Uma reportagem de segurança da VentureBeat aponta que empresas estão colocando o Jev pra decidir dentro de agentes, e que prompt injection no conteúdo avaliado pode influenciar o veredito

Comentário aberto de NPS é literalmente texto que qualquer pessoa digitou numa caixa

Se a saída da classificação dispara ação automática (reembolso, escalar pro time, abrir ticket prioritário), coloca revisão humana no meio

Tome cuidado! 😛

Vídeo: modelos de IA na prática

Pra começar do zero no assunto de modelos de IA, este vídeo do canal mostra o GPT-5.6 sendo usado na construção de vários sistemas

Conclusão

O fluxo inteiro cabe em três frases

Cada comentário vira um state, você manda Choice para tema e área, Score para severidade e Noul para churn e reembolso numa chamada só, e lê tudo de volta em result.choices, result.scores e result.nouls

Saída tipada, tabela pronta, gráfico no fim do dia

Meu conselho de próximo passo é não abrir editor de código ainda

Pega 10 comentários reais, cola no playground do console, escreve tuas perguntas ali e olha as probabilidades aparecendo

É nesses 10 que você descobre que dois temas da tua taxonomia são o mesmo tema, e isso te economiza horas depois

Sobre custo, o preço documentado é cobrado por token de entrada: US$ 0,042 por 1 milhão de tokens de entrada, com token de saída em US$ 0,00

Como cada comentário de NPS é curto, é essa conta que decide se você classifica uma amostra ou a base inteira

Até o próximo post!