jev-latest, jev-preview e por que fixar a versão

O campo model da requisição aceita dois tipos de nome: um alias, que é um apelido móvel, e um identificador com versão, que é fixo. A diferença parece administrativa e tem consequência direta em qualquer sistema que use limiares de confiança.

Os nomes de hoje

A documentação avisa que jev-preview aponta hoje para o mesmo modelo que jev-latest, porque não há build de prévia disponível no momento. Quando houver, ele passa à frente.

Nos SDKs, o padrão é jev-latest: é o valor da constante DEFAULT_MODEL no SDK Python, e o defaultModel do cliente de JavaScript, que você pode sobrescrever no construtor ou pela variável de ambiente TYPESAFE_DEFAULT_MODEL.

O que a resposta informa

Toda resposta traz o campo model com o identificador com versão que atendeu à chamada. Este é um detalhe pequeno e muito útil: mesmo pedindo um alias, você sabe exatamente o que respondeu.

{
  "model": "jev-1.13.0",
  "answers": { "is_urgent": { "type": "noul", "noul": 0.92 } },
  "usage": { "input_tokens": 312, "output_tokens": 48 }
}

Registre esse campo em todo log. Sem ele, uma variação de comportamento entre duas semanas vira discussão sem evidência. Com ele, é uma consulta.

Vale citar um exemplo de que isso não é teórico: o cookbook oficial de autoconsistência com Noul imprime, junto dos resultados, a contagem de versões que responderam durante a execução — pediu jev-latest e registrou jev-1.13.0 nas 15 chamadas. Quem escreveu o experimento achou importante o bastante para deixar no relatório.

Por que fixar a versão

A documentação é direta: um alias se move quando uma versão nova é lançada, então as respostas por trás dele podem mudar sem nenhuma mudança do seu lado. E acrescenta a recomendação: se você ajustou limiares de confiança contra uma versão específica, fixe o identificador daquela versão e mude para a nova no seu próprio ritmo.

O motivo é o que este guia repete em toda página de arquitetura. Um sistema com if confianca > 0.85 embutiu naquele número um comportamento observado. Se a distribuição do modelo muda, o número continua lá, com outro significado. A mecânica dos limiares está em roteamento por confiança e o conceito em confiança.

Note o efeito assimétrico: uma versão nova pode ser melhor em acurácia e ainda assim quebrar o seu corte, porque corte é calibração, não qualidade.

Quando o alias é a escolha certa

Fixar tem custo. Uma versão fixada eventualmente sai de cena, e aí a migração acontece na pior hora — por obrigação, e não por escolha.

O alias faz sentido quando:

• o sistema ainda está em desenvolvimento e não há limiar calibrado a proteger;
• as decisões não são automáticas, e uma pessoa revisa tudo;
• os cortes são conservadores o bastante para absorver variação pequena;
• você prefere melhoria automática a estabilidade, o que é uma escolha legítima em produto novo.

O desenho que resolve os dois lados

Fixe a versão em produção. Mantenha o alias em um ambiente de comparação.

Com os dois rodando, a migração deixa de ser um salto. Você monta um conjunto de casos com resposta conhecida — vinte já dizem muita coisa — roda nas duas versões e compara três coisas: quantas decisões mudaram, como a confiança média se moveu e se algum caso atravessou um dos seus cortes.

PRODUCAO = "jev-1.13.0"
CANDIDATO = "jev-latest"

for caso in casos_de_referencia:
    a = client.system_one(state=caso.state, questions=PERGUNTAS, model=PRODUCAO)
    b = client.system_one(state=caso.state, questions=PERGUNTAS, model=CANDIDATO)
    registrar_diferenca(caso.id, a.model, b.model, a.answers, b.answers)

Guardar a distribuição inteira de cada resposta, e não só o rótulo, é o que torna essa comparação útil: você vê o deslocamento antes que ele atravesse o limiar.

Listar o que a sua conta pode usar

curl -sS https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

A resposta traz um item por modelo ou alias, com nome, descrição e data de lançamento. A documentação observa dois detalhes: hoje a lista traz os aliases, e identificadores com versão como jev-1.13.0 são aceitos no campo model mesmo quando não aparecem na lista.

O que não muda entre versões

Vale registrar o que a documentação garante que não depende da versão: o Jev não é ajustado nem adaptado com dados de cliente, e os mesmos pesos servem todas as contas. Ou seja, a sua “personalização” vive no state e nos critérios, e ela atravessa a migração intacta. O assunto está em Jev vs fine-tuning.

Para a chamada crua onde o campo model aparece, veja a API HTTP sem SDK. O índice está em como usar.