Como usar o Jev para classificar commits e decidir o próximo bump de versão?

Fala aí, beleza? Versionar direito parece simples até você olhar o histórico do repositório e ver fix: ajustes, wip, agora vai e um commit que quebrou a API pública escondido no meio

Toda automação de release moderna depende de uma coisa só: o time escrever a mensagem no padrão

E sempre tem alguém que esquece 😅

O Jev ataca esse problema por outro lado. Ele é o modelo System One da TypeSafe AI: em vez de gerar texto, devolve um valor tipado com probabilidades e confiança, feito pra ser consumido por código e não lido por uma pessoa

Ou seja: você não pede pro modelo "escrever" qual é o bump, você pergunta e recebe uma opção de um conjunto que VOCÊ definiu

Neste post a gente monta isso na prática: mensagem de commit + resumo do diff entram, tipo de mudança e sugestão de bump saem, e a decisão fica registrada no changelog de um jeito que dá pra auditar depois

Bora?

O que você precisa antes de começar

A lista é curtinha:

• Conta na TypeSafe, criada no console em console.typesafe.ai. Contas novas recebem US$ 5 em crédito pra começar
• A chave de API na variável de ambiente TYPESAFE_API_KEY (é dela que o cliente lê por padrão)
• Python 3.10 ou superior
• O SDK oficial instalado

Detalhe que vale saber antes: o Jev saiu em early access com waitlist em 15 de setembro de 2026, junto com uma rodada seed de US$ 40 milhões liderada pela DCVC

Mas isso mudou rápido. Desde 20 de setembro de 2026 a waitlist foi removida e o Jev está disponível pra qualquer pessoa

Sobre custo, é bom você já entrar com o número na cabeça: US$ 0,042 por milhão de tokens de entrada, e os tokens de saída não são cobrados. Faz sentido pro tipo de resposta que ele dá, que é um valor tipado e não um textão

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

Qual ID de modelo usar:

A versão atual é a jev-1.13.0, com os aliases jev-latest (padrão do SDK) e jev-preview

O jev-latest resolve pra jev-1.13.0 hoje, e vai mudar quando sair release nova

Guarde isso, porque na hora de auditar o changelog isso volta a aparecer 😉

A janela de contexto define quanto de diff cabe:

A janela listada pro Jev 1.13 é de 32.000 tokens

Isso não é detalhe burocrático, é regra de projeto do seu script: diff gigante não entra inteiro, tu vai precisar resumir

Passo a passo: classificar o commit e obter o bump sugerido

1. Instale o SDK e configure a chave

pip install typesafe-sdk
# ou, se tu usa uv:
uv add typesafe-sdk

export TYPESAFE_API_KEY="sua-chave-aqui"

O erro comum deste passo: chumbar a chave no script e subir pro repositório. O cliente lê TYPESAFE_API_KEY do ambiente justamente pra tu não precisar fazer isso

2. Monte o state com a mensagem do commit e um resumo do diff

O state é o contexto que o modelo vai avaliar. No nosso caso, é a mensagem somada a um resumo do que mudou: arquivos tocados, funções ou assinaturas alteradas, o que foi removido

import subprocess

mensagem = subprocess.run(
    ["git", "log", "-1", "--pretty=%B"],
    capture_output=True, text=True
).stdout.strip()

resumo_diff = subprocess.run(
    ["git", "show", "--stat", "--unified=3", "HEAD"],
    capture_output=True, text=True
).stdout[:20000]

state = f"""Mensagem do commit:
{mensagem}

Resumo do diff:
{resumo_diff}
"""

O erro comum deste passo: colar o diff inteiro de um commit de refactor gigante e estourar os 32.000 tokens de contexto. Corte por tamanho, priorize arquivo de API pública e interface, e deixe lock file e asset de fora

3. Defina a pergunta Choice com criteria explícito

Uma pergunta Choice é montada com instructions (a pergunta em si) e criteria (o dicionário de opções, cada uma com sua descrição). O Choice aceita até 255 opções, mas aqui a gente só precisa de três

A descrição de cada opção segue a regra clássica do SemVer:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()

bump = Choice(
    instructions=(
        "Classifique este commit e indique qual incremento de versão "
        "semântica ele exige no pacote publicado."
    ),
    criteria={
        "major": "Remove ou altera comportamento existente: assinatura pública mudou, endpoint removido, retorno diferente, qualquer quebra de compatibilidade",
        "minor": "Adiciona comportamento novo mantendo compatibilidade: função, parâmetro opcional, endpoint novo",
        "patch": "Corrige um bug, ajuste interno, sem mudar contrato público nem adicionar comportamento novo",
    },
)

O erro comum deste passo: escrever criteria vago tipo "major": "mudança grande". Vago é onde a classificação escorrega. Descreva o critério do jeito que tu explicaria pro dev novo do time

4. Chame o system_one e leia a resposta tipada

A requisição do System One exige model, state e questions, e a resposta vem com model, answers e usage

resposta = client.system_one(
    state=state,
    questions={"bump": bump},
)

O modelo padrão do SDK é o jev-latest. Se tu quiser comportamento estável ao longo do tempo, aponta pro ID versionado jev-1.13.0 em vez do alias

A resposta de um Choice traz três coisas que interessam: a opção escolhida, uma probabilidade pra cada opção (que somam 1) e um valor de confidence de 0 a 1

E tem uma garantia que muda tudo na hora de escrever o código que consome: o modelo nunca devolve valor fora das opções declaradas. Não vai chegar "maior", "MAJOR?" nem um parágrafo explicando. É major, minor ou patch

O erro comum deste passo: assumir de cabeça o nome do atributo de leitura no Python. Confira na documentação do SDK da versão que você instalou como acessar o objeto de respostas, porque é ali que mora o answers

5. Aplique limiar de confiança antes de agir

A confiança é derivada da forma da distribuição de probabilidade, e a documentação orienta justamente usar limiar: agir no alto, revisar o meio, escalar o baixo pra humano

LIMIAR_ALTO = 0.85
LIMIAR_MEIO = 0.6

def decidir(escolha, confianca):
    if confianca >= LIMIAR_ALTO:
        return ("aplicar", escolha)
    if confianca >= LIMIAR_MEIO:
        return ("revisar", escolha)
    return ("humano", escolha)

E aproveita pra ler o usage da resposta, que é o que te dá a conta real de tokens consumidos por commit

O erro comum deste passo: tratar confidence como prova de que a resposta está certa. A própria documentação deixa explícito que confiança não é garantia de correção factual. Ela te diz o quanto a distribuição está concentrada, não que o mundo concorda com ela

Tome cuidado! Confiança alta em major ainda merece olho humano, porque é o bump que quebra o build de quem depende de você

Como enriquecer a mesma chamada com mais perguntas tipadas

Aqui vem a parte massa do System One: dá pra fazer VÁRIAS perguntas sobre o mesmo state numa única requisição

O modelo avalia todas em paralelo e isoladamente, então acrescentar pergunta quase não muda o tempo de resposta. E a latência ponta a ponta reportada pra ele é de 70 a 500 milissegundos

Ou seja: o mesmo commit que você já mandou pra decidir o bump pode responder mais três perguntas de graça em termos de tempo (em tokens de entrada, claro, você paga pelo state que enviou)

1. Some um Noul pra marcar correção de segurança

O Noul é a pergunta sim ou não com probabilidade calibrada. Perfeito pra flag binária de changelog

2. Some um Score pra estimar risco

O Score dá uma nota contra níveis ordenados, e serve bem pra priorizar o que o revisor olha primeiro

seguranca = Noul(
    instructions="Este commit corrige uma falha de segurança?",
)

risco = Score(
    instructions="Qual o risco de regressão deste commit em produção?",
)

resposta = client.system_one(
    state=state,
    questions={
        "bump": bump,
        "seguranca": seguranca,
        "risco": risco,
    },
)

3. Use cada resposta em um campo diferente do changelog

O bump vira a versão, o Noul vira a seção de segurança, o Score vira a ordem de revisão

O erro comum deste passo: juntar tudo numa pergunta só, tipo "classifique o bump e diga se é segurança e qual o risco". Isso devolve a ambiguidade que você estava tentando eliminar. Pergunta independente é pergunta separada, e o modelo já foi feito pra avaliar em paralelo mesmo

Esse padrão de "um state, várias perguntas tipadas" é o mesmo que aparece quando você usa o Jev pra qualificar leads no funil: muda o contexto, a mecânica é idêntica

Onde isso encaixa no fluxo do time

Pipeline de release que não depende de convenção:

Ferramentas como o semantic-release automatizam bump de versão e geração de changelog muito bem, com uma condição: o time precisa seguir a convenção de mensagens de commit

Quando a adesão é parcial, a automação herda o buraco

A classificação tipada muda o insumo: a decisão passa a olhar o que o commit FEZ (o diff) e não só como ele foi descrito

Triagem de histórico legado:

Repositório com dois anos de update e fix stuff é onde isso brilha. Tu roda a classificação em lote pra cima do histórico e finalmente consegue montar um changelog retroativo que faz sentido

Marcação de correções de segurança:

O commit-miner, mantido por devanshbatham no GitHub, é um CLI que já faz exatamente isso: classifica mensagens e diffs de commits do Git com o Jev, marcando bug fixes, correções de segurança/CWEs e tipos de mudança

Um aviso que evita dor de cabeça: existe um fork (r0075h3ll) cujo PR trocou o backend de classificação de TypeSafe/Jev pra OpenRouter

Então nem todo repositório com esse nome roda em Jev. Confere o backend antes de assumir 👀

Outras formas de acesso:

O Jev também está no catálogo do Cloudflare Workers AI como typesafe/jev, e o Pydantic AI documenta suporte ao provedor TypeSafe

Se o teu pipeline já vive em um desses lugares, dá pra plugar sem reescrever a casa toda

E se a ideia de classificação tipada te pegou, o mesmo desenho serve pra moderar conteúdo enviado por usuários, que é outro caso onde "o modelo devolve texto" sempre foi o ponto fraco

Como deixar a decisão auditável no changelog

Essa é a parte que separa "IA decidiu" de "decisão registrada"

Daqui a seis meses alguém vai perguntar por que a 3.0.0 foi lançada. Tu precisa ter a resposta pronta

1. Grave a opção escolhida junto com a distribuição completa

Não salve só major. Salve a probabilidade de cada opção, porque major 0.51 / minor 0.49 conta uma história bem diferente de major 0.97

2. Grave o valor de confiança e o limiar que estava valendo

O limiar é decisão do time e ele muda com o tempo. Sem ele registrado, a auditoria não consegue reconstruir o porquê

3. Grave o ID de modelo usado, versionado

Aqui o alias te trai: jev-latest resolve pra jev-1.13.0 hoje e muda quando sai release nova

Se o teu artefato de release diz só "jev-latest", daqui a três meses ninguém sabe qual modelo decidiu aquilo

Por isso vale fixar o ID versionado quando reprodutibilidade importa, e registrar exatamente qual foi

4. Grave o state que gerou a decisão (ou o hash dele)

Mesmo modelo + mesmo state é a única forma de alguém reproduzir o raciocínio depois. Se o state for grande demais pra guardar inteiro, guarda o hash e o SHA do commit

5. Exija revisão humana no major

Confiança alta não substitui revisão quando a consequência é quebrar o código de quem depende do teu pacote

Deixa o minor e o patch fluírem automáticos, segura o major num gate

Um exemplo de registro mínimo no artefato de release:

{
  "commit": "a3f91c2",
  "bump": "minor",
  "probabilities": {"major": 0.04, "minor": 0.91, "patch": 0.05},
  "confidence": 0.88,
  "threshold": 0.85,
  "model": "jev-1.13.0",
  "state_sha256": "9c1d...",
  "revisado_por": "automatico"
}

O erro comum deste passo: registrar só o resultado final no CHANGELOG.md bonitinho e jogar fora os números. O valor tipado existe justamente pra ser guardado, filtrado e comparado depois

Um vídeo pra contextualizar o momento dos modelos

Pra quem tá chegando agora nesse movimento todo de lançamento de modelo, esse vídeo do canal fala sobre o Sonnet 5 e a nova versão do modelo da Anthropic

Conclusão

O ganho aqui não é "IA no pipeline", é decisão de versão em formato tipado

O Jev te devolve uma opção do conjunto que você declarou, com probabilidade pra cada uma e confiança de 0 a 1, e nunca inventa um valor fora dessa lista

Isso significa código que consome sem parser, sem regex e sem rezar pra mensagem de commit estar no padrão 😄

E, com tokens de saída não cobrados e US$ 0,042 por milhão de tokens de entrada, classificar o histórico inteiro do repositório sai bem diferente de rodar um modelo de texto pra cada commit

Próximo passo prático: cria a conta no console, usa os US$ 5 de crédito pra rodar essa classificação nos últimos commits do teu repositório e compara o resultado com o bump que o time aplicou na mão

A parte mais interessante do teste costuma ser onde os dois discordam…

Até o próximo post!