Como usar o Jev como quality gate de um pipeline de dados?

Schema bateu, not null passou, tipo de coluna certinho, e mesmo assim o lote tá errado

O campo descricao veio com "N/A", o texto tá truncado no meio da palavra, metade dos registros veio em outro idioma e a categoria não tem nada a ver com o produto

Regra de validação não pega isso, porque isso não é regra, é julgamento

E julgamento é justamente onde entra o Jev: um modelo que não escreve texto, ele responde perguntas tipadas contra um state e devolve valor tipado mais distribuição de probabilidade, que o teu código consome direto

Neste post a gente monta um quality gate de verdade: o lote chega, o gate decide entre warehouse, quarentena e reprocessamento, e o orquestrador executa sem nenhum parsing de string pelo caminho

E tem uma saída de segurança em cima disso, a revisão humana, que não é escolha do modelo e sim do teu limiar de confiança (te conto no passo 6)

Por que um modelo tipado resolve o que regra de validação não pega

Validação determinística é ótima e vai continuar existindo

Ela responde perguntas fechadas: o schema bate? a chave é única? o valor tá dentro do range? a contagem de linhas confere com o manifesto?

Isso é código, é rápido, é barato e é 100% previsível

O problema é a outra metade do trabalho

• campo preenchido com lixo plausível ("-", "sem informação", "teste123")
• texto truncado no meio, tipo Cabo HDMI 2.1 de alta veloci
• idioma trocado numa fatia do lote
• descrição que não bate com a categoria declarada
• registro que passa em toda regra e ainda assim é obviamente inútil pra quem vai consumir

Nenhuma dessas coisas vira um CHECK constraint decente

É aqui que o Jev encaixa

Ele é o primeiro modelo da classe System One da TypeSafe AI, lançado em 15 de setembro de 2026 em acesso antecipado

O posicionamento da empresa é curioso e importante pro nosso caso: modelo feito pra máquina, não pra pessoa

Ele não gera texto token a token

Entra um state (texto ou JSON) mais perguntas tipadas, sai decisão tipada

A TypeSafe alega inteligência de nível frontier em menos de 100 milissegundos de latência e até 100x mais rápido e mais barato que modelos frontier (isso é alegação da fornecedora, então trate como alegação até medir no teu ambiente)

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 dá pra afirmar com segurança pelo desenho: quando a saída já é um valor tipado com confidence de 0 a 1, o gate vira um if no orquestrador, não um parser de JSON dentro de markdown que quebra na terça-feira 🙂

E tem três tipos de pergunta, só isso:

Três primitivas, e o gate inteiro cabe nelas

O que você precisa antes de plugar o Jev no pipeline

Antes do código, o checklist chato mas necessário:

1. Acesso ao modelo

A TypeSafe anunciou em 22 de setembro de 2026 a pausa temporária dos novos cadastros por excesso de demanda

Contas já criadas seguem funcionando, e a pausa ainda estava em vigor em 24 de setembro de 2026

Se você não tem conta direta, o Jev também aparece em outros lugares: na OpenRouter com os ids typesafe/jev-1.13 e typesafe/jev-latest, no AI Gateway da Vercel e no catálogo de modelos do Cloudflare Workers AI

2. SDK ou HTTP puro

A TypeSafe publica SDK oficial pra Python (que exige Python 3.10 ou superior) e pra JavaScript/TypeScript

O cliente oficial lê a chave da variável de ambiente TYPESAFE_API_KEY e chama jev-latest por padrão

Se preferir bater direto no HTTP, o endpoint da API System One é POST https://api.typesafe.ai/v1/systemone

export TYPESAFE_API_KEY="sua-chave-aqui"

3. Um orquestrador que já quebra o job em lotes

Airflow, Dagster, Prefect, cron com script, tanto faz

O gate é uma task a mais entre "lote pronto" e "carrega no warehouse", e ele precisa conseguir fazer um POST e ler a resposta

4. Consciência do contexto

O Jev 1.13 tem 32.000 tokens de contexto

Isso não é detalhe, é restrição de projeto: entra amostra, não entra o lote inteiro

Se o teu volume é grande de verdade e você quer opinião do modelo sobre cada pedaço, o caminho é outro desenho, aquele de map-reduce com Jev em volumes grandes, e não enfiar tudo num state só

Sobre custo, o preço publicado é US$ 0,042 por 1 milhão de tokens de entrada, com tokens de saída a US$ 0

Ou seja, o que pesa na conta é o tamanho do state que você manda, o que reforça a mesma ideia: amostra enxuta

Passo a passo: montando o quality gate

1. Defina a decisão ANTES de escrever qualquer pergunta

Esse passo parece burocracia e é o mais importante

O gate não existe pra "avaliar qualidade", ele existe pra escolher um caminho

Repara que são três rotas, e só três: é exatamente esse o conjunto de opções que o modelo vai escolher na Choice

A revisão humana NÃO é uma quarta opção do Choice, ela é saída de segurança do teu código: quando a confiança da escolha vem baixa, o orquestrador ignora a rota sugerida e manda o lote pra uma fila de análise (o passo 6 mostra isso)

Só depois de fechar essa tabela é que você escreve as perguntas

O erro comum deste passo: criar um gate que devolve "nota de qualidade de 0 a 10" e ninguém sabe o que fazer com 6,4

2. Monte o state: metadados calculados por você + amostra

O state aceita objeto ou array JSON, com contexto, exemplos e informações que ajudam o modelo a responder

Repare numa coisa: a contagem de linhas vem do SEU código, não de um pedido ao modelo

import random

def montar_state(lote, meta, tamanho_amostra=25):
    amostra = random.sample(lote, min(tamanho_amostra, len(lote)))
    return {
        "origem": meta["origem"],
        "janela": meta["janela"],                 # calculado pelo pipeline
        "linhas_no_lote": len(lote),              # contado em Python, nao pelo modelo
        "colunas_esperadas": meta["schema"],
        "amostra_de_registros": amostra,
    }

O erro comum deste passo: despejar o lote inteiro no state achando que mais dado é mais acurácia

A própria documentação de jaggedness avisa que a acurácia cai conforme o state se enche de conteúdo não relacionado à decisão

State inchado é state pior, e ainda por cima mais caro

3. Escreva as perguntas tipadas

Uma Choice pra rota, Nouls pras afirmações binárias, Scores pro que é gradiente

PERGUNTAS = {
    # Choice: as tres rotas do gate, sem ordem entre elas
    "rota": {
        "tipo": "choice",
        "pergunta": "Considerando os metadados e a amostra, qual destino este lote deve ter?",
        "opcoes": ["warehouse", "quarentena", "reprocessamento"],
    },
    # Nouls: afirmacoes verdadeiro/falso
    "campos_criticos_reais": {
        "tipo": "noul",
        "afirmacao": "Os campos criticos da amostra estao preenchidos com valor real, "
                     "e nao com placeholders como 'N/A', '-', 'teste' ou string vazia",
    },
    "encoding_ok": {
        "tipo": "noul",
        "afirmacao": "O texto da amostra esta com encoding consistente, sem caracteres "
                     "corrompidos do tipo 'ç' ou '\\ufffd'",
    },
    "coerente_com_schema": {
        "tipo": "noul",
        "afirmacao": "O conteudo de cada campo da amostra corresponde ao significado "
                     "declarado para aquela coluna no schema",
    },
    # Score: rubrica com niveis que VOCE define
    "utilidade_das_descricoes": {
        "tipo": "score",
        "pergunta": "Quao utilizavel esta o campo de descricao da amostra?",
        "niveis": [
            "inutilizavel: vazio, truncado ou sem sentido na maioria dos registros",
            "ruim: muitos registros genericos ou incompletos",
            "aceitavel: descreve o item, com falhas pontuais",
            "bom: descritivo, completo e coerente com a categoria",
        ],
    },
}

Rubrica de Score precisa de no mínimo 2 níveis e a API aceita até 10

O erro comum deste passo: pedir pro modelo contar

Nada de "quantos registros estão vazios?" ou "a data do lote é posterior à do lote anterior?"

A própria TypeSafe documenta que o Jev 1.13 não conta de forma confiável, lê datas como texto e não tem precisão numérica

Contagem e comparação de data são trabalho do teu código, ponto

4. Mande tudo numa chamada só

Todas as perguntas de uma requisição são avaliadas em paralelo e em isolamento contra o mesmo state

No cookbook oficial de perguntas paralelas, agrupar 13 perguntas sobre o mesmo artigo numa única chamada saiu 12,2x mais barato e 10,0x mais rápido, sem mudança nas respostas

Faz sentido: você paga o state uma vez, não sete vezes

state = montar_state(lote, meta)
resposta = chamar_jev(state, PERGUNTAS)  # POST https://api.typesafe.ai/v1/systemone

O erro comum deste passo: escrever uma rubrica que referencia a resposta de outra pergunta

Coisa tipo "se o encoding estiver ok, então avalie…"

Não funciona, porque as perguntas são isoladas: uma não vê a resposta da outra

Se existe dependência, ela vive no teu if, depois que as respostas chegam

5. Leia a resposta

A resposta traz o identificador do modelo, um objeto answers com uma resposta por pergunta e usage com input_tokens e output_tokens

Respostas de Choice e Score incluem probabilities (a distribuição entre opções ou níveis) e confidence, que colapsa a distribuição num número de 0 a 1 pra você aplicar um limiar sem precisar fazer a conta

print(resposta["model"])
print(resposta["usage"]["input_tokens"], resposta["usage"]["output_tokens"])

rota = resposta["answers"]["rota"]
confianca = rota["confidence"]          # 0 a 1
distribuicao = rota["probabilities"]    # distribuicao entre as tres opcoes

Guarda probabilities no log sempre

É ele que depois te mostra a diferença entre "warehouse com folga" e "warehouse por pouquinho"

O erro comum deste passo: jogar fora a distribuição e salvar só a decisão

Aí quando o gate erra você não tem como calibrar nada

6. Aplique o limiar no orquestrador

A documentação da TypeSafe traz um padrão pronto pra isso, o confidence-gated routing: abaixo do limiar vai pra revisão humana, acima segue pro handler automático (o exemplo da doc usa confidence < 0.8)

HANDLERS = {
    "warehouse": carregar_no_warehouse,
    "quarentena": mover_para_quarentena,
    "reprocessamento": reagendar_extracao,
}

def aplicar_gate(lote_id, opcao, confianca, limiar=0.8):
    if confianca < limiar:
        return enfileirar_revisao_humana(lote_id, opcao, confianca)
    handler = HANDLERS.get(opcao)
    return handler(lote_id)

Repara que não tem json.loads, não tem regex, não tem "extrai o que veio depois dos dois pontos"

A saída já é tipada, então ela encaixa direto no orquestrador

O erro comum deste passo: chutar o limiar e nunca mais olhar pra ele

O limiar bom vem dos teus dados, e no fim do post eu falo de como levantar isso sem risco

7. Trate o 429

Os rate limits da TypeSafe são medidos em tokens por segundo e requisições por minuto, e uma requisição acima de qualquer um dos limites recebe 429 Too Many Requests

A doc avisa também que esses limites podem mudar sem aviso, então trate 429 como evento normal do dia a dia, não como incidente

import time

def com_retry(fn, tentativas=4):
    espera = 1.0
    for i in range(tentativas):
        resp = fn()
        if resp.status_code != 429:
            return resp
        if i == tentativas - 1:
            break
        time.sleep(espera)
        espera *= 2
    return None  # gate indisponivel: cai no fallback

E decide agora, com a cabeça fria, qual é o fallback quando o gate não responde

A opção conservadora é mandar o lote pra quarentena em vez de pro warehouse: dado errado no warehouse custa muito mais caro que lote parado esperando

O erro comum deste passo: fallback silencioso que libera o lote quando o gate falha

Já vi pipeline "verde" o mês inteiro assim 😛

Quatro perguntas de gate que valem a pena no seu pipeline

CSV de fornecedor:

O clássico do arquivo que muda de formato sem ninguém avisar

Aqui o Noul brilha: "a amostra segue o mesmo layout de colunas declarado no contrato de integração"

Como Noul devolve um valor entre 0 e 1, você consegue separar o "claramente ok" (perto de 1) do "tem coisa estranha" (região do meio) sem precisar inventar categoria nova

Complementa com um Score de completude da amostra, com uns 4 níveis bem descritos

Scraping:

Scraping falha de um jeito específico: a página muda e o seletor passa a capturar menu, cookie banner ou página de erro

O detalhe cruel é que isso passa em qualquer validação de schema, porque é string preenchida

Use Choice pra classificar o que a amostra parece ser: conteudo_valido, pagina_de_erro, bloqueio_antibot, layout_mudou

Cada uma dessas quatro opções dispara uma ação diferente no orquestrador, e a distribuição de probabilidade te diz se o modelo tá dividido entre duas hipóteses ou cravou uma

Payload de API de terceiro:

API de terceiro adora responder 200 com corpo degradado: campos opcionais sumindo, enum novo aparecendo, texto virando null

Noul pra "todos os campos obrigatórios da amostra vieram com valor real", Choice pra rota e Score pra riqueza do payload

Tudo na mesma chamada, contra o mesmo state

Enriquecimento de catálogo:

Esse é o caso mais "julgamento puro": a descrição bate com a categoria? o título corresponde ao produto? o texto foi truncado?

Score com rubrica é a ferramenta certa, porque é gradiente e não sim/não

E o desenho aqui é o mesmo de qualquer roteamento por Choice com limiar de confiança, igual quando você usa Jev pra qualificar leads no funil: muda o state e mudam as opções, a mecânica é idêntica

Onde o gate falha (e como prevenir)

A TypeSafe publica uma página de jaggedness do Jev 1.13 listando as fraquezas conhecidas do modelo

Ler isso antes de ir pra produção economiza uns bons cabelos brancos

Sintoma: o gate erra contagem ou ordem de datas

Causa: o Jev 1.13 não conta de forma confiável (caracteres, ocorrências ou itens de lista), lê datas como texto e não como quantidades ordenadas, e não tem precisão numérica

Como prevenir: toda pergunta que tem resposta exata sai do modelo e vira asserção determinística no código

Contagem de nulos, cardinalidade, janela temporal, soma de valores: tudo isso é SQL ou Python

O Jev fica com o que sobra, que é o julgamento sobre o conteúdo

Sintoma: você tenta reconstruir um número a partir do Score

Causa: os níveis de Score do Jev 1.13 são fracos em calibração numérica, e a doc é explícita em dizer que eles não devem ser usados pra reconstruir o valor exato por interpolação entre níveis

Como prevenir: trate Score como faixa, não como régua

"Nível aceitável ou acima segue" funciona

Tentar converter o Score num percentual exato de registros ruins não funciona, e pior, parece que funciona por umas semanas

Sintoma: um lote sujo passa e ninguém entende por quê

Causa: o Jev trata o state como dado, não como conteúdo hostil

Texto escrito pra direcionar a resposta (instrução injetada, enquadramento enganoso) pode mover o resultado

E adivinha o que tem dentro de um pipeline de dados? Campo livre vindo de fora 🙂

Como prevenir: isole o conteúdo de terceiro em campos próprios e bem rotulados dentro do state, nunca misturado com a tua instrução

Se o dado de origem é não confiável (scraping, formulário público, comentário de usuário), assuma isso no desenho e não deixe conteúdo de terceiro parecer instrução

Sintoma: a acurácia cai quando o lote cresce

Causa: state poluído com contexto irrelevante pra decisão

A doc avisa que a acurácia cai conforme o state se enche de conteúdo que não ajuda a responder a pergunta

Somando com os 32.000 tokens de contexto do Jev 1.13, o teto aparece rápido

Como prevenir: amostra estratificada e enxuta, com só as colunas que importam pra decisão

Se o gate precisa olhar 5 campos, manda 5 campos, não os 40 da tabela

Sintoma: 429 em horário de pico

Causa: os limites são medidos em tokens por segundo e requisições por minuto, e estourar qualquer um dos dois devolve 429

Como esses limites podem mudar sem aviso, não dá pra tratar como constante

Como prevenir: retry com backoff, agrupamento de perguntas numa chamada só (menos requisições pelo mesmo trabalho) e fallback definido no código, conservador

Vídeo: pipeline de IA na prática

Pra começar do zero com pipeline montado com IA, este vídeo do canal mostra o fluxo de ponta a ponta, do desenho até o código rodando:

O próximo passo

O desenho certo desse negócio é chato de tão simples:

• o determinístico valida o que é regra (schema, unicidade, range, contagem, data)
• o Jev decide o que é julgamento (o conteúdo faz sentido? bate com a categoria? é lixo plausível?)
• o orquestrador consome a saída tipada e executa, sem parsing no meio

E o próximo passo prático não é ligar o gate em produção na sexta à noite haha

Roda ele em modo sombra primeiro: o gate avalia os lotes e só loga a decisão, probabilities e confidence, sem bloquear nada

Aponta pra lotes que já foram aprovados historicamente, deixa rodando uns dias e compara

Onde o gate discordou do histórico, olha o caso na mão: às vezes o modelo errou, às vezes ele achou um problema que passou batido por meses

Com esses dados na mesa, você calibra o limiar de confidence com número real em vez de chute, e só então liga o roteamento de verdade

É mais lento pra subir e MUITO mais tranquilo pra dormir

até o próximo post!