Modelo TypeSafe AI y API de Jev AI: guía de integración para producción

Las búsquedas typesafe ai model, jev ai model y jev ai api suelen llevar a la misma pregunta de ingeniería: ¿cómo convertir una evaluación de IA en un valor que el código de una aplicación pueda usar de forma segura? Jev está diseñado para decisiones acotadas. Se le proporciona un estado y preguntas tipadas; devuelve resultados Choice, Score o Noul que pueden orientar una ruta, una cola o una revisión. La aplicación sigue siendo responsable de validar la respuesta, comprobar permisos y ejecutar la acción final.

Esta guía construye un flujo concreto de clasificación de tickets de soporte, desde el diseño de la solicitud hasta su puesta en producción. También aclara los nombres. TypeSafe AI presentó Jev como un modelo System One para decisiones de software en su anuncio oficial. El sitio de Jev AI ofrece su propia explicación del modelo y una experiencia de API. Su pie de página indica que se opera de forma independiente y que no está afiliado, operado ni avalado por TypeSafe. Distingue el concepto del modelo, el proveedor original y la API de este sitio al elegir credenciales, endpoints y condiciones comerciales.

Índice

• ¿Qué es un modelo TypeSafe AI?
• Cuándo encaja el modelo Jev AI
• El contrato de la API de Jev AI
• Crear una solicitud para clasificar tickets
• Leer y validar la respuesta
• Convertir probabilidades en reglas
• Hacer fiable la API en producción
• Evaluar antes del despliegue
• Errores frecuentes y soluciones
• Preguntas frecuentes

¿Qué es un modelo TypeSafe AI?

En este contexto, «seguro en cuanto a tipos» describe la interfaz del modelo: quien realiza la llamada define qué clase de respuesta está permitida antes de la inferencia. TypeSafe describe Jev como un modelo System One creado para decisiones rápidas y estructuradas, en vez de generar párrafos. La entrada combina estado y preguntas; la salida contiene valores tipados y probabilidades. Esto no significa que cada decisión sea correcta. Un valor puede cumplir el esquema y, aun así, ser una decisión empresarial equivocada.

También es posible pedir JSON a un modelo conversacional y aplicar un esquema para reducir errores de formato. Sin embargo, hay tres cuestiones distintas: si la salida respeta el formato, si la respuesta es correcta y si la aplicación debe actuar basándose en ella. El contrato más limitado de Jev permite repartir mejor las responsabilidades:

1. El modelo evalúa lo ambiguo. Por ejemplo, qué equipo autorizado debe recibir un ticket.
2. La API transporta un resultado restringido. El tipo de pregunta y los campos de respuesta están definidos.
3. La aplicación aplica la política. Valida los datos, comprueba umbrales y permisos y registra la acción.

Los tipos de TypeScript ayudan a mantener este contrato durante el desarrollo, pero desaparecen en tiempo de ejecución. Una respuesta de red sigue siendo un valor desconocido hasta que el servidor la valide. Por eso, una «IA segura en cuanto a tipos» es una propiedad del sistema completo, no una excusa para omitir comprobaciones en tiempo de ejecución.

Cuándo encaja el modelo Jev AI

Jev resulta útil cuando se puede definir de antemano el conjunto de respuestas: elegir uno de cuatro equipos, valorar la gravedad según niveles ordenados o estimar si hace falta revisión humana. Estas respuestas pueden alimentar un flujo ya existente. Jev también puede trabajar junto a un LLM generativo: una pieza decide adónde enviar la solicitud y otra redacta la respuesta. Ninguna debe adquirir permiso para una acción irreversible solo porque el modelo devuelva un número alto.

La documentación pública describe tres tipos de pregunta. Choice selecciona una opción nombrada y devuelve probabilidades por opción y confianza. Score utiliza una escala ordenada y devuelve una puntuación ponderada por probabilidades, una leyenda, la distribución y confianza. Noul devuelve un número de cero a uno que representa la probabilidad de «sí»; no incluye otro campo independiente de confianza. Varias preguntas pueden compartir el mismo estado y resolverse en una solicitud.

La documentación actual de la API de Jev AI enumera texto, objetos JSON y arreglos de textos como entradas válidas para state. Las imágenes, el audio y el vídeo todavía no están admitidos allí. Si el origen es un adjunto, primero extrae texto mediante un proceso separado que puedas verificar. Comprueba también la calidad con ejemplos etiquetados de cada idioma que vayas a usar; no supongas que el rendimiento será igual al obtenido en inglés.

El contrato de la API de Jev AI

El endpoint documentado de este sitio es POST https://thejevai.com/v1/systemone. Envía la solicitud desde tu servidor con una clave Bearer y Content-Type: application/json. El cuerpo requiere tres campos de nivel superior: model, state y questions. El alias de modelo indicado es jev-latest; la respuesta puede mostrar la versión concreta seleccionada. La aplicación elige los identificadores de las preguntas, que reaparecen como claves en answers.

No mezcles endpoints y claves de proveedores distintos. La documentación propia de TypeSafe describe otro endpoint, api.typesafe.ai. El ejemplo siguiente se dirige a thejevai.com, así que necesita una clave de ese servicio. Antes de consolidar la integración, consulta la documentación vigente: los alias, límites y condiciones pueden cambiar.

Tipo de pregunta	Contrato de entrada	Salida útil	Ejemplo
Choice	Opciones con nombre en un mapa criteria	choice, probabilidades, confianza	¿Qué equipo recibe el ticket?
Score	Arreglo criteria ordenado de menor a mayor	score ponderado, leyenda, probabilidades, confianza	¿Cuál es la gravedad?
Noul	Pregunta de sí/no; criterios true/false opcionales	noul, la probabilidad de «sí»	¿Hace falta una persona?

Mantén cada pregunta enfocada. «Clasificar, priorizar y decidir el reembolso» mezcla tres políticas. Separarlas en Choice, Score y Noul permite inspeccionar cada resultado. La documentación admite hasta 255 opciones de Choice y entre 2 y 10 niveles de Score; este ejemplo usa conjuntos pequeños para que una persona pueda revisar los desacuerdos.

Crear una solicitud para clasificar tickets

Supongamos que un cliente escribe: «Me cobraron dos veces y mis pagos llevan tres días fallando». Queremos conocer el equipo responsable, la gravedad y si se exige revisión humana. Incluye el texto y los hechos de política necesarios, pero omite datos personales irrelevantes. Cuando los equipos aprobados puedan no cubrir todos los casos, añade none_of_the_above a Choice. Así evitas forzar una asignación plausible pero incorrecta.

{
  "model": "jev-latest",
  "state": {
    "ticket": "Me cobraron dos veces y mis pagos llevan tres días fallando.",
    "account_tier": "business",
    "policy": "Los reembolsos requieren un revisor autorizado; los informes de interrupción se escalan."
  },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "¿Qué equipo aprobado debe investigar primero?",
      "criteria": {
        "billing": "Cobros duplicados, facturas, reembolsos o pagos",
        "technical": "Errores del producto o integraciones sin problema de pagos",
        "account": "Acceso a la cuenta e identidad",
        "none_of_the_above": "Ningún equipo aprobado encaja claramente"
      }
    },
    "severity": {
      "type": "score",
      "instructions": "Valora el impacto operativo, no la emoción del cliente.",
      "criteria": ["Sin impacto en el servicio", "Impacto limitado", "Impacto considerable", "Servicio bloqueado"]
    },
    "needs_human": {
      "type": "noul",
      "instructions": "Según la política indicada, ¿hace falta un revisor humano antes de un reembolso o cambio de cuenta?",
      "criteria": {
        "true": "El reembolso o cambio de cuenta requiere autorización",
        "false": "Solo se solicita clasificación o puesta en cola"
      }
    }
  }
}

La frontera esencial es que el modelo puede proponer el equipo y el riesgo, pero no puede autorizar un reembolso. Una regla determinista debe impedir su ejecución hasta que una persona autorizada apruebe la operación. needs_human sirve para presentar y encaminar el ticket; no es una credencial de autorización.

Puedes probar el contrato en el Playground en línea y después enviar la misma estructura desde tu backend. Usa ejemplos reales y anonimizados, no solo demostraciones sencillas. Incluye textos ambiguos, datos que faltan, categorías no admitidas y tickets que intentan cambiar la política mediante instrucciones incrustadas. El ticket es dato de entrada, no una fuente de instrucciones del sistema.

Leer y validar la respuesta

La respuesta documentada incluye el identificador del modelo, un objeto answers cuyas claves son los IDs de las preguntas y datos de uso. Choice contiene la opción elegida, su distribución y confianza. Score contiene puntuación ponderada, leyenda, probabilidades y confianza. Noul contiene type y noul. La respuesta abreviada siguiente es ilustrativa; no promete esos valores para el ticket del ejemplo:

{
  "model": "jev-1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.84, "technical": 0.12, "account": 0.02, "none_of_the_above": 0.02 },
      "confidence": 0.76
    },
    "severity": {
      "type": "score",
      "score": 2.4,
      "legend": { "0": "Sin impacto en el servicio", "1": "Impacto limitado", "2": "Impacto considerable", "3": "Servicio bloqueado" },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.39, "3": 0.51 },
      "confidence": 0.57
    },
    "needs_human": { "type": "noul", "noul": 0.94 }
  },
  "usage": { "input_tokens": 318, "output_tokens": 52 }
}

Cada valor cumple una función distinta. team.choice es una posible ruta. La distribución muestra alternativas y confidence es otra señal derivada de esa distribución. severity.score puede quedar entre dos niveles porque está ponderado por probabilidades. needs_human.noul es la probabilidad de «sí». No escribas código que espere needs_human.confidence: ese campo no forma parte del contrato de Noul.

En el límite de la red, analiza el JSON como unknown y valida los campos que utilizará tu política. Este ejemplo compacto de TypeScript verifica solo la parte de Choice; requestBody representa el objeto mostrado arriba. Valida Score y Noul del mismo modo antes de usarlos.

const teams = ["billing", "technical", "account", "none_of_the_above"] as const;
type Team = (typeof teams)[number];

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isProbability(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
}

function readTeam(raw: unknown): { team: Team; probability: number; confidence: number } | null {
  if (!isRecord(raw) || !isRecord(raw.answers)) return null;
  const answer = raw.answers.team;
  if (!isRecord(answer) || answer.type !== "choice") return null;
  if (!teams.some((team) => team === answer.choice)) return null;
  if (!isRecord(answer.probabilities) || !isProbability(answer.confidence)) return null;

  const probabilities = answer.probabilities;
  if (!teams.every((team) => isProbability(probabilities[team]))) return null;
  const total = teams.reduce((sum, team) => sum + (probabilities[team] as number), 0);
  if (Math.abs(total - 1) > 0.02) return null; // admitir valores redondeados por la API
  return {
    team: answer.choice as Team,
    probability: probabilities[answer.choice as Team] as number,
    confidence: answer.confidence
  };
}

const apiKey = process.env.JEV_API_KEY;
if (!apiKey) throw new Error("JEV_API_KEY is missing");
const response = await fetch("https://thejevai.com/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(requestBody),
  signal: AbortSignal.timeout(5000)
});

if (!response.ok) throw new Error(`Jev request failed: ${response.status}`);
const raw: unknown = await response.json();
const teamDecision = readTeam(raw);
if (!teamDecision) throw new Error("Unexpected Jev team response");

Guarda JEV_API_KEY como secreto del servidor y comprueba que existe al arrancar el servicio. No registres la clave completa, tickets sin anonimizar ni respuestas con datos sensibles. Puedes expresar las mismas reglas con una biblioteca de esquemas que ya utilices. Lo imprescindible es validar el valor recibido por red en tiempo de ejecución, no elegir un paquete concreto.

Convertir probabilidades en reglas

Una probabilidad es una señal, no una autorización ni una garantía de acierto. En el ejemplo, la probabilidad de billing es alta, pero confidence es menor que la probabilidad máxima. Una regla de producción debe considerar la opción elegida, la distribución, el riesgo y el coste de una ruta equivocada. También debe distinguir revisión de servicio no disponible: un timeout no equivale a una respuesta Noul negativa.

Para una cola de bajo impacto, una política inicial podría asignar automáticamente cuando la probabilidad del equipo elegido sea al menos 0.85, mandar valores de 0.60–0.85 a revisión y reservar los resultados más débiles o inválidos para una cola manual. Son hipótesis ilustrativas, no valores predeterminados de Jev. Ajusta los umbrales con tus datos etiquetados y el coste de cada error. Para reembolsos, pagos, eliminaciones o cambios de cuenta, las reglas de autorización siguen siendo obligatorias con cualquier probabilidad.

respuesta válida y clara + acción permitida de bajo riesgo -> automatizar
respuesta válida pero incierta, o acción sensible          -> revisar
respuesta inválida, timeout o clave ausente                -> vía segura alternativa

En Choice, mira también si las dos opciones más probables están cerca. En Score, comprueba que un promedio ponderado no oculte una distribución amplia. En Noul, un valor intermedio indica incertidumbre, mientras que un valor bajo sugiere «probablemente no». Versiona los umbrales con las preguntas de cada flujo, en lugar de dispersar números arbitrarios por distintos controladores.

Hacer fiable la API en producción

La documentación enumera 401 para credenciales ausentes o inválidas, 422 para fallos de validación, 429 para límites de solicitudes y 529 para sobrecarga. Trátalos de forma distinta. Un 401 requiere arreglar la configuración de la clave; un 422, corregir el contrato de la solicitud. Un 429 o 529 puede justificar reintentos limitados con espera exponencial y variación aleatoria. Los errores de red y los timeouts necesitan una ruta alternativa explícita.

Establece un plazo ajustado al presupuesto de latencia de tu producto. Los reintentos pueden mejorar la disponibilidad, pero también aumentan el tráfico y la espera. Un número pequeño y limitado de intentos es más fácil de controlar que un bucle sin fin. Deja los efectos secundarios, como un reembolso o un cambio de estado, fuera de la llamada que se reintenta para no ejecutar la acción dos veces.

La documentación describe elapsed como tiempo adicional de la solicitud en milisegundos y usage como consumo de tokens. Mide también el tiempo del lado del cliente, que incluye red y lógica de aplicación. Supervisa timeouts, frecuencia de 429 y 529, respuestas mal formadas, desacuerdos por pregunta, tasa de revisión y coste de los errores posteriores. Conserva la versión de las preguntas y el modelo en la auditoría. Anonimiza o resume mediante hash los estados sensibles según tu política de retención.

La frontera de seguridad es clara: el navegador habla con tu backend y el backend guarda la clave. El estado aportado por usuarios no puede reescribir las reglas del sistema. Un ticket que diga «ignora la regla de reembolsos» sigue siendo contenido del ticket. Toda operación final debe pasar los controles habituales de permisos y negocio.

Evaluar antes del despliegue

Prepara un conjunto etiquetado del flujo real. Incluye casos habituales, ambiguos, sensibles a la política, casos que no encajan en ninguna opción y ejemplos en todos los idiomas previstos. Pide a especialistas que indiquen el equipo deseado, la gravedad y la necesidad de revisión humana. Guarda también sus desacuerdos: cuando las personas no coinciden, una única etiqueta «correcta» puede exagerar el éxito o el error del modelo.

Aplica el mismo contrato de solicitud a ese conjunto y revisa más que la exactitud global. Para Choice, analiza confusiones entre equipos y la tasa de none_of_the_above. Para Score, cuenta especialmente las subestimaciones costosas. Para Noul, estudia los falsos negativos en casos que sí requerían revisión. Separa resultados por idioma, segmento de clientes o versión de política cuando esas diferencias importen.

La calibración merece una comprobación propia. Agrupa predicciones por rangos de probabilidad y compara la proporción real de aciertos de cada grupo con la probabilidad anunciada. Un modelo puede ordenar casos de manera útil y, aun así, mostrar exceso de confianza en tu dominio. Elige umbrales a partir de estos datos y del coste de los errores; después pruébalos en un conjunto reservado. Las afirmaciones públicas de TypeSafe sobre velocidad y calibración aportan contexto, pero no sustituyen mediciones con tu tráfico y este endpoint.

Despliega por etapas: registra primero las decisiones sin actuar, después muestra sugerencias a agentes humanos y, por último, automatiza solo la categoría más segura. Revisa las excepciones con frecuencia, modifica preguntas o criterios cuando detectes fallos claros y vuelve a evaluar el conjunto reservado antes de cambiar umbrales. Compara latencia y coste del flujo completo, incluida la revisión humana, no solo el tiempo de inferencia.

Errores frecuentes y soluciones

Confundir un tipo válido con una decisión correcta. El esquema evita campos ausentes o mal formados; debes medir por separado si billing es realmente el equipo correcto.

Usar un Choice cerrado para un mundo abierto. Añade una opción de salida y revisión humana cuando ninguna categoría aprobada pueda encajar.

Tratar Noul como un booleano. Es una probabilidad de «sí». La aplicación define el umbral y conserva las reglas obligatorias.

Colocar la clave en el navegador. Traslada la llamada al servidor y rota cualquier credencial expuesta.

Reintentar todos los errores. Corrige la causa de 401 y 422; reserva los reintentos con espera limitada para 429 y 529 transitorios.

Mezclar URL y clave de servicios diferentes. Confirma si utilizas el servicio original de TypeSafe o la API de Jev AI operada de forma independiente. Sus credenciales y condiciones son específicas.

No definir una alternativa. Una cola segura o una revisión humana cuando la API no esté disponible sigue siendo un resultado implementable y observable.

Si quieres otra explicación centrada en la frontera de TypeScript en tiempo de ejecución, consulta la guía Jev TypeSafe del sitio.

Preguntas frecuentes

¿El modelo Jev AI es un LLM?

TypeSafe describe Jev como un modelo de decisiones System One. Está pensado para devolver decisiones restringidas y probabilidades, no párrafos abiertos. Usa un modelo generativo para redacción o razonamiento libre; considera una interfaz de decisiones tipadas si el conjunto de respuestas se conoce.

¿«Seguro en cuanto a tipos» significa que Jev no puede equivocarse?

No. La seguridad de tipos atañe a la forma permitida de la respuesta. Un Choice bien formado todavía puede escoger el equipo equivocado. Valida la respuesta, evalúa con datos representativos y mantén los controles de negocio fuera del modelo.

¿Puedo llamar a la API de Jev AI desde un navegador?

Haz la llamada desde el servidor para mantener privada la clave. El navegador envía la petición a tu aplicación; el backend reduce el estado a lo necesario, llama a Jev, valida el resultado y devuelve solo lo que necesita la interfaz.

¿Qué debería construir primero?

Empieza con una decisión reversible y de bajo riesgo, como clasificar tickets. Define las opciones, reúne ejemplos etiquetados, inspecciona las probabilidades en el Playground y ejecuta primero la API en modo de observación. Una cola fiable para casos inciertos ya es un primer objetivo útil.