Instala el SDK de Python y lanza tu primera solicitud: listo en 10 minutos
La clave ya la conseguiste en la lección anterior. En esta lección la vas a usar: completas la instalación de typesafe-sdk y ejecutas el ejemplo oficial: un ticket de cliente, una sola solicitud con tres preguntas a la vez, y obtienes las tres respuestas: «a qué grupo asignarlo, cuán frustrado está el cliente y si es urgente». Todo en 10 minutos.
Qué podrás hacer al terminar
- Completar la instalación de typesafe-sdk en un entorno virtual aislado (Python 3.10+)
- Ejecutar el ejemplo oficial de las tres preguntas sobre un ticket y ver las tres líneas de salida
technical/0.67/0.99 - Entender el
choice,score,nouldel JSON devuelto, así comoconfidence,probabilities - Saber que el SDK lee automáticamente las variables de entorno y gestiona automáticamente los reintentos por límite de peticiones, sin escribir la clave en el código
- Saber a qué lección ir a diagnosticar si algo no funciona
Tu situación actual
- Ya tienes la Key, pero tras instalar con pip el import da error y no distingues si es un problema de la versión de Python o del entorno
- El ejemplo se ejecuta, pero la salida es un montón de JSON y no sabes cuál campo es «la respuesta»
- Quieres primero que funcione, sin ponerte a estudiar toda la documentación de la API de entrada
Cuándo usar esta técnica
Cuando necesitas:
- Llamar a Jev con Python desde tu propia computadora y hacer funcionar tu primera solicitud real
- Una forma de instalación limpia que no contamine el Python del sistema
Y no quieres:
- Instalar el SDK en el Python del sistema y que choque con otros proyectos
- Ponerte a escribir a mano solicitudes HTTP, cabeceras de autenticación y lógica de reintentos desde el principio
🎒 Preparativos antes de empezar
- La Key de la lección anterior ya está guardada en la variable de entorno
TYPESAFE_API_KEY - Python 3.10 o superior (requisito de versión del SDK oficial; puedes comprobarlo en la terminal con
python3 --version) - pip ya instalado (la documentación oficial enlaza a la página oficial de instalación de pip; si no lo tienes, instálalo primero)
- Línea de comandos con Bash (macOS / Linux / Windows WSL: los comandos del inicio rápido oficial están escritos para este entorno)
Idea central
Qué se instala. El nombre del paquete pip del SDK oficial de Python es typesafe-sdk, y el nombre para importar es typesafe_sdk. Encapsula todo lo de «construir la solicitud HTTP, autenticación, compresión, reintentos por límite de peticiones»; tú solo escribes el state y las preguntas.
Por qué usar venv. La ruta con pip del inicio rápido oficial es precisamente «venv + pip»: el entorno virtual instala el SDK en el .venv del directorio del proyecto, sin tocar el Python del sistema; borrar la carpeta equivale a una desinstalación limpia.
Cómo es la primera solicitud. El ejemplo oficial toma un ticket de cliente como state y, en una sola solicitud, hace tres preguntas:
| Pregunta | Tipo de pregunta | Campo devuelto |
|---|---|---|
| A qué grupo debe ir este ticket | Choice | choice + probabilities de cada opción + confidence |
| Cuán frustrado suena el cliente | Score | (score, 0–2, puede caer entre dos niveles) + confidence |
| Si es urgente | Noul | (noul, 0–1 de probabilidad) |
Las tres preguntas se evalúan en paralelo sobre el mismo state y se devuelven todas de una vez: esta es la forma de trabajo central de Jev; más adelante, la lección preguntas en paralelo lo llevará al extremo.
El SDK hace tres cosas por ti.
| Tarea | Cómo lo hace el SDK |
|---|---|
| Autenticación | Lee automáticamente la variable de entorno TYPESAFE_API_KEY |
| Elegir modelo | model="jev-latest"; si no se especifica, el SDK usa por defecto también jev-latest (apunta actualmente a Jev 1.14) |
| Reintentos por límite de peticiones | Ante un 429 reintenta automáticamente por defecto, con tiempos de espera cada vez más largos, y respeta retry-after |
El criterio de que funciona. La salida esperada del ejemplo oficial son tres líneas:
technical
0.67
0.99La documentación oficial advierte también: estos son resultados de ejemplo y los valores pueden cambiar según la versión de Jev.
Hazlo conmigo
Paso 1: crea el directorio del proyecto y verifica las variables de entorno
Por qué: el inicio rápido oficial parte de un directorio limpio; la Key debe estar en las variables de entorno para que el SDK pueda leerla automáticamente.
mkdir typesafe-quickstart
cd typesafe-quickstart
export TYPESAFE_API_KEY="your-api-key"Sustituye your-api-key por tu Key (si la guardaste en la lección anterior, en una terminal recién abierta tienes que volver a hacer export).
Deberías ver: los tres comandos terminan sin errores; echo $TYPESAFE_API_KEY imprime tu Key.
Paso 2: completar la instalación de typesafe-sdk (venv + pip)
Por qué: venv instala el SDK en el directorio .venv propio del proyecto, sin contaminar el Python del sistema; es la práctica estándar de la ruta oficial con pip.
python3 -m venv .venv
.venv/bin/pip install typesafe-sdkDeberías ver: pip lista los paquetes a instalar y muestra que la instalación fue exitosa, y typesafe-sdk aparece en la lista de paquetes.
- En la carpeta del proyecto apareció el directorio
.venv
💡 Para quienes están acostumbrados a uv
La ruta con uv también está soportada oficialmente: uv init --bare y después uv add typesafe-sdk. El procedimiento completo para uv, npm y la conexión directa con curl está en la lección Formas alternativas de instalación.
Paso 3: escribir el ejemplo oficial route_ticket.py
Por qué: primero haz funcionar el ejemplo oficial tal cual y luego cámbialo por tu propio contenido; así, al depurar, siempre tienes una línea base «conocida como correcta».
Con tu editor crea route_ticket.py en el directorio del proyecto y pega el ejemplo completo del inicio rápido oficial:
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed."
with TypeSafeClient(model="jev-latest") as client: # Reads TYPESAFE_API_KEY.
response = client.system_one(
state=ticket,
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",
},
),
"frustration": Score(
instructions="How frustrated the customer appears",
criteria=[
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
],
),
"is_urgent": Noul(
instructions="The message conveys urgency or time-sensitivity",
),
},
)
print(response.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)Deberías ver: el archivo guardado en typesafe-quickstart/route_ticket.py.
Paso 4: ejecutarlo y obtener las tres respuestas
Por qué: este paso es el objetivo de toda la lección: tu primera llamada real a Jev.
.venv/bin/python route_ticket.pyUsa .venv/bin/python en lugar del python del sistema, para asegurarte de usar el entorno donde acabas de instalar el SDK.
Deberías ver: tres líneas de salida —
technical
0.67
0.99- Veo tres líneas de salida, la primera es
technical(el ticket se asigna al equipo técnico)
Paso 5: entender la respuesta completa
Por qué: print solo imprimió tres valores; en un proyecto real probablemente usarás probabilities y confidence para escribir lógica de ramificación.
La respuesta JSON completa que da el inicio rápido oficial (valores de ejemplo, cambian según la versión):
Respuesta JSON completa del ejemplo oficial
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"confidence": 1.0,
"probabilities": {
"technical": 1.0,
"billing": 0.0,
"sales": 0.0
}
},
"frustration": {
"type": "score",
"score": 0.67,
"confidence": 0.5,
"legend": {
"0": "Calm, just stating facts",
"1": "Frustrated but civil",
"2": "Very angry, strong language"
},
"probabilities": {
"0": 0.33,
"1": 0.67,
"2": 0.0
}
},
"is_urgent": {
"type": "noul",
"noul": 0.99
}
},
"usage": {
"input_tokens": 428,
"output_tokens": 73
}
}Tres puntos que vale la pena notar:
| Campo | Dónde | Significado |
|---|---|---|
confidence | En la respuesta de Choice / Score | El grado de certeza del modelo sobre esa respuesta (la respuesta de Noul no tiene este campo) |
probabilities | En cada respuesta | Distribución de probabilidades completa: department apuesta al 100% por technical |
usage | En el nivel superior | Consumo de esta llamada: 428 token de entrada, 73 token de salida (la facturación se calcula por la entrada, la salida es gratis) |
El "model": "jev-1.13.0" del JSON de ejemplo es el valor registrado cuando se redactó el ejemplo de la documentación oficial; si ejecutas jev-latest ahora, el campo model de la respuesta depende de la versión vigente del modelo. Cómo usar confidence para escribir ramificaciones se explica en detalle en la lección Confianza (confidence).
Punto de control ✅
- typesafe-sdk está instalado en
.venv, no en el Python del sistema - En mi código no aparece la API Key (el SDK lee la variable de entorno automáticamente)
- Obtuve las tres líneas de salida y sé que son, respectivamente, las respuestas de Choice / Score / Noul
- Sé que las respuestas se guardan por ID de pregunta en
response.choices/.scores/.nouls - Sé que los valores del ejemplo pueden cambiar según la versión, no hace falta obsesionarse con si es 0.67 o 0.66
Aviso de errores comunes
❌ ModuleNotFoundError: No module named 'typesafe_sdk'
El paquete no está instalado en el Python que estás usando. Causa más común: ejecutaste con el python del sistema un proyecto instalado en .venv. Forma correcta: según el ejemplo oficial, ejecuta con .venv/bin/python route_ticket.py; quienes prefieren activar el entorno primero, tras source .venv/bin/activate también pueden usar python (uso genérico de venv; el ejemplo oficial no sigue ese paso).
❌ Versión de Python inferior a 3.10
El SDK oficial requiere Python 3.10 o superior. Compruébalo con python3 --version; si la versión es más baja, primero actualiza Python, o recrea el venv con un intérprete 3.10+.
❌ Funcionó, pero los valores no coinciden con 0.67 / 0.99
No está roto: la documentación oficial dice claramente que los resultados del ejemplo varían según la versión de Jev. Fíjate en si la estructura es correcta: la primera línea es una de billing / technical / sales, la segunda es un número de 0–2, la tercera un número de 0–1. Si la estructura es correcta, funcionó.
❌ Modifiqué el ejemplo y ya no funciona, no sé qué rompí
Vuelve a la línea base: primero haz funcionar el ejemplo oficial tal cual y luego cambia paso a paso — primero el texto de state, luego las preguntas y al final el tipo de pregunta, ejecutando tras cada cambio. Si de verdad te atascas, la lección Depuración inicial explica cada error uno por uno.
Técnicas avanzadas (opcional)
Dos conjuntos de clientes, síncrono y asíncrono. El SDK ofrece a la vez TypeSafeClient (síncrono, el usado en esta lección) y AsyncTypeSafeClient (asíncrono), con interfaces del mismo nombre (system_one); para escenarios de alta concurrencia cambia a la versión asíncrona.
El SDK tiene componentes adicionales opcionales. Al instalar puedes incluir extras: http2 habilita soporte HTTP/2, pil envía imágenes Pillow, zstd comprime el cuerpo de la petición en Python 3.13 y versiones anteriores. Lo relacionado con imágenes se trata en la lección Box e imágenes.
¿No quieres usar Python? El SDK de JavaScript / TypeScript y la conexión directa a la API con curl se explican en la lección Formas alternativas de instalación.
Resumen de la lección
✅ typesafe-sdk instalado: venv + pip, instalado en el .venv del proyecto, Python 3.10+.
✅ Primera solicitud completada: un ticket, tres preguntas, una sola respuesta——technical / 0.67 / 0.99.
✅ Ya sabes leer la respuesta: las respuestas se guardan por ID de pregunta en choices / scores / nouls, con probabilidades y confidence incluidos.
Repaso de los campos de configuración clave:
| Campo | Valor recomendado | Descripción |
|---|---|---|
| Nombre del paquete | typesafe-sdk | Nombre para instalar con pip; el nombre para import es typesafe_sdk |
model | jev-latest | Alias, actualmente apunta a Jev 1.14; si no se especifica, el SDK también lo usa por defecto |
state | Cadena / objeto JSON / arreglo de textos | En esta lección se usó una cadena de ticket |
questions | {ID: Choice/Score/Noul(...)} | El ID lo eliges tú; las respuestas se obtienen por ID desde choices / scores / nouls |
| Variable de entorno | TYPESAFE_API_KEY | El SDK la lee automáticamente, no se escribe la clave en el código |
Avance de la próxima lección
Python no es la única ruta: Instalación por métodos alternativos: uv, npm y conexión directa a la API con curl.
Aprenderás:
- Instalar el mismo SDK con uv en dos o tres comandos
- Ejecutar el mismo ejemplo en Node.js 20+ con
@typesafe-ai/sdk - Conectarte directamente a la API con curl 7.76+ y ver cómo es el JSON en bruto
- Elegir qué ruta según la situación de tu proyecto