Conceitos e primitivas do Jev

Como obter acesso

Caminho mais rápido neste site: entrar, comprar um pack pré-pago pequeno, criar uma chave jv_live_, depois POST em /api/v1/decide. Chaves TypeSafe upstream ficam nos nossos servidores. Waitlist oficial e gateways de terceiros são opcionais se você precisar de credenciais TypeSafe brutas.

Opções de acesso

1. Hospedado neste site (recomendado para início rápido): Preços + Conta — tokens pré-pagos e chaves jv_live_ para /api/v1/decide e tools.
2. Alternativas oficiais / gateway: waitlist TypeSafe em typesafe.ai, mais OpenRouter, Vercel AI Gateway e Cloudflare AI se você já fatura nessas plataformas.

Limitação importante: Não há arquivo de modelo baixável. Você não pode self-host o Jev localmente. Toda inferência roda na nuvem (este host, TypeSafe ou um gateway).

Nota de preços

Cartão TypeSafe publicado: entrada cerca de $0.042 por milhão de tokens. Tokens de saída são grátis nesse cartão. Os packs de varejo deste site estão em Pricing (muitas vezes mais altos para cobrir hosting).

Para packs pré-pagos e medição ao vivo neste host, veja Pricing. Markups de gateway ainda podem valer se você chamar upstream em outro lugar.

Três primitivas centrais do Jev

Pedidos Jev são montados com três tipos de pergunta primitiva. Cada pedido envia state (contexto de entrada ou dados do programa) mais uma lista de perguntas tipadas. O Jev retorna resultados tipados estruturados com probabilidades calibradas.

1. Choice: Escolha uma resposta da sua lista de opções. Típico para roteamento de agentes e classificação.
2. Score: Retorne uma posição numérica graduada em uma escala ou rubrica. Típico para scoring de risco e severidade.
3. Noul: Retorne uma probabilidade de julgamento sim/não. Típico para gates de moderação e filtros booleanos simples.

Definições curtas também estão no glossário.

Instalação

Você não precisa de um pacote npm/pip oficial do Jev para chamar decide. Prefira nosso guia hospedado para exemplos ao vivo. HTTP mínimo POST funciona em qualquer linguagem. Node.js 18+ pode usar fetch nativo. Em Python, instale a biblioteca amplamente usada requests:

pip install requests

Neste site, crie uma chave jv_live_ em Account. Não invente nomes de pacote como @typesafe/jev-sdk.

# Store keys outside source control
export JEV_API_KEY="YOUR_API_KEY"
# Or, when calling through OpenRouter:
# export OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"

JSON completo mínimo de request da API

Endpoint hospedado usado abaixo: POST https://jevtypesafe.org/api/v1/decide. Para teste interativo e abas curl/Python/TypeScript, abra o guia da API.

{
  "state": "Customer message: my order has not arrived",
  "questions": {
    "ticket_routing": {
      "type": "choice",
      "options": ["support", "logistics", "billing"]
    },
    "is_urgent": {
      "type": "noul"
    },
    "severity_level": {
      "type": "score",
      "criteria": ["calm", "frustrated", "angry"]
    }
  }
}

Exemplos de API para copiar

Exemplos HTTP da comunidade contra a API decide deste site. Substitua JEV_API_KEY por uma chave jv_live_ de Account. Guia completo: /docs/api.

Node.js

// Minimal raw API call — hosted decide on this site
// Replace with a jv_live_ key from Account
async function callJev() {
  const apiKey = process.env.JEV_API_KEY;

  const payload = {
    state: "Customer message: my order has not arrived",
    questions: {
      ticket_routing: {
        type: "choice",
        instructions: "Route this ticket",
        criteria: { support: "product help", logistics: "shipping", billing: "payment" },
      },
    },
  };

  const res = await fetch("https://jevtypesafe.org/api/v1/decide", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    throw new Error(`Jev request failed: ${res.status}`);
  }

  return res.json();
}

Python

# Minimal raw API call — hosted decide on this site
# Requires: pip install requests
# Replace with a jv_live_ key from Account
import os
import requests

def call_jev():
    api_key = os.environ["JEV_API_KEY"]
    payload = {
        "state": "Customer message: my order has not arrived",
        "questions": {
            "ticket_routing": {
                "type": "choice",
                "instructions": "Route this ticket",
                "criteria": {"support": "product help", "logistics": "shipping", "billing": "payment"},
            }
        },
    }
    response = requests.post(
        "https://jevtypesafe.org/api/v1/decide",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Boas práticas

1. Mantenha chaves de API em variáveis de ambiente; nunca no frontend (exceto o tester intencional de chave no browser).
2. Adicione cache de requests para decisões repetidas e reduza chamadas e custo.
3. Adicione retry para falhas de rede transitórias.
4. Valide todos os schemas de entrada antes de enviar à modelo.
5. Prefira Choice / Score / Noul a prompts de texto livre quando precisar de automação.

Notas de implementação

Cacheie pela identidade da decisão, não pelo texto bruto do prompt

Faça hash do conjunto de perguntas mais campos de state normalizados. Se dois pedidos representam a mesma decisão de roteamento, reutilize o resultado anterior. Especialmente útil em hot paths como scoring de moderação e seleção de tools.

Fail closed em mismatch de schema

Se a resposta não bater com o schema de decisão esperado, não force silenciosamente para um ramo padrão. Registre o incidente, devolva uma rota de fallback segura e alerte.

Mantenha LLMs generativos atrás do gate de decisão

Chame o Jev primeiro. Só invoque um modelo estilo chat depois que a rota for conhecida. Veja casos de uso em produção para exemplos concretos.