Formas alternativas de instalación: uv, npm y conexión directa a la API con curl
La lección anterior recorrió la ruta principal con venv + pip, pero la instalación del SDK TypeSafe no tiene una sola vía: el inicio rápido oficial ofrece además tres alternativas: uv, el SDK de JavaScript / TypeScript y la conexión directa en Bash. En esta lección recorreremos las tres: en 8 minutos, elige la que convenga a tu proyecto.
Qué podrás hacer al terminar
- Completar la instalación del SDK TypeSafe con dos comandos de uv y bloquear las dependencias en
uv.lock - Instalar el SDK de Jev JavaScript con npm (
@typesafe-ai/sdk) y ejecutar el mismo ejemplo de las tres preguntas del ticket de la lección anterior - Ejecutar el mismo código directamente en TypeScript (Node.js 22.18+)
- Conectarte directamente a la API de TypeSafe con curl 7.76+ y ver una línea completa de respuesta JSON sin procesar
- Nombrar los requisitos de versión de cada una de las tres rutas y elegir la adecuada para tu proyecto
Tu situación actual
- El proyecto ya usa uv; volver a venv + pip es como ir marcha atrás
- Nuestro stack tecnológico es todo Node / TypeScript; montar un entorno Python completo para una llamada a la API no vale la pena
- Aún no has decidido qué SDK usar y quieres ver primero con curl qué devuelve realmente la API antes de empezar
Cuándo usar este método
Cuando necesitas:
- Añadir Jev en un proyecto Python gestionado con uv
- Llamar a Jev desde un proyecto Node.js, frontend o TypeScript
- Hacer llamadas HTTP directas desde cualquier lenguaje (para verificar el resultado primero, o cuando no hay SDK oficial para tu lenguaje)
Y no quieres:
- Ejecutar manualmente
python3 -m venvy luegopip install - Instalar un SDK completo solo para una solicitud curl
🎒 Preparativos antes de empezar
- has completado Instalación y primera solicitud — esta lección reutiliza el mismo ejemplo de
route_ticket.py - tienes la Key en las variables de entorno:
echo $TYPESAFE_API_KEYla imprime en la terminal (si no, vuelve a Registro y API Key) - prepara lo necesario según la ruta que vayas a tomar: Python 3.10+ (ruta uv), Node.js 22+ (ruta npm), curl 7.76+ (ruta curl)
- usas Bash en la línea de comandos (macOS / Linux / Windows WSL — los comandos del inicio rápido oficial están escritos para este entorno)
Idea central
La sección «escribe código para enviar tu primera solicitud» del inicio rápido oficial ofrece cuatro pestañas: Python, JavaScript, TypeScript y Bash. La lección anterior recorrió la ruta de Python con venv + pip; en esta completaremos las restantes.
Comparación de las tres rutas alternativas:
| Ruta | Qué instala | Requisitos de versión | Para quién |
|---|---|---|---|
| uv | typesafe-sdk (el mismo paquete que pip) | Python 3.10+, requiere instalar uv | Proyectos Python que ya usan o quieren usar uv |
| npm | @typesafe-ai/sdk | Node.js 22+ (TS directo 22.18+) | Proyectos Node, frontend y TypeScript |
| curl | no instala nada | curl 7.76+ | Cualquier lenguaje; verificación rápida de la respuesta de la API |
Las tres rutas llaman al mismo endpoint: POST https://api.typesafe.ai/v1/systemone, y la autenticación es siempre Authorization: Bearer <Key>. La única diferencia está en «quién envuelve el HTTP por ti».
El SDK hace tres cosas por ti que, en la conexión directa, debes hacer tú mismo:
| Tarea | Lo que hace el SDK | Con conexión directa por curl |
|---|---|---|
| Autenticación | lee automáticamente TYPESAFE_API_KEY y arma el encabezado | escribirlo a mano -H "Authorization: Bearer $TYPESAFE_API_KEY" |
| Reintentos ante límite de peticiones | 429 / 529 reintenta por defecto con retroceso exponencial | escribirlo tú mismo (la página oficial de errors exige retroceso exponencial) |
| Formato de envío y recepción | estado y preguntas envueltos en clases, respuestas obtenidas por ID | armar el JSON tú mismo y analizar el JSON tú mismo |
Hazlo conmigo
Las tres rutas son independientes entre sí; elige una según tu lenguaje (la comparación está en la tabla de arriba); la numeración de los pasos es continua, para facilitar referencias cruzadas.
Paso 1: completar la instalación del SDK TypeSafe con uv
Por qué: uv es el método de instalación que aparece junto a pip en el inicio rápido oficial; dos comandos crean el proyecto + instalan el SDK, y además generan automáticamente un archivo de bloqueo multiplataforma uv.lock.
Primero confirma si uv está instalado:
uv --versionSi no lo tienes, usa el script oficial de instalación (macOS / Linux):
curl -LsSf https://astral.sh/uv/install.sh | shInstala el SDK. Ejecuta en el directorio del proyecto:
uv init --bare
uv add typesafe-sdkDeberías ver: ninguno de los dos comandos da errores; el segundo muestra una salida similar a Installed 14 packages, con una línea typesafe-sdk==0.7.5 en la lista (el número de versión es el que tengas al instalar). En el directorio aparecen .venv/ y uv.lock, y en el dependencies de pyproject.toml aparece "typesafe-sdk>=0.7.5".
- En el directorio del proyecto aparecen
.venv/yuv.lock
Ejecuta el ejemplo de la lección anterior, sin activar ningún entorno:
uv run route_ticket.pyDeberías ver: las mismas tres líneas que en la lección anterior:
technical
0.67
0.99route_ticket.py es exactamente el ejemplo oficial de la lección anterior; basta con copiarlo tal cual (el código está en Instalación y primera solicitud).
Tres detalles sobre la ruta con uv (según la documentación oficial de uv):
| Detalle | Explicación |
|---|---|
uv init --bare | solo genera pyproject.toml, no crea directorio src, README ni git; suficiente para arrancar rápido |
.venv | uv gestiona el entorno virtual junto a pyproject.toml; uv run garantiza automáticamente que esté sincronizado con el archivo de bloqueo. También se puede usar directamente .venv/bin/python route_ticket.py |
uv.lock | fija versiones exactas; la recomendación oficial es incluirlo en el control de versiones, para poder reproducir el mismo conjunto de dependencias en otra máquina |
Paso 2: instalar con npm el Jev JavaScript SDK y ejecutar el ejemplo
Por qué: el SDK de JavaScript / TypeScript es uno de los dos SDK cliente oficiales; usa el mismo estilo «state + questions» que el SDK de Python, y además el tipo de las respuestas se infiere automáticamente a partir de la definición de las preguntas.
Primero verifica la versión de Node; aquí hay una trampa fácil de pisar:
node --versionLa pestaña de JavaScript del inicio rápido oficial dice «Node.js 20 or later», pero ese es el criterio de una versión antigua: la página de documentación del SDK y el registro de cambios dicen Node.js 22 or newer (cambios de ruptura a partir de la v0.7.0), y el campo engines del paquete npm también es >=22. Toma como referencia 22+ (detalles en el aviso de trampas de abajo).
Instala el SDK:
npm install @typesafe-ai/sdk
npm pkg set type=moduleEl segundo comando marca el proyecto como ES module; el ejemplo oficial usa sintaxis import, y sin configurarlo Node daría un error al cargar.
Deberías ver: el primero muestra added 1 package; en el directorio aparecen node_modules/, package.json, package-lock.json. En package.json aparece "@typesafe-ai/sdk": "^0.7.0", y tras ejecutar el segundo aparece además "type": "module".
Crea con un editor route_ticket.js y pega el ejemplo oficial:
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
const 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.";
const client = new TypeSafeClient({ defaultModel: "jev-latest" }); // Reads TYPESAFE_API_KEY.
const response = await client.systemOne({
state: ticket,
questions: {
department: choice("Which team should handle this", {
billing: "Payment or subscription issues",
technical: "Bugs or integration problems",
sales: "Pricing or account questions",
}),
frustration: score("How frustrated the customer appears", [
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
]),
is_urgent: noul("The message conveys urgency or time-sensitivity"),
},
});
console.log(response.answers.department.choice);
console.log(response.answers.frustration.score);
console.log(response.answers.is_urgent.noul);Ejecútalo:
node route_ticket.jsDeberías ver: tres líneas de salida, igual que en la ruta de Python:
technical
0.67
0.99node route_ticket.jsimprimetechnical/0.67/0.99
Ejecutar directamente con TypeScript (opcional)
El mismo código, guardado tal cual como route_ticket.ts (el contenido es idéntico a route_ticket.js), directamente:
node route_ticket.tsDeberías ver: las mismas tres líneas de salida. Esto requiere Node.js 22.18 o superior (soporte para ejecutar TypeScript directamente); además, el SDK infiere el tipo de las respuestas a partir de tu definición de preguntas: el tipo de response.answers.department.choice es "billing" | "technical" | "sales", y el autocompletado del editor funciona de inmediato.
Paso 3: conectarse directamente con curl a la API de TypeSafe
Por qué: el ejemplo de Bash del inicio rápido oficial es precisamente «una solicitud HTTP completa sin SDK». Cualquier lenguaje capaz de enviar HTTP (Go, Java, Rust…) puede llamar a Jev siguiendo esta estructura; también sirve para verificar primero la respuesta de la API antes de decidir si instalar el SDK.
Crea con un editor route_ticket.sh y pega el ejemplo oficial:
#!/usr/bin/env bash
set -euo pipefail
: "${TYPESAFE_API_KEY:?Set TYPESAFE_API_KEY first.}"
curl --fail-with-body --silent --show-error \
https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"state": "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.",
"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"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated the customer appears",
"criteria": [
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language"
]
},
"is_urgent": {
"type": "noul",
"instructions": "The message conveys urgency or time-sensitivity"
}
}
}
JSONEjecútalo:
bash route_ticket.shDeberías ver: una línea entera de JSON sin procesar; a diferencia de los tres valores que imprime la ruta con SDK, esta es la respuesta completa, que incluye el confidence y las probabilities de cada respuesta, así como la medición de usage. El ejemplo completo formateado está en el apartado «Leer la respuesta completa» de la lección anterior; no se repite el significado de los campos: Instalación y primera solicitud.
Si no se ha configurado la Key, el script lo intercepta primero en local: route_ticket.sh: line 3: TYPESAFE_API_KEY: Set TYPESAFE_API_KEY first.; esa es la función de la línea de guarda de la línea 3 del inicio, para no enviar una Key vacía al servidor en vano.
bash route_ticket.shimprimió una línea entera de JSON, con"answers"dentro
Dos avisos sobre la ruta con curl:
| Ítem | Explicación |
|---|---|
--fail-with-body | requiere curl 7.76+: ante un error HTTP el código de salida es distinto de 0, pero aun así imprime el cuerpo de la respuesta, lo que facilita ver dónde está el error |
429 / 529 | la conexión directa exige escribir por tu cuenta los reintentos con retroceso exponencial (los SDK los traen por defecto); si recibes uno, mira el cuerpo de la respuesta, espera un momento y vuelve a enviar |
Punto de control ✅
- Ruta con uv: están los tres elementos
.venv/,uv.lock,pyproject.toml, yuv run route_ticket.pymuestra tres líneas de respuestas - Ruta con npm:
package.jsoncontiene a la vez"@typesafe-ai/sdk"y"type": "module" - Ruta con curl:
bash route_ticket.shimprime una línea entera de JSON, conanswersdentro - Sé que las tres rutas llaman al mismo endpoint:
POST /v1/systemone - Sé los umbrales de versión: Python 3.10+ / Node 22+ (ejecución directa de TS 22.18+) / curl 7.76+
Aviso de trampas
❌ npm pkg set type=module da npm error code ENOENT
Síntoma: al ejecutar npm pkg set type=module directamente en un directorio vacío, da el error Could not read package.json ... no such file or directory.
Causa: npm pkg set es un comando que «modifica package.json»; si el directorio aún no tiene ese archivo, no lo creará por ti (probado en npm 10.9.7).
Forma correcta: sigue el orden oficial: primero npm install @typesafe-ai/sdk (npm genera automáticamente package.json), luego npm pkg set type=module.
❌ node lanza Warning: Failed to load the ES module
Síntoma: al ejecutar node route_ticket.js, reporta Failed to load the ES module: route_ticket.js. Make sure to set "type": "module" in the nearest package.json file or use the .mjs extension.
Causa: el proyecto no está marcado como ES module (o se configuró como commonjs), mientras que el ejemplo oficial usa la sintaxis import.
Forma correcta: npm pkg set type=module; o, siguiendo la sugerencia del error, cambia la extensión del archivo a .mjs.
❌ Preparaste el entorno según «Node 20+», pero instalaste la nueva versión del SDK que requiere 22+
Causa: la pestaña JavaScript de la página oficial de inicio rápido dice «Node.js 20 or later», pero la última versión del SDK en npm (0.7.0) tiene engines como node >=22, y en el registro de cambios la v0.7.0 también indica claramente un cambio disruptivo: «require Node.js 22 or newer». Históricamente, 0.5.7 / 0.6.0 sí soportaban 20+; esa frase del inicio rápido corresponde a versiones antiguas.
Forma correcta: verifica primero con node --version; si no llega a 22, actualiza Node o cambia a la ruta con uv y curl de esta lección.
❌ Tras uv add, al usar python route_ticket.py sigue apareciendo ModuleNotFoundError
Causa: el python del sistema no es el entorno gestionado por uv; el SDK está instalado en el .venv del proyecto.
Forma correcta: como en el ejemplo oficial, usa uniformemente uv run route_ticket.py (primero se asegura de que .venv esté sincronizado con el lockfile); o especifica explícitamente .venv/bin/python route_ticket.py.
Técnicas avanzadas (opcional)
El SDK también gestiona la compresión por ti. A partir de la v0.7.5, el SDK de Python usa por defecto compresión zstd para el cuerpo de las peticiones; el SDK de JavaScript en Node 22.15+ comprime automáticamente cuerpos de más de 1 KiB, y para desactivarlo pasa compression: false. En Python 3.13 y versiones anteriores hay que añadir extras explícitamente: uv add "typesafe-sdk[zstd]" (además hay otros dos extras: http2 y pil).
Lenguajes sin SDK oficial. Go, Java, Rust… basta con enviar POST /v1/systemone siguiendo la estructura del paso 3; las definiciones de los campos state / questions / answers se ven en la referencia rápida de la API.
Antes de llevar la conexión directa a producción. Envuelve los reintentos con retroceso exponencial de 429 / 529 en tu cliente HTTP: es un requisito explícito de la página oficial de errors para usuarios de conexión directa; con la ruta del SDK no hay que ocuparse de esto.
Resumen de la lección
✅ Ruta uv: uv init --bare + uv add typesafe-sdk, dos comandos para completar la instalación del SDK de TypeSafe, y con uv run se ejecuta directamente.
✅ Ruta npm: npm install @typesafe-ai/sdk + npm pkg set type=module, JavaScript y TypeScript (con 22.18+ se ejecuta directamente) hacen funcionar el mismo ejemplo.
✅ Ruta curl: --fail-with-body para conectarse directamente a la API y ver el JSON crudo completo con confidence y probabilities.
Repaso de los campos de configuración clave:
| Campo | Valor recomendado | Explicación |
|---|---|---|
| Nombre del paquete Python | typesafe-sdk | El mismo paquete para pip / uv; uv add typesafe-sdk |
| Nombre del paquete JS | @typesafe-ai/sdk | Instalación con npm; desde la v0.7.0 requiere Node 22+ |
| ES module | type=module | Los ejemplos oficiales JS / TS usan import; hay que configurarlo |
| Endpoint | POST https://api.typesafe.ai/v1/systemone | Compartido por las tres rutas |
| Autenticación | Authorization: Bearer <Key> | El SDK la incluye automáticamente; curl usa $TYPESAFE_API_KEY |
| Variable de entorno | TYPESAFE_API_KEY | Compartida por las tres rutas; no escribas la clave en el código |
Avance de la próxima lección
Con las tres rutas funcionando, falta el último paso de respaldo: ¿Qué hacer si no se instala o no se ejecuta: solución de problemas iniciales.
Aprenderás:
- A localizar en 60 segundos, con 3 comandos, si el problema está en el entorno, la Key o la red
400/401/413/422/429: qué significa cada código de estado y cómo manejarlo- Qué errores reintenta automáticamente el SDK (
429/529) y cómo escribirlo tú mismo en la conexión directa - Al preguntar, cómo incluir el
request_idy un código mínimo de reproducción del error