Tutorial TypeSafe Jev passo a passo. Guia prático do TypeSafe Jev, o modelo de IA System One para decisões tipadas de software.
01
Enquadre a tarefa
Decida se Jev se encaixa
Jev não é um modelo de bate-papo. Ele transforma o estado existente em uma decisão fechada de Escolha, Pontuação ou Noul e retorna uma distribuição de probabilidade.
Um bom ajuste
Use Jev para decisões limitadas
Roteie uma solicitação para uma fila nomeada.
Coloque um registro em uma escala ordenada de risco ou qualidade.
Estime se uma condição claramente declarada é verdadeira.
Não é um bom ajuste
Use um modelo generativo
Escreva, resuma, traduza ou reescreva textos abertos.
Mantenha uma conversa natural em várias voltas.
Crie uma resposta quando as saídas válidas não puderem ser nomeadas antecipadamente.
O modelo mental oficial
STATE
Um estado para avaliar
Passe uma string, objeto ou array contendo o texto e os fatos relacionados que o julgamento precisa. Use campos de objetos nomeados para a maioria das solicitações reais.
QUESTIONS
Um julgamento instantâneo por pergunta
Cada pergunta deve perguntar algo específico que uma pessoa experiente possa julgar rapidamente a partir do estado fornecido.
PARALLEL
Perguntas independentes em paralelo
As perguntas em uma solicitação têm o mesmo estado, são executadas de forma independente e não vazam uma resposta para outra.
CODE
Componha respostas em código
Pondere, limite, ramifique e combine respostas digitadas em código comum, em vez de ocultar a lógica do fluxo de trabalho em um prompt.
Teste de decomposição: Se o julgamento pesar vários fatores independentes ou exigir um raciocínio extenso, divida-o em questões atômicas e combine as respostas em código.
Depois deste capítulo:Você pode separar tarefas de geração de conteúdo de tarefas de decisão estruturada.
Use Choice para rótulos mutuamente exclusivos, Score para níveis ordenados e Noul para um julgamento de verdadeiro ou falso.
Tipo
Você fornece
Você recebe
Usar quando
choice
Opções nomeadas → descrições
Chave selecionada + probabilidades por opção (+ confiança)
Rótulos/rotas mutuamente exclusivas
score
Níveis ordenados (2–10), baixo → alto
Pontuação de nível ponderada por probabilidade + problemas de degrau
Gravidade, qualidade, rubricas de risco
noul
Proposição sim/não (+ critérios opcionais)
Probabilidade de verdadeiro
Verificações de fatos únicos
choiceAté 255 opções
Um vencedor mais a distribuição completa
Use para alternativas fixas e não ordenadas. Adicione outro/nenhum quando a lista não cobrir todos os estados. O valor escolhido é a opção de maior probabilidade.
Use para um julgamento claro de sim/não. Perto de 0,5 significa incerteza, não uma quantidade média da propriedade. Noul não tem um campo de confiança separado.
{
"type": "noul",
"noul": 0.95
}
Pontuação não é precisão. Uma pontuação de 1,5 em uma rubrica de 0–2 é um nível esperado, e não “75% correto”. Não trate a confiança na pontuação ou na escolha como uma promessa de precisão.
Depois deste capítulo:Você pode selecionar o formato de resposta correto para roteamento, moderação e pontuação de risco.
Mantenha os nomes das opções estáveis, defina limites mutuamente exclusivos, inclua um caminho residual e dê a cada questão uma decisão.
Escrevendo critérios fortes
Opções disjuntas. Se duas chaves de escolha puderem ser verdadeiras, os operadores lutarão contra o modelo.
Descreva as arestas. Diga o que buy_intent inclui (estoque, envio) versus price_question.
Mantenha o resíduo por último. Use outro/humano como saída de emergência, não como pega-tudo preguiçoso.
Pontuação do pedido crescente. As matrizes de critérios são mais baixas → mais altas.
Uma decisão por pergunta. Divida “rota” de “urgência” em chaves separadas.
Anatomia de uma pergunta
question_id
Uma chave de pesquisa de resposta para o seu código. Ela não é enviada para o modelo, portanto as instruções ainda devem conter a pergunta completa.
type
escolha, pontuação ou noul. Escolha a forma na qual seu código pode atuar diretamente.
instructions
O julgamento completo e específico. Pode ser uma string, um objeto ou uma matriz e pode fazer referência a caminhos de estado nomeados.
criteria
Opções de escolha, níveis de pontuação ordenados ou esclarecimento opcional de verdadeiro/falso para Noul.
Exemplo · uma decisão, limites disjuntos
route: {
type: 'choice',
instructions: 'Route this ticket to one queue.',
criteria: {
tech: 'Bugs, outages, API failures, or integrations',
sales: 'Pricing, plans, demos, or new-purchase intent',
billing: 'Charges, invoices, receipts, or subscriptions',
human: 'Ambiguous, sensitive, legal, or multi-issue'
}
}
Estado da estrutura e campos exatos de referência
Mantenha as evidências em campos de estado nomeados e aponte instruções para eles com caminhos de ponto e índice. Isto reduz a ambiguidade sobre qual texto, registro ou política deve controlar a resposta.
const state = {
ticket: {
message: 'I was charged twice. Please refund the duplicate.',
orderId: 'A-104'
},
order: { charges: [49, 49] },
refundPolicy: 'Duplicate charges are eligible for a refund.'
};
const questions = {
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request a refund?'
},
policy_supports_refund: {
type: 'noul',
instructions: 'Does `refundPolicy` support the request given `order.charges`?'
}
};
Lote por padrão: Faça todas as perguntas que usam o mesmo estado em uma única solicitação, até mesmo perguntas especulativas. Faça uma segunda solicitação somente quando seu estado ou opções realmente dependerem de uma resposta anterior.
Depois deste capítulo:Você pode escrever uma definição de pergunta estável e testável que o código possa consumir.
Chame o endpoint ou SDK oficial do System One do seu servidor, inspecione a resposta digitada e lide com erros de validação, limite de taxa e sobrecarga. O gateway continua sendo um caminho de acesso opcional.
Comece com o endpoint HTTP oficial
Mantenha TYPESAFE_API_KEY no servidor. Envie estado, modelo e um mapa de perguntas nomeadas para POST /v1/systemone.
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Stripe has failed for 3 days. I am losing sales.",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"is_urgent": {
"type": "noul",
"instructions": "Does this message convey urgency?"
}
}
}'
Use o SDK oficial para respostas digitadas e novas tentativas
O Python SDK lê TYPESAFE_API_KEY do ambiente, o padrão é jev-latest, expõe classes de perguntas/respostas digitadas e aplica sua política de repetição padrão.
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"message": "Stripe has failed for 3 days.", "impact": "Losing sales"},
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"is_urgent": Noul(
instructions="Does `message` and `impact` convey urgency?"
),
},
)
department = response.answers["department"]
print(department.choice, department.confidence)
print(response.answers["is_urgent"].noul)
Chave de API ausente ou inválida. Verifique o token do portador.
422
Formato de solicitação inválido. Inspecione a resposta para o campo incorreto.
429
Limite de taxa excedido. Afaste-se antes de tentar novamente.
529
Serviço temporariamente sobrecarregado. Afaste-se antes de tentar novamente.
Para 429 e 529, use espera exponencial em vez de nova tentativa imediata. Os SDKs oficiais fazem isso automaticamente de acordo com sua política de repetição padrão.
Alternativa: Vercel AI Gateway
Este site também documenta o Gateway como uma camada de acesso para avaliação do AI SDK. É um caminho de integração alternativo, que não faz parte do Jev ou do TypeSafe.
import { experimental_evaluate as evaluate } from 'ai';
import { gateway } from '@ai-sdk/gateway';
const result = await evaluate({
model: gateway('typesafe-ai/jev'),
state,
questions,
});
Depois deste capítulo:Você pode manter as credenciais do servidor e receber respostas digitadas com probabilidades.
Não transforme a probabilidade máxima diretamente em uma ação final. Defina faixas para sugestão, confirmação e revisão humana com base no risco do negócio.
PROBABILITY
Evidência para cada opção ou nível
Choice e Score retornam a distribuição completa. Use-o quando opções de segundo colocado, ambiguidade ou medidas de incerteza personalizadas forem importantes.
CONFIDENCE
Um resumo da forma de distribuição
A confiança comprime o quão concentrada ou plana é a distribuição em 0–1. Não é igual à probabilidade da opção selecionada.
Noul: Noul já retorna P(true), portanto não tem confiança separada. Valores próximos de 0,5 são incertos; limite o lado sim e o não de acordo com o risco.
TypeSafe expõe a confiança da distribuição de opções. Uma política prática é:
01
Alta confiança
Sugira automaticamente a escolha (tag, rota ou veredicto) em sua IU.
02
Confiança média
Mostre a sugestão, mas solicite que um operador a confirme antes de continuar.
03
Baixa confiança
Envie para uma fila humana sem ação padrão.
Calibre os limites em exemplos rotulados do seu stream ou caixa de entrada. Os limites são específicos do caso de uso. Nunca transfira sugestões para dinheiro ou devolva efeitos colaterais.
Limite a ação, não o modelo globalmente
action = response.answers["action"]
if action.confidence < 0.5:
route_to_human(state) # uncertain: do not guess
elif action.choice == "check_balance":
show_balance(account_id) # reversible, low stakes
elif action.choice == "approve_transfer":
if action.confidence > 0.9:
confirm_then_execute(account_id)
else:
ask_user_to_confirm(account_id) # higher stakes, higher bar
Calibrar antes da automação
Colete exemplos representativos e rotulados do fluxo de trabalho real.
Registre respostas, distribuições, confiança, latência e a decisão humana.
Escolha limites separadamente para ações reversíveis, dispendiosas e irreversíveis.
Monitore o desvio e reavalie após alterar o estado, as instruções, os critérios ou o alias do modelo.
Dicas estaduais
Passe uma string, objeto ou array como estado. Prefira registros estruturados (texto de comentário + metadados) a descartar um log de bate-papo inteiro quando apenas uma mensagem importa.
Depois deste capítulo:Você pode projetar um substituto de baixa confiança e calibrar limites com dados rotulados.
Crie um fluxo de trabalho completo com estado estruturado, perguntas paralelas, política de propriedade do código, evidências de auditoria, novas tentativas e um substituto humano.
Crie um fluxo de trabalho completo de triagem de suporte
Envie um estado de ticket estruturado e faça três perguntas independentes em paralelo. Mantenha o roteamento e a política de segurança no código.
STATE→CHOICESCORENOUL→POLICY
const questions = {
department: {
type: 'choice',
instructions: 'Which team should handle `ticket.message`?',
criteria: {
returns: 'Exchanges, wrong or damaged items',
shipping: 'Delivery status, delays, or lost packages',
billing: 'Charges, invoices, or payment problems',
other: 'None of the above'
}
},
frustration: {
type: 'score',
instructions: 'How frustrated is the customer?',
criteria: ['Calm', 'Concerned but civil', 'Very angry']
},
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request money back?'
}
};
Transforme respostas digitadas em uma decisão auditável
Mantenha credenciais e chamadas de modelo no lado do servidor.
Valide o tamanho do estado, os campos obrigatórios e as definições das perguntas antes de chamar a API.
Armazene a versão do modelo, a versão da pergunta, as probabilidades, a confiança e a ação final.
Forneça um caminho outro/humano explícito e nunca invente um padrão de incerteza.
Tente novamente 429 e 529 com espera exponencial limitada; não tente novamente erros de validação.
Teste em relação a casos extremos rotulados e recalibre os limites antes de ativar a automação.
Case index
Six Jev patterns to explore next
These are research paths, not claims that this site built the projects. Each card opens the corresponding category in the open-source radar so you can inspect real implementations and source evidence.