Guía del SDK de Jev

Cómo acceder

Camino más rápido aquí: inicia sesión, compra un pack, crea jv_live_, POST a /api/v1/decide. Las claves TypeSafe upstream quedan en nuestros servidores. Lista de espera y pasarelas son opcionales.

Opciones de acceso

1. Alojado en este sitio (recomendado): Precios + Cuenta — tokens prepago y claves jv_live_ para /api/v1/decide y tools.
2. Oficial / pasarelas: waitlist en typesafe.ai, más OpenRouter, Vercel AI Gateway y Cloudflare AI si ya facturas ahí.

Limitación importante: No hay archivo de modelo descargable. No puedes autoalojar Jev localmente. Toda inferencia es en la nube.

Nota de precios

Los tokens de entrada cuestan 0,042 USD por millón de tokens. Los tokens de salida son totalmente gratis. No se te cobrarán salidas de decisión Jev en la tarifa publicada de TypeSafe.

Las pasarelas pueden aplicar markup o unidades de facturación extra. Revisa su página de precios antes de estimar coste en producción. Consulta también la FAQ de precios.

Tres primitivas centrales de Jev

Las peticiones Jev se construyen con tres tipos de pregunta primitiva. Cada petición envía state (contexto de entrada o datos del programa) más una lista de preguntas tipadas. Jev devuelve resultados tipados estructurados con probabilidades calibradas.

1. Choice: Elige una respuesta de tu lista de opciones. Típico para enrutado de agentes y clasificación.
2. Score: Devuelve una posición numérica en una escala o rúbrica. Típico para scoring de riesgo y severidad.
3. Noul: Devuelve probabilidad de un juicio sí/no. Típico para compuertas de moderación y filtros booleanos.

Definiciones breves también en el glosario.

Instalación

No hay un paquete npm o pip oficial obligatorio solo para enviar una petición. El camino mínimo es un HTTP POST al endpoint System One. Node.js 18+ puede usar fetch integrado. En Python, instala requests:

pip install requests

Si llamas a Jev vía OpenRouter, usa su API Decisions documentada y su clave. No inventes nombres de paquete 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 petición API

Endpoint en los ejemplos: POST https://jevtypesafe.org/api/v1/decide. Confirma ruta y campos actuales en la documentación TypeSafe antes de producción.

{
  "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"]
    }
  }
}

Ejemplos API para copiar

Ejemplos mínimos de la comunidad con HTTP crudo. No son un SDK oficial. Sustituye la variable de entorno por una clave real de lista de espera o pasarela.

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()

Buenas prácticas del SDK

1. Guarda claves API en variables de entorno; nunca en frontend.
2. Añade caché para decisiones repetidas y reduce coste.
3. Añade reintentos para fallos de red transitorios.
4. Valida esquemas de entrada antes de enviar.
5. Prefiere Choice / Score / Noul frente a prompts libres cuando automatizas.

Notas de implementación

Cachea por identidad de decisión, no por prompt crudo

Hashea el conjunto de preguntas y campos de state normalizados. Si dos peticiones son la misma decisión de enrutado, reutiliza el resultado. Muy útil en moderación y selección de herramientas.

Fail closed ante desajuste de esquema

Si la respuesta no encaja con tu esquema esperado, no la fuerces a una rama por defecto. Registra, devuelve ruta segura y alerta.

Mantén LLMs generativos detrás de la compuerta de decisión

Llama primero a Jev. Invoca el modelo chat solo cuando la ruta sea conocida. Ejemplos en casos de uso en producción.