Como evoluir uma rubrica de Score do Jev sem invalidar o que você já pontuou

Mudar um nível da rubrica muda o significado de todo score que você já gravou, mesmo que a string de versão continue igualzinha

Fala aí, beleza? Se você já tem um histórico pontuado pelo Score do Jev (o modelo System One da TypeSafe AI) e agora bateu aquela vontade de ajustar a definição dos níveis, esse post é pra você 🙂

O problema é simples de explicar e chato de resolver: a rubrica nova pode ser MUITO melhor, só que os números antigos foram gerados na régua velha

Aí vem a dúvida clássica: dá pra comparar? Tem que repontuar tudo? Joga fora?

Bora ver na prática as três decisões que resolvem isso: quando versionar, quando repontuar a base e como comparar séries de períodos diferentes

Curso Recomendado

Curso de Jev: Sistemas Mais Inteligentes, Rápidos e Robustos

Desenvolva sistemas mais inteligentes, rápidos e robustos com Jev

Conhecer curso

O que você precisa antes de mexer na rubrica?

Antes de encostar em qualquer nível, confere se tu tem isso aqui na mão:

• Acesso ao Jev pelo OpenRouter ou pelo Vercel AI Gateway
• Uma rubrica de Score já em uso, com entre 2 e 10 níveis
• O texto ou o estado estruturado original de cada item avaliado, guardado (sem ele não tem como repontuar nada)
• Um lugar pra gravar a versão da rubrica, o hash e o ID do modelo junto de cada resultado

E o que o Score devolve, afinal?

Ele avalia o estado contra os níveis ordenados da rubrica e devolve três coisas: um valor ponderado por probabilidade, a distribuição completa entre os níveis e uma confiança de 0 a 1

Se liga nisso: guarde a distribuição inteira, não só o número final

Com a distribuição salva, você consegue entender depois POR QUE um score deu aquilo, e comparar períodos fica bem menos no escuro

Passo a passo para evoluir a rubrica sem quebrar o histórico:

A ideia aqui é que a próxima mudança já nasça rastreável, e que nada do que você pontuou antes vire lixo

1. Congele o modelo no ID versionado

Troque jev-latest pelo ID versionado jev-1.13.0 no campo model do SDK ou do corpo da requisição

Em 2026-09-25, os aliases jev-latest e jev-preview apontavam para jev-1.13.0, listado como o modelo estável atual

{
  "model": "jev-1.13.0"
}

Erro comum deste passo: calibrar a rubrica contra o alias

O alias muda quando sai versão nova, e as respostas por trás dele podem mudar sem você alterar uma vírgula do seu lado

Aí você edita a rubrica, o score muda, e não dá pra saber se foi culpa da sua edição ou do modelo novo…

2. Carimbe cada avaliação com versão e hash da rubrica

Esse é o passo que salva o histórico

Não é recurso nativo do Jev: é uma prática da aplicação, e tem um caso real num projeto open source que passou a gravar a versão da rubrica (tipo [email protected]) e o hash em cada registro

Um registro de exemplo ficaria assim:

{
  "item_id": "cand-0142",
  "model": "jev-1.13.0",
  "rubric_version": "[email protected]",
  "rubric_hash": "sha256:<hash do texto dos níveis>",
  "score": 0.75,
  "distribution": [0.1, 0.3, 0.6],
  "confidence": "<valor devolvido pelo Jev>"
}

O hash sai do texto dos níveis, do jeito que foi enviado. Em Python, algo assim resolve:

import hashlib
import json

niveis = [
    "Nenhuma evidência no texto",
    "Evidência indireta, sem resultado citado",
    "Evidência direta com resultado citado",
]

texto = json.dumps(niveis, ensure_ascii=False, sort_keys=True)
rubric_hash = "sha256:" + hashlib.sha256(texto.encode("utf-8")).hexdigest()

Erro comum deste passo: confiar só na string de versão

Editar o texto de um nível pode mudar os scores mesmo com a versão igual, e o hash é justamente o que denuncia isso

Já vi muita gente esquecer de subir a versão depois de um ajuste "rapidinho", então deixa o hash fazer esse trabalho por você 😛

3. Classifique a mudança antes de publicar

Nem toda edição é igual

A TypeSafe AI recomenda definir os níveis como situações concretas e observáveis (a evidência que você vê e a ação que aquele nível influencia), e não com adjetivos vagos como baixo, médio e alto

Se você está trocando "médio" por "evidência indireta, sem resultado citado", você mudou o CRITÉRIO, não só a redação

Erro comum deste passo: tratar isso como correção de texto

Quando o critério muda, é rubrica nova: versão nova, hash novo, e nada de misturar com os números antigos como se fosse a mesma coisa

4. Respeite os limites de níveis

O Score aceita entre 2 e 10 níveis

Um 11º nível retorna erro 400 da API, e escalas maiores precisam ser feitas como Choice

Erro comum deste passo: descobrir o limite em produção

Se a evolução da rubrica passa por "vamos detalhar mais", conta os níveis antes de subir, porque a API não vai te avisar com carinho haha

5. Decida entre versionar e repontuar

Os registros antigos continuam válidos sob a versão e o hash deles

Ou seja: versionar é o padrão, e repontuar só entra quando a análise exige uma série contínua medida na régua nova

Pra estimar o custo de repontuar, a conta é em cima dos tokens de entrada: no OpenRouter o Jev custa US$ 0,042 por milhão de tokens de entrada, e a saída é grátis

Soma o tamanho dos textos ou estados guardados, mais a rubrica e a pergunta de cada chamada, e tu tem uma estimativa honesta antes de rodar

Erro comum deste passo: sobrescrever o score antigo

Grave o score novo AO LADO do antigo, cada um com a sua versão e o seu hash

Sobrescrever é o rm -rf do histórico: some a prova do que foi decidido com a régua anterior

6. Compare séries de períodos diferentes do jeito certo

Aqui mora a pegadinha

O score é a média das posições dos níveis ponderada pelas probabilidades, então ele pode cair entre dois níveis

Por convenção, uma rubrica de três níveis fica em 0, 0,5 e 1, e com probabilidades 0,1 / 0,3 / 0,6 a posição dá 0,75

Agora pensa: se você muda a quantidade de níveis, muda também o que cada posição da régua representa, e o mesmo número deixa de significar a mesma coisa

Então tu tem dois caminhos:

• Comparar só dentro da mesma versão (e do mesmo hash)
• Repontuar uma amostra do período antigo na rubrica nova, pra criar uma ponte entre as duas séries

Na amostra ponte, olhe também a confiança: ela mede o quanto a distribuição está concentrada, de 0 a 1, e uma queda forte na régua nova é sinal de que algum nível ficou ambíguo

Erro comum deste passo: plotar numa linha só scores de rubricas com número de níveis diferente

O gráfico fica lindo e a conclusão fica errada 😀

Quando versionar basta e quando repontuar a base compensa?

Resumindo em cenário concreto, que é onde a dúvida aparece de verdade:

Dashboard que só olha o período atual: versionar basta

Se a tela mostra só os itens do mês e ninguém compara com trimestre passado, a régua antiga não atrapalha

Carimba versão e hash, segue a vida, e repontuar aqui é gastar à toa

Relatório de tendência de vários trimestres: repontuar compensa

Tendência só faz sentido se todos os pontos foram medidos com a mesma régua

Repontue a base inteira ou, no mínimo, uma amostra ponte do período antigo pra saber como os números se deslocam

Troca de agente, prompt ou de quem chama o Jev: recalibrar

Um limiar que funcionava no trimestre passado pode não funcionar hoje

A recomendação é monitorar o drift e recalibrar os limiares sempre que o agente, os prompts ou quem chama o Jev mudam, mesmo sem ter mexido na rubrica

Escala que precisa passar de 10 níveis: virou outra coisa

O Score aceita no máximo 10 níveis, e um 11º nível na rubrica retorna erro 400 da API

Ou seja: se a sua escala precisa ser maior que isso, ela tem que ser feita como Choice

Isso muda o tipo de pergunta e o formato da resposta, então trate como série nova desde o primeiro dia

Vídeo: uma introdução ao assunto

Pra começar do zero, este vídeo do canal mostra uma IA que te mostra tudo que você fez nos últimos 30 dias, bem na pegada de usar IA pra olhar pro próprio histórico 🙂

Próximo passo: carimbe versão e hash antes da próxima edição

Fixe o modelo no ID versionado, pra que o score não mude por baixo dos panos

Carimbe versão e hash da rubrica em cada avaliação, porque a string de versão sozinha não segura edição de nível

E compare só dentro da mesma régua, ou com uma amostra ponte quando a série precisa atravessar versões

O próximo passo é bem prático: antes de editar QUALQUER nível, adiciona versão e hash no registro atual e congela o jev-1.13.0

Assim a próxima mudança da rubrica do Jev Score já nasce rastreável, e o seu histórico continua valendo alguma coisa =)

Até o próximo post!