Tutorial de TypeSafe Jev paso a paso. Guía práctica de TypeSafe Jev, el modelo System One para decisiones de software tipadas.
01
Encuadre la tarea
Decide si Jev encaja
Jev no es un modelo de chat. Convierte el estado existente en una decisión cerrada de Elección, Puntuación o Noul y devuelve una distribución de probabilidad.
un buen ajuste
Utilice Jev para decisiones acotadas
Enrute una solicitud a una cola con nombre.
Colocar un registro en una escala ordenada de riesgo o calidad.
Estima si una condición claramente establecida es verdadera.
No encaja bien
Utilice un modelo generativo en su lugar
Escriba, resuma, traduzca o reescriba texto abierto.
Mantenga una conversación natural de varios turnos.
Cree una respuesta cuando los resultados válidos no se puedan nombrar de antemano.
El modelo mental oficial
STATE
Un estado para evaluar
Pase una cadena, objeto o matriz que contenga el texto y los hechos relacionados que necesita el juicio. Utilice campos de objetos con nombre para la mayoría de las solicitudes reales.
QUESTIONS
Un juicio rápido por pregunta
Cada pregunta debe plantear algo concreto que una persona con conocimientos pueda juzgar rápidamente a partir del estado proporcionado.
PARALLEL
Preguntas independientes en paralelo
Las preguntas de una solicitud ven el mismo estado, se ejecutan de forma independiente y no filtran una respuesta a otra.
CODE
Redactar respuestas en código
Pondere, umbral, bifurque y combine respuestas escritas en código normal en lugar de ocultar la lógica del flujo de trabajo en un solo mensaje.
Prueba de descomposición: Si el juicio sopesa varios factores independientes o requiere un razonamiento extenso, divídalo en preguntas atómicas y combine las respuestas en código.
Después de este capítulo:Puede separar las tareas de generación de contenido de las tareas de decisión estructurada.
Utilice Choice para etiquetas mutuamente excluyentes, Score para niveles ordenados y Noul para un juicio de verdadero o falso.
Tipo
tu suministras
tu recibes
Usar cuando
choice
Opciones con nombre → descripciones
Clave seleccionada + probabilidades por opción (+ confianza)
Etiquetas/rutas mutuamente excluyentes
score
Niveles ordenados (2 a 10), bajo → alto
Puntuación de nivel ponderada por probabilidad + problemas de peldaño
Rúbricas de gravedad, calidad y riesgo.
noul
Propuesta sí/no (+ criterios opcionales)
Probabilidad de verdadero
Verificaciones de hechos únicos
choiceHasta 255 opciones
Un ganador más la distribución completa.
Úselo para alternativas fijas y desordenadas. Agregue otro/ninguno cuando la lista no cubra todos los estados. El valor elegido es la opción de mayor probabilidad.
Los niveles están indexados desde 0. La puntuación es el promedio ponderado entre las probabilidades de nivel, por lo que puede caer entre dos niveles.
La probabilidad de que una afirmación sea verdadera.
Úselo para un juicio limpio de sí/no. Cerca de 0,5 significa incertidumbre, no una cantidad media de la propiedad. Noul no tiene un campo de confianza separado.
{
"type": "noul",
"noul": 0.95
}
La puntuación no es precisión. Una puntuación de 1,5 en una rúbrica de 0 a 2 es un nivel esperado, no un “75 % de acierto”. No trate la confianza en la puntuación o la elección como una promesa de precisión.
Después de este capítulo:Puede seleccionar la forma de respuesta correcta para enrutamiento, moderación y puntuación de riesgo.
Mantenga estables los nombres de las opciones, defina límites mutuamente excluyentes, incluya una ruta residual y asigne a cada pregunta una decisión.
Escribir criterios sólidos
Opciones disjuntas. Si dos claves de Elección pueden ser verdaderas, los operadores lucharán contra el modelo.
Describir los bordes. Diga qué incluye buy_intent (stock, envío) frente a price_question.
Mantenga el residuo al final. Utilice a otros/humanos como trampillas de escape, no como trampas perezosas.
Puntuación de orden ascendente. Las matrices de criterios son las más bajas → las más altas.
Una decisión por pregunta. Divida “ruta” de “urgencia” en claves separadas.
Anatomía de una pregunta.
question_id
Una clave de búsqueda de respuesta para su código. No se envía al modelo, por lo que las instrucciones aún deben contener la pregunta completa.
type
elección, puntuación o noul. Elija la forma sobre la que su código puede actuar directamente.
instructions
El juicio completo y específico. Puede ser una cadena, un objeto o una matriz y puede hacer referencia a rutas de estado con nombre.
criteria
Opciones de elección, niveles de puntuación ordenados o aclaración opcional de verdadero/falso para Noul.
Ejemplo · una decisión, límites separados
route: {
type: 'choice',
instructions: 'Route this ticket to one queue.',
criteria: {
tech: 'Bugs, outages, API failures, or integrations',
sales: 'Pricing, plans, demos, or new-purchase intent',
billing: 'Charges, invoices, receipts, or subscriptions',
human: 'Ambiguous, sensitive, legal, or multi-issue'
}
}
Estado de la estructura y campos exactos de referencia.
Mantenga evidencia en campos de estado con nombre y apunte instrucciones hacia ellos con rutas de puntos e índices. Esto reduce la ambigüedad sobre qué texto, registro o política debería controlar la respuesta.
const state = {
ticket: {
message: 'I was charged twice. Please refund the duplicate.',
orderId: 'A-104'
},
order: { charges: [49, 49] },
refundPolicy: 'Duplicate charges are eligible for a refund.'
};
const questions = {
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request a refund?'
},
policy_supports_refund: {
type: 'noul',
instructions: 'Does `refundPolicy` support the request given `order.charges`?'
}
};
Lote por defecto: Haga todas las preguntas que utilicen el mismo estado en una sola solicitud, incluso preguntas especulativas. Haga una segunda solicitud sólo cuando su estado u opciones realmente dependan de una respuesta anterior.
Después de este capítulo:Puede escribir una definición de pregunta estable y comprobable que el código pueda consumir.
Llame al punto final o SDK oficial de System One desde su servidor, inspeccione la respuesta escrita y maneje los errores de validación, límite de velocidad y sobrecarga. La puerta de enlace sigue siendo una ruta de acceso opcional.
Comience con el punto final HTTP oficial
Mantenga TYPESAFE_API_KEY en el servidor. Envíe el estado, el modelo y un mapa de las preguntas nombradas a POST /v1/systemone.
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Stripe has failed for 3 days. I am losing sales.",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"is_urgent": {
"type": "noul",
"instructions": "Does this message convey urgency?"
}
}
}'
Utilice el SDK oficial para respuestas escritas y reintentos
El SDK de Python lee TYPESAFE_API_KEY del entorno, por defecto es jev-latest, expone clases de preguntas/respuestas escritas y aplica su política de reintento predeterminada.
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"message": "Stripe has failed for 3 days.", "impact": "Losing sales"},
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"is_urgent": Noul(
instructions="Does `message` and `impact` convey urgency?"
),
},
)
department = response.answers["department"]
print(department.choice, department.confidence)
print(response.answers["is_urgent"].noul)
Clave API faltante o no válida. Verifique la ficha del portador.
422
Forma de solicitud no válida. Inspeccione la respuesta del campo infractor.
429
Se superó el límite de tarifa. Retroceda antes de volver a intentarlo.
529
Servicio temporalmente sobrecargado. Retroceda antes de volver a intentarlo.
Para 429 y 529, utilice un retroceso exponencial en lugar de un reintento inmediato. Los SDK oficiales hacen esto automáticamente según su política de reintento predeterminada.
Alternativa: Vercel AI Gateway
Este sitio también documenta Gateway como una capa de acceso para la evaluación del SDK de IA. Es una ruta de integración alternativa, que no forma parte de Jev ni TypeSafe.
import { experimental_evaluate as evaluate } from 'ai';
import { gateway } from '@ai-sdk/gateway';
const result = await evaluate({
model: gateway('typesafe-ai/jev'),
state,
questions,
});
Después de este capítulo:Puede conservar las credenciales del lado del servidor y recibir respuestas escritas con probabilidades.
No convierta la probabilidad máxima directamente en una acción final. Establezca bandas para sugerencias, confirmación y revisión humana según el riesgo empresarial.
PROBABILITY
Evidencia para cada opción o nivel
Choice y Score devuelven la distribución completa. Úselo cuando las opciones de segundo lugar, la ambigüedad o las medidas de incertidumbre personalizadas sean importantes.
CONFIDENCE
Un resumen de la forma de distribución.
La confianza comprime cuán concentrada o plana es la distribución en 0-1. No es lo mismo que la probabilidad de la opción seleccionada.
Noul: Noul ya devuelve P(verdadero), por lo que no tiene una confianza separada. Los valores cercanos a 0,5 son inciertos; umbral tanto del lado del sí como del no según el riesgo.
TypeSafe expone la confianza de la distribución de opciones. Una política práctica es:
01
Alta confianza
Sugiera automáticamente la elección (etiqueta, ruta o veredicto) en su interfaz de usuario.
02
Confianza media
Muestra la sugerencia, pero requiere que un operador la confirme antes de continuar.
03
Baja confianza
Enviar a una cola humana sin acción predeterminada.
Calibre los límites en ejemplos etiquetados de su flujo o bandeja de entrada. Los umbrales son específicos del caso de uso. Nunca transfiera sugerencias a dinero ni reembolse los efectos secundarios.
Umbral de la acción, no del modelo globalmente
action = response.answers["action"]
if action.confidence < 0.5:
route_to_human(state) # uncertain: do not guess
elif action.choice == "check_balance":
show_balance(account_id) # reversible, low stakes
elif action.choice == "approve_transfer":
if action.confidence > 0.9:
confirm_then_execute(account_id)
else:
ask_user_to_confirm(account_id) # higher stakes, higher bar
Calibrar antes de la automatización
Recopile ejemplos representativos y etiquetados del flujo de trabajo real.
Registre respuestas, distribuciones, confianza, latencia y la decisión humana.
Elija umbrales por separado para acciones reversibles, costosas e irreversibles.
Supervise la deriva y vuelva a evaluar después de cambiar el estado, las instrucciones, los criterios o el alias del modelo.
Consejos estatales
Pase una cadena, objeto o matriz como estado. Prefiera registros estructurados (texto de comentario + metadatos) a deshacerse de un registro de chat completo cuando solo importa un mensaje.
Después de este capítulo:Puede diseñar un respaldo de baja confianza y calibrar umbrales con datos etiquetados.
Cree un flujo de trabajo completo con estado estructurado, preguntas paralelas, política de propiedad de código, evidencia de auditoría, reintentos y un respaldo humano.
Cree un flujo de trabajo completo de clasificación de soporte
Envíe un estado de ticket estructurado y haga tres preguntas independientes en paralelo. Mantenga la política de rutas y seguridad en código.
STATE→CHOICESCORENOUL→POLICY
const questions = {
department: {
type: 'choice',
instructions: 'Which team should handle `ticket.message`?',
criteria: {
returns: 'Exchanges, wrong or damaged items',
shipping: 'Delivery status, delays, or lost packages',
billing: 'Charges, invoices, or payment problems',
other: 'None of the above'
}
},
frustration: {
type: 'score',
instructions: 'How frustrated is the customer?',
criteria: ['Calm', 'Concerned but civil', 'Very angry']
},
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request money back?'
}
};
Convierta las respuestas escritas en una decisión auditable
Mantenga las credenciales y las llamadas de modelo en el lado del servidor.
Valide el tamaño del estado, los campos obligatorios y las definiciones de las preguntas antes de llamar a la API.
Almacene la versión del modelo, la versión de la pregunta, las probabilidades, la confianza y la acción final.
Proporcione un camino humano/otro explícito y nunca invente un defecto de incertidumbre.
Vuelva a intentar 429 y 529 con retroceso exponencial limitado; no vuelva a intentar errores de validación.
Pruebe con casos extremos etiquetados y recalibre los umbrales antes de habilitar la automatización.
Case index
Six Jev patterns to explore next
These are research paths, not claims that this site built the projects. Each card opens the corresponding category in the open-source radar so you can inspect real implementations and source evidence.