Jev TypeSafe: decisiones tipadas en TypeScript

Quienes buscan jev typesafe suelen encontrar dos ideas relacionadas, pero distintas: las decisiones de IA tipadas de Jev y el sistema de tipos de TypeScript. Esta guía explica cómo conectarlas sin confundir un tipo de compilación con un resultado fiable en tiempo de ejecución. Jev evalúa preguntas sobre un estado y devuelve respuestas estructuradas; tu servicio TypeScript todavía debe validar la respuesta de red y decidir qué puede hacer la aplicación.

El sitio de Jev presenta el producto como una herramienta de decisiones independiente para equipos de software. Jev no está afiliado a TypeSafe, no es operado por TypeSafe ni cuenta con su respaldo. Puedes conocer el producto en la página principal de Jev AI y probar su Playground en línea.

Qué significa usar Jev con seguridad de tipos en TypeScript

TypeScript comprueba el código antes de ejecutarlo. Puede detectar propiedades mal escritas o tipos internos incorrectos al llamar una función. Sin embargo, no puede demostrar que una respuesta HTTP de un servicio remoto coincida con el tipo que declaraste. Una instrucción como const answer: Decision = await response.json() solo le dice al compilador qué esperas recibir; no inspecciona los bytes que llegaron realmente.

Trata el valor de response.json() como unknown hasta que la aplicación compruebe su estructura. Este límite tiene dos partes:

1. Construcción de la solicitud: TypeScript ayuda a mantener coherentes el estado, las definiciones de preguntas y los identificadores internos.
2. Lectura de la respuesta: las comprobaciones en tiempo de ejecución confirman que los datos remotos incluyen los campos que el código va a usar.

La distinción importa porque la respuesta del modelo es una señal para decidir, no una autorización para ejecutar una acción. La autenticación, las reglas del negocio, las comprobaciones deterministas y las aprobaciones necesarias siguen siendo responsabilidad de tu aplicación.

Los tres tipos de pregunta de Jev

La documentación oficial de Jev describe tres formas de pregunta. Elige el tipo que corresponda a la forma de la decisión, en vez de pedir a un único prompt amplio que resuelva varias tareas sin relación.

Tipo	Adecuado para	Resultado que conviene revisar
Choice	Elegir equipo, cola, categoría o modelo	Opción elegida, probabilidades, confianza
Score	Gravedad, calidad, urgencia u otra escala ordenada	Puntuación ponderada, probabilidades por nivel, confianza
Noul	Determinar si una proposición concreta es verdadera	Probabilidad de 0 a 1 de que la respuesta sea sí

Usa Choice cuando las respuestas posibles estén definidas. Si un ticket puede ir a facturación, soporte técnico o ventas, describe qué corresponde a cada opción. Añade una opción segura como other o needs_review cuando la lista no cubra todos los casos; de lo contrario, el clasificador tendrá que escoger la alternativa menos incorrecta.

Usa Score cuando haya un orden entre los resultados. Define los niveles de menor a mayor con descripciones concretas. Una escala de gravedad puede especificar qué tiempo de respuesta o escalamiento corresponde a “bajo”, “medio” y “crítico”. Jev devuelve una distribución de probabilidades y una puntuación ponderada por probabilidad, así que el resultado puede quedar entre los niveles con nombre. Tu código debe asignarlo a una política de negocio explícita.

Usa Noul para una proposición única de sí o no, por ejemplo, si un mensaje solicita claramente un reembolso. El valor noul representa la probabilidad de que la respuesta sea sí; no es un segundo campo de confianza. Si el flujo necesita una categoría y una condición binaria, envía dos identificadores de pregunta y lee ambas respuestas.

Diseña el límite de decisión antes de crear la solicitud

Una integración fiable empieza con un contrato de decisión pequeño y claro. Anota qué acción concreta puede realizar la aplicación, cuáles son las respuestas posibles, qué evidencia debe incluirse en la entrada y qué debe ocurrir cuando el resultado sea incierto. A menudo esto revela que una supuesta “tarea de IA” contiene en realidad dos o tres preguntas independientes.

Por ejemplo, un flujo de soporte puede pedir a Jev que elija un equipo, puntúe la urgencia y determine si el mensaje solicita explícitamente un reembolso. Las preguntas pueden compartir el mismo estado y evaluarse en una sola solicitud. Asigna claves estables como department, urgency y refund_requested; el código las usa para encontrar cada respuesta. Mantén las claves aunque cambies las etiquetas visibles para el personal.

El estado debe tener suficiente información, pero no estar inflado. Para asignar un ticket quizá necesites el mensaje, el área del producto y el nivel de cuenta. Probablemente no necesites el perfil completo del cliente, un historial de conversación ajeno al problema ni secretos. Un estado más breve y pertinente es más fácil de revisar, cuesta menos transmitirlo y reduce la exposición de datos irrelevantes.

Jev acepta texto, objetos JSON y arreglos de texto como estado. Usa una cadena para un caso sencillo y un objeto estructurado cuando los campos tengan significados diferentes. Un arreglo puede contener textos relacionados, como el mensaje actual y un fragmento corto de una política. La documentación actual no incluye imágenes, audio ni video como entradas directas; si los necesitas, conviértelos primero en texto relevante con OCR, transcripción u otro servicio.

Construye una solicitud tipada y valida la respuesta

El ejemplo siguiente llama al endpoint System One documentado desde un servicio TypeScript del lado servidor. El tipo de la solicitud ayuda a detectar errores al escribir código. La respuesta permanece como unknown hasta que las comprobaciones de ejecución validen los campos que consume este flujo.

type Question =
  | { type: "choice"; instructions: string; criteria: Record<string, string> }
  | { type: "score"; instructions: string; criteria: string[] }
  | { type: "noul"; instructions: string };

type EvaluationRequest = {
  model: "jev-latest";
  state: string | Record<string, unknown> | string[];
  questions: Record<string, Question>;
};

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

function isProbabilityMap(value: unknown): value is Record<string, number> {
  const map = asRecord(value);
  if (!map) return false;
  const entries = Object.values(map);
  if (entries.length === 0) return false;
  if (!entries.every(
    (item) => typeof item === "number" && Number.isFinite(item) && item >= 0 && item <= 1
  )) return false;
  const total = entries.reduce((sum, item) => sum + item, 0);
  return Math.abs(total - 1) < 0.02;
}

async function classifyTicket(ticket: string) {
  const apiKey = process.env.JEV_API_KEY;
  if (!apiKey) throw new Error("JEV_API_KEY is not configured");

  const request = {
    model: "jev-latest",
    state: { message: ticket },
    questions: {
      department: {
        type: "choice",
        instructions: "¿Qué equipo debe atender este ticket?",
        criteria: {
          billing: "Pagos, facturas, reembolsos o desembolsos",
          technical: "Errores, interrupciones o fallos de integración",
          sales: "Precios, mejoras del plan o nuevas cuentas"
        }
      }
    }
  } satisfies EvaluationRequest;

  const response = await fetch("https://thejevai.com/v1/systemone", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(request)
  });

  if (!response.ok) throw new Error("Falló la solicitud a Jev: " + response.status);

  const payload: unknown = await response.json();
  const root = asRecord(payload);
  const answers = asRecord(root?.answers);
  const answer = asRecord(answers?.department);

  if (
    answer?.type !== "choice" ||
    typeof answer.choice !== "string" ||
    typeof answer.confidence !== "number" ||
    !Number.isFinite(answer.confidence) ||
    answer.confidence < 0 ||
    answer.confidence > 1 ||
    !isProbabilityMap(answer.probabilities)
  ) {
    throw new Error("La estructura de respuesta de Jev no es la esperada");
  }

  const allowedTeams = ["billing", "technical", "sales"];
  if (!allowedTeams.includes(answer.choice)) {
    throw new Error("Jev devolvió un equipo no reconocido");
  }

  return {
    team: answer.choice,
    confidence: answer.confidence,
    probabilities: answer.probabilities
  };
}

const result = await classifyTicket("Fallaron tres despliegues y producción está devolviendo errores 500.");
if (result.confidence >= 0.8) {
  // Aplicar la lista permitida y las reglas de negocio antes de enrutar.
} else {
  // Enviar los casos inciertos a una cola de revisión humana.
}

El ejemplo es deliberadamente acotado. Valida la forma de la respuesta usada para asignar el equipo, comprueba que las probabilidades sean números finitos dentro del rango permitido y rechaza una opción que no aparezca en la lista permitida de la aplicación. Una aplicación más grande debe validar todos los campos que influyan en una acción. Si un campo es solo informativo, no dejes que se convierta silenciosamente en una señal de control.

Guarda JEV_API_KEY en un almacén de secretos del servidor. Nunca la incluyas en un paquete del navegador, un repositorio público, un mensaje de error ni las propiedades de analítica. Un tipo de TypeScript no oculta un valor a los usuarios si el código que lo contiene se entrega al navegador.

Lee la respuesta sin confiar demasiado en ella

La respuesta se organiza según los identificadores de las preguntas enviadas. En Choice, revisa la opción elegida, las probabilidades de las opciones y la confianza. En Score, revisa la puntuación ponderada, la leyenda, las probabilidades por nivel y la confianza. En Noul, lee la probabilidad de que la respuesta sea sí. Valida la forma correspondiente al tipo de pregunta; no supongas que todas las respuestas tienen los mismos campos.

Una respuesta puede tener una estructura válida y aun así ser incorrecta para un caso de negocio concreto. La validación en ejecución responde: “¿Puede mi código leer este valor de forma segura?”. La evaluación responde: “¿Este flujo toma buenas decisiones con entradas representativas?”. Son comprobaciones diferentes y ambas hacen falta.

Evita reducir todas las señales a un booleano genérico success. Conserva el resultado tipado para que la política de la aplicación use el campo adecuado. El enrutamiento puede depender de la opción de Choice y un umbral de confianza; una cola de prioridad puede usar Score; una confirmación puede depender de Noul. Los mapeos explícitos facilitan las revisiones y la depuración posteriores.

Usa la confianza como señal, no como garantía

Jev devuelve probabilidades y una señal de confianza para Choice y Score; Noul devuelve la probabilidad de que la respuesta sea sí. Estos valores ayudan a comparar o enrutar casos, pero no demuestran que la decisión sea correcta. La confianza no equivale a la precisión medida, y un valor alto no garantiza la seguridad.

Crea un conjunto de evaluación etiquetado que se parezca a la distribución real de entradas. Incluye casos habituales, casos límite, casos poco frecuentes pero costosos y ejemplos que deban ir a other o a revisión humana. Mide los errores por sus consecuencias, no solo con una única cifra de exactitud global. Enviar una interrupción urgente a una cola de baja prioridad puede costar más que escalar innecesariamente una solicitud rutinaria.

Elige los umbrales a partir del comportamiento observado y del coste de equivocarse. Para una sugerencia de bajo impacto, un umbral menor puede ser aceptable si una persona puede corregirla fácilmente. Para pagos, restricciones de cuenta u operaciones destructivas, conserva las reglas deterministas y la aprobación humana incluso cuando la señal del modelo sea alta. No copies el umbral de un tutorial como si fuera un valor universal.

Trata los fallos y la incertidumbre como rutas normales

Una solicitud puede fallar antes de que Jev responda: la red puede agotar el tiempo de espera, el servicio puede devolver un estado no exitoso o el cuerpo puede no poder analizarse. Modela estos resultados explícitamente. Un tipo interno puede distinguir decision, review y unavailable para evitar que un fallo de transporte parezca una respuesta negativa normal.

Define tiempos de espera y reintentos limitados que se ajusten a la operación. Reintenta solo los errores que puedan ser transitorios, respeta las indicaciones de reintento del servidor y limita el número de intentos. No repitas errores de validación como si fueran fallos de red. Si se agota el presupuesto de reintentos, vuelve a una cola segura conocida o a una revisión humana en vez de elegir silenciosamente la primera opción.

Registra lo suficiente para diagnosticar el flujo: identificadores de correlación disponibles, IDs de preguntas, estado de la respuesta, resultado de la validación y rama de política elegida. No guardes claves API ni copies datos personales sin necesidad en los registros. Si necesitas conservar el estado original para auditorías, define deliberadamente la retención, los controles de acceso y la anonimización.

Despliega gradualmente

Un despliegue por etapas ayuda a separar la calidad del modelo de los errores de integración:

1. Explora: prueba estados representativos y preguntas tipadas en el Playground de Jev. Aclara los criterios ambiguos antes de escribir código de producción.
2. Evalúa sin conexión: ejecuta una muestra etiquetada a través del flujo de solicitud. Revisa las confusiones y los casos con mayor coste de negocio.
3. Ejecuta en sombra: registra las respuestas mientras el proceso existente sigue siendo la autoridad. Compara las sugerencias con los resultados reales sin realizar acciones.
4. Asiste al operador: muestra sugerencias a una persona y recoge sus correcciones. Así aparecen categorías ausentes y rúbricas confusas.
5. Automatiza de forma selectiva: activa solo las ramas que alcancen el umbral medido y tengan una alternativa segura. Debe ser posible pausar la automatización cuando cambie el patrón de entrada.

Versiona el texto de las preguntas y sus criterios junto con el código que interpreta las respuestas. Si cambias el significado de critical o añades un equipo de destino, el conjunto de evaluación debe cubrir el nuevo comportamiento antes del despliegue. Vigila la mezcla de entradas, las correcciones, las tasas de escalamiento y los resultados posteriores; un esquema estable no garantiza un rendimiento estable.

Errores de integración frecuentes

Confiar en una aserción de TypeScript. Una aserción cambia lo que cree el compilador, no los datos que envió el servidor. Empieza desde unknown, valida los campos usados y rechaza los tipos de respuesta inesperados.

Hacer preguntas compuestas. “Elige un equipo, determina la urgencia y decide si corresponde un reembolso” agrupa juicios distintos. Usa identificadores de pregunta claros y combina las respuestas con código normal. Las reglas estrictas de elegibilidad deben seguir siendo deterministas.

Forzar una opción cuando ninguna encaja. Los criterios incompletos fomentan una respuesta aproximada pero incorrecta. Añade una opción de reserva o envía los casos inciertos a revisión.

Confundir probabilidad con permiso. La probabilidad es una señal para una política, no la política misma. La autenticación, la autorización, los límites de solicitudes y las comprobaciones para acciones irreversibles pertenecen a tu servicio.

Enviar el registro completo. Más contexto no siempre es mejor. Incluye solo la información necesaria para las preguntas definidas, especialmente cuando el estado contiene datos personales o confidenciales.

Lista de verificación para una integración de Jev TypeSafe en producción

• Guarda la clave API en un almacén de secretos del servidor y rótala según la política de tu organización.
• Envía solo texto o campos estructurados pertinentes; elimina datos personales y secretos que no hagan falta.
• Prueba casos rutinarios, ambiguos, adversariales y fuera de alcance en el Playground y en un conjunto de evaluación sin conexión.
• Valida el tipo de respuesta, los campos obligatorios, los rangos, la suma de probabilidades y las listas permitidas de la aplicación.
• Define tiempos de espera, reintentos limitados, gestión de respuestas no exitosas y una ruta segura de fallback.
• Registra los resultados de validación y de política sin guardar credenciales ni datos sensibles innecesarios.
• Revisa los umbrales y criterios cuando cambien la distribución de entradas o el coste del error.

Consulta la documentación de la API de Jev para conocer los campos actuales de solicitud y respuesta. Revisa los planes y el uso antes de estimar el volumen de producción.

Preguntas frecuentes

¿Jev TypeSafe es lo mismo que TypeScript?

No. Jev devuelve decisiones tipadas, como una opción, una puntuación o una probabilidad de sí. TypeScript comprueba el código de la aplicación antes de ejecutarlo. Una integración sólida usa ambos: tipa la solicitud y el resultado interno, y valida en tiempo de ejecución los datos de red no confiables.

¿Un tipo de TypeScript valida una respuesta de API?

No. Las anotaciones de tipos desaparecen cuando se ejecuta JavaScript. Trata la respuesta descodificada como unknown y comprueba cada campo que la aplicación usa antes de enrutar, guardar o mostrar datos. Un guard de tipo permite estrechar el tipo después de la validación.

¿Varias preguntas pueden compartir el mismo estado?

Sí. Jev puede evaluar en paralelo varias preguntas tipadas sobre un mismo estado. Mantén cada pregunta acotada y asígnale una clave estable para que el código lea cada respuesta de forma independiente. Las preguntas separadas son más fáciles de probar y combinar que un único prompt con una decisión anidada grande.

¿Noul es confianza?

No. Noul es la probabilidad de que una proposición sea verdadera. Choice y Score incluyen confianza además de las probabilidades de sus respuestas. Lee el campo que corresponda al tipo de pregunta y define los umbrales a partir de ejemplos medidos.

¿Puede Jev ejecutar la acción después de decidir?

La ejecución debe pertenecer a tu aplicación. Usa Jev para evaluar una pregunta delimitada y deja que tus comprobaciones de autorización, listas permitidas, reglas deterministas y pasos de aprobación decidan si se procede. Así una respuesta incierta del modelo no se convierte en un efecto secundario sin validar.

¿Cuál es un buen primer caso de uso?

Empieza con una decisión repetida, de bajo impacto y con pocas respuestas posibles, como sugerir un equipo de soporte. Prepara ejemplos etiquetados, define qué significa cada resultado y decide cómo tratar los casos desconocidos. Cuando el flujo sea medible, añade validación en ejecución y compara las sugerencias con el proceso actual antes de automatizar.

Resumen

El significado práctico de jev typesafe es mantener un límite claro entre la decisión estructurada de un modelo y la lógica de la aplicación que la consume. Define preguntas acotadas, envía solo el estado pertinente, valida cada respuesta en tiempo de ejecución, mide el comportamiento con ejemplos representativos y conserva una ruta explícita de revisión para los casos inciertos o de alto impacto. TypeScript hace que tu propio código sea más fácil de razonar; las comprobaciones en ejecución lo protegen de datos no confiables.