Como usar o Jev para triar issues e bugs de um repositório

Fala aí, beleza? Se o seu repositório passou dos primeiros meses de vida, você já tem aquela pilha de issues com a label needs-triage que ninguém abre desde sempre

E o pior nem é o volume

É que a maior parte do trabalho ali é repetitivo: ler o título, bater o olho no corpo, decidir se é bug ou dúvida, chutar a área responsável, desconfiar que já tem uma issue igual aberta desde março…

A proposta aqui é tirar exatamente essa parte do caminho

A Jev é o modelo principal da TypeSafe AI e o primeiro que eles chamam de "System One model": ela avalia perguntas tipadas contra um state e devolve resultado estruturado que o software consome direto, sem gerar texto

Ou seja: nada de pedir JSON pra um chat e rezar pro parse não explodir 😛

Você pergunta "qual a severidade disso?" e recebe a resposta junto com a probabilidade de cada nível e um valor de confiança

Seu código decide o que fazer com isso

O que você precisa antes de começar

A lista é curta, beleza?

1) Uma conta. O cadastro é feito no console.typesafe.ai e não tem mais lista de espera, a TypeSafe anunciou que a Jev está disponível pra todo mundo. A conta começa com US$ 5 de crédito gratuito, algo em torno de 120 milhões de tokens

2) A chave na variável de ambiente. O cliente dos SDKs oficiais lê a TYPESAFE_API_KEY direto do ambiente

3) Escolher o SDK. Tem oficial pra Python e pra JavaScript/TypeScript

# Python (exige Python 3.10 ou superior)
pip install typesafe-sdk

# JavaScript / TypeScript (exige Node.js 20 ou mais novo)
npm install @typesafe-ai/sdk

export TYPESAFE_API_KEY="sua_chave_aqui"

Não quer SDK? Dá pra bater direto no endpoint de avaliação:

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Uma observação que vai te poupar dor de cabeça depois: o cliente dos SDKs chama jev-latest por padrão, e jev-latest é um alias móvel

Pré-inscrição Curso Jev

Domine o Jev e coloque decisões de IA dentro do seu sistema

Você vai aprender a usar o Jev, o System One Model da TypeSafe AI, pra automatizar decisões com resposta tipada e confiança medida, sem depender de chat nem de alguém revisando cada passo. Entre na lista de espera para garantir a condição de lançamento!

Quero minha vaga

Ele aponta pra release estável e muda quando sai versão nova, o que pode alterar as respostas

A versão corrente hoje é a Jev 1.13

Tome cuidado! Se a sua triagem for rodar em produção fechando issue sozinha, fixar a versão é decisão de engenharia, não frescura

Passo a passo: montando a triagem de issues com a Jev

Antes do código, o porquê: a Jev não sai buscando nada

Ela avalia o que você mandou no campo state, e só

Então a qualidade da triagem começa em COMO você monta esse state

1. Monte o state com a issue

O campo state aceita uma string simples pra texto ou dado estruturado (objeto/array) pra logs, registros e estado atual da aplicação

Pra triagem, estruturado é melhor: você separa título, corpo e labels, e ainda pendura as candidatas a duplicata no mesmo payload

state = {
    "issue": {
        "numero": 4821,
        "titulo": "App crasha ao salvar perfil com avatar grande",
        "corpo": "Ao subir um avatar acima de 5MB a tela congela e volta pro login. Acontece no Chrome e no Firefox.",
        "labels": ["needs-triage"],
    },
    "candidatas_duplicata": [
        {"numero": 4102, "titulo": "Upload de avatar falha silenciosamente", "status": "aberta"},
        {"numero": 3990, "titulo": "Erro 500 ao salvar perfil", "status": "fechada"},
    ],
}

O orçamento de contexto é de cerca de 64 mil tokens pro state somado a TODAS as perguntas, e cerca de 32 mil tokens pro state somado à pergunta isolada mais longa

Parece muito, mas issue com stack trace colada inteira come isso rapidinho

O erro comum deste passo: jogar o corpo cru da issue com 900 linhas de log dentro do state. Você estoura orçamento e ainda afoga o sinal no ruído

2. Desenhe a severidade como Score

Severidade é uma escala, e Score é exatamente isso: a resposta é uma posição ao longo dos níveis que você definiu, e ela PODE cair entre dois níveis

O modelo devolve probabilidade pra cada nível e confiança pra resposta

# desenho da pergunta (o envelope exato do request está na referência da API)
severidade = {
    "tipo": "Score",
    "pergunta": "Qual a severidade do defeito descrito no campo issue?",
    "niveis": [
        "cosmetico: aparencia, sem impacto de uso",
        "incomodo: da pra usar com contorno",
        "funcionalidade quebrada com contorno conhecido",
        "funcionalidade quebrada sem contorno",
        "perda de dados ou indisponibilidade total",
    ],
}

Repara que cada nível tem descrição, não só um nome

"Alta" e "média" não significam nada sozinhos

O erro comum deste passo: tratar a resposta como um inteiro. Se ela pode cair entre dois níveis, seu código precisa lidar com isso em vez de arredondar sem pensar

3. Desenhe a área responsável como Choice

Área é escolha fechada, então é Choice

A resposta é a opção selecionada, e junto vem a probabilidade de CADA opção mais a confiança da escolhida

Essa distribuição é ouro: dá pra ver quando a issue ficou empatada entre billing e auth

area = {
    "tipo": "Choice",
    "pergunta": "Qual time do repositorio e o dono mais provavel do codigo afetado pela issue?",
    "opcoes": [
        "frontend-web",
        "mobile",
        "api-core",
        "auth",
        "billing",
        "infra-deploy",
        "docs",
        "indefinido",
    ],
}

Um Choice aceita no máximo 255 opções, e cada opção adicionada custa alguns tokens

Teto alto, então o limite de verdade é o seu bom senso: lista de 60 microsserviços vira classificação ruim e conta mais cara

O erro comum deste passo: esquecer a saída de emergência. Sem uma opção tipo indefinido, o modelo é obrigado a escolher alguma coisa mesmo quando a issue não dá pista nenhuma

4. Desenhe "é duplicata?" como Noul

Noul é a resposta sim/não numa escala contínua de 0 (não) a 1 (sim)

Perfeito pra duplicata, porque duplicata quase nunca é preto no branco

duplicata = {
    "tipo": "Noul",
    "pergunta": "A issue descreve o mesmo defeito de alguma das candidatas_duplicata?",
}

E aqui vale lembrar: as candidatas precisam estar DENTRO do state

A Jev avalia o que você mandou, ela não vai vasculhar o histórico do repositório por conta própria

O erro comum deste passo: mandar 200 issues antigas como candidatas "pra garantir". Você paga contexto e ainda cai no problema de state grande com detalhe irrelevante. Faça um filtro barato antes (busca por texto, label, componente) e mande um punhado

5. Mande as três perguntas na mesma requisição

Esse é o pulo do gato

Cada pergunta é pontuada isoladamente contra o state, então a resposta de uma não depende das outras

Mandar N perguntas numa chamada dá o MESMO resultado que N chamadas separadas

Só que sai bem mais barato e mais rápido: no cookbook oficial de perguntas paralelas, rodar 13 perguntas de uma vez sobre um artigo longo saiu 12,2x mais barato e 10,0x mais rápido que perguntar uma por vez, com respostas idênticas

Faz sentido, né? O state só é processado uma vez

6. Leia confiança e probabilidade, e decida no SEU código

A Jev entrega o dado tipado

A regra de negócio é sua

É nesse ponto que a maioria das triagens automáticas dá errado, e é por isso que a próxima seção existe

O erro comum deste passo: esperar texto de volta. A Jev não gera texto, por design. Se você quer um comentário simpático explicando a decisão pro autor da issue, esse trabalho é de outro sistema (ou seu)

Como transformar confiança em ação dentro do fluxo do repositório

A documentação da TypeSafe recomenda dividir a confiança em três faixas com ações distintas:

• alta: agir automaticamente
• média: seguir com cautela, pedir confirmação, marcar pra revisão ou buscar mais contexto
• baixa: não agir, mandar pro humano, pedir esclarecimento ou cair em outro sistema

E tem um detalhe que muita gente ignora: o limiar NÃO é um número só

A própria doc afirma que ações diferentes dentro do mesmo sistema devem ser barradas em níveis diferentes, conforme a consequência do erro

Pensa no seu repositório:

Aplicar a label area/auth errado custa… nada. Alguém troca em dois cliques

Fechar uma issue legítima como duplicata custa um usuário que nunca mais volta a reportar bug pra você 😅

Mesma requisição, mesmo modelo, limiares completamente diferentes

A doc traz inclusive um exemplo usando 0,5 como corte pra não chutar e mandar pro humano

Na prática, o desenho fica mais ou menos assim:

• confiança alta na área: o bot aplica a label e atribui a fila do time
• confiança média: aplica a label mas mantém needs-triage e marca pra revisão
• confiança baixa: não encosta na issue, só empilha numa fila de triagem humana
• duplicata: só sugere no comentário, nunca fecha sozinho, a não ser que você tenha calibrado isso com calma

Essa mesma lógica de faixa de confiança aparece em qualquer fluxo tipado, seja moderação, seja quando você usa a Jev pra qualificar e priorizar leads num funil: o que muda é só a consequência do erro

Ah, e sobre robustez: os SDKs oficiais tratam retentativas automaticamente, com política de retry padrão

Uma preocupação a menos no webhook

Outras perguntas que vale plugar na mesma chamada

Já que as perguntas são independentes e pontuadas em paralelo contra o mesmo state, somar decisão no mesmo request é quase de graça em termos de arquitetura

Então por que parar em três? 😀

• Intenção: Choice entre bug, pedido de feature, dúvida de uso, problema de documentação
• Falta informação pra reproduzir? Noul. Se der perto de 1, o bot pede versão, SO e passos antes de qualquer humano gastar tempo
• É regressão? Noul, com a menção de versão no state
• Candidata a good first issue: Noul ou Score, pra alimentar o onboarding de contribuidor novo
• Esforço estimado: Score, com níveis descritos em horas ou tamanho de mudança

Isso conversa direto com o mapa oficial de casos de uso da TypeSafe, que cita classificar tickets recebidos por problema, área de produto e intenção e depois rotear pro time, fila ou workflow certo

O mesmo mapa cita casar entidades entre nomes, perfis e registros inconsistentes, e encaminhar os casos incertos pra revisão humana

É exatamente o formato da pergunta de duplicata: match com escape pro humano quando tá no meio do caminho

Se o seu produto também recebe conteúdo de usuário fora do repositório, a mesma mecânica serve pra moderar conteúdo enviado por usuários, trocando só o state e os enunciados

Onde a triagem automática quebra (e como prevenir)

Aqui é a parte que ninguém coloca no tutorial, e é a mais importante

A TypeSafe publica uma página de jaggedness da Jev 1.13 listando nove modos de falha conhecidos

Vou mapear cada um pro mundo real da triagem de issues:

Os três que mais pegam gente em triagem, na minha leitura:

Leitura literal. A doc é bem clara: a Jev responde a pergunta que você ESCREVEU, não a que você quis dizer. Palavras de escopo, negações e condições implícitas são lidas ao pé da letra. Então evita enunciado com negação dupla, tipo "isso não é uma issue que não pode ser fechada?". Já me ferrei com pergunta torta em outros contextos, e a correção é sempre a mesma: simplifica o enunciado

Invariantes estruturais. A documentação afirma que o modelo não garante que duas respostas fiquem consistentes entre si. Isso não é bug, é contrato. Se a sua regra diz que "dúvida de uso" nunca pode ter severidade máxima, essa regra mora no seu código, com teste e tudo

State grande com ruído. Contexto sobrando não é contexto bom. Antes de montar o state, pergunte o que ali de fato ajuda a decidir severidade e área

O que continua sendo trabalho humano

A fronteira é bem nítida: a Jev DECIDE, ela não redige

Ela não gera código, não escreve e-mail, não produz resumo e não explica conceito em linguagem natural

Ou seja, continuam humanos (ou de outro sistema):

• escrever o comentário pedindo os passos de reprodução
• descrever a causa raiz depois de investigar
• confirmar duplicata nos casos genuinamente duvidosos
• priorização de roadmap, que é decisão de produto e não classificação
• a conversa com quem abriu o chamado, que é onde mora a boa vontade do contribuidor

O que a Jev tira do caminho é a classificação repetitiva: severidade, área, intenção, falta de informação, suspeita de duplicata

E sobre rodar isso no backlog inteiro: o preço da Jev é US$ 0,042 por milhão de tokens de entrada, com tokens de saída a US$ 0,00

Com os US$ 5 de crédito inicial (cerca de 120 milhões de tokens) dá pra fazer um estudo sério antes de colocar cartão

Não vou estimar custo por issue aqui porque isso depende inteiramente do tamanho do seu state, e chutar número é o tipo de coisa que eu acho zoado fazer

Mede no seu repositório, com as suas issues

Próximo passo

Começa pequeno e em modo sombra

Pega 200 issues que o time já triou manualmente, roda as três perguntas contra elas e compara a saída da Jev com o rótulo humano

Olha onde bate, onde erra e, principalmente, QUAL era a confiança quando errou

É esse número que vai te dizer onde cortar cada ação, porque o limiar é por ação e não um valor único pro sistema todo

Só depois disso você liga a automação, e liga pela ponta mais barata: label primeiro, fechamento de duplicata muito depois (ou nunca automático, dependendo da sua comunidade)

E não esquece de fixar a versão do modelo quando a estabilidade importar, porque jev-latest é alias móvel e muda de baixo de você

Triagem chata resolvida, cabeça livre pro que interessa 😀

até o próximo post!