Skip to content

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 venv y luego pip 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_KEY la 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:

RutaQué instalaRequisitos de versiónPara quién
uvtypesafe-sdk (el mismo paquete que pip)Python 3.10+, requiere instalar uvProyectos Python que ya usan o quieren usar uv
npm@typesafe-ai/sdkNode.js 22+ (TS directo 22.18+)Proyectos Node, frontend y TypeScript
curlno instala nadacurl 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:

TareaLo que hace el SDKCon conexión directa por curl
Autenticaciónlee automáticamente TYPESAFE_API_KEY y arma el encabezadoescribirlo a mano -H "Authorization: Bearer $TYPESAFE_API_KEY"
Reintentos ante límite de peticiones429 / 529 reintenta por defecto con retroceso exponencialescribirlo tú mismo (la página oficial de errors exige retroceso exponencial)
Formato de envío y recepciónestado y preguntas envueltos en clases, respuestas obtenidas por IDarmar 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:

bash
uv --version

Si no lo tienes, usa el script oficial de instalación (macOS / Linux):

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

Instala el SDK. Ejecuta en el directorio del proyecto:

bash
uv init --bare
uv add typesafe-sdk

Deberí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/ y uv.lock

Ejecuta el ejemplo de la lección anterior, sin activar ningún entorno:

bash
uv run route_ticket.py

Deberías ver: las mismas tres líneas que en la lección anterior:

text
technical
0.67
0.99

route_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):

DetalleExplicación
uv init --baresolo genera pyproject.toml, no crea directorio src, README ni git; suficiente para arrancar rápido
.venvuv 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.lockfija 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:

bash
node --version

La 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:

bash
npm install @typesafe-ai/sdk
npm pkg set type=module

El 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:

javascript
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:

bash
node route_ticket.js

Deberías ver: tres líneas de salida, igual que en la ruta de Python:

text
technical
0.67
0.99
  • node route_ticket.js imprime technical / 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:

bash
node route_ticket.ts

Deberí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:

bash
#!/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"
    }
  }
}
JSON

Ejecútalo:

bash
bash route_ticket.sh

Deberí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.sh imprimió una línea entera de JSON, con "answers" dentro

Dos avisos sobre la ruta con curl:

ÍtemExplicación
--fail-with-bodyrequiere 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 / 529la 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, y uv run route_ticket.py muestra tres líneas de respuestas
  • Ruta con npm: package.json contiene a la vez "@typesafe-ai/sdk" y "type": "module"
  • Ruta con curl: bash route_ticket.sh imprime una línea entera de JSON, con answers dentro
  • 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:

CampoValor recomendadoExplicación
Nombre del paquete Pythontypesafe-sdkEl mismo paquete para pip / uv; uv add typesafe-sdk
Nombre del paquete JS@typesafe-ai/sdkInstalación con npm; desde la v0.7.0 requiere Node 22+
ES moduletype=moduleLos ejemplos oficiales JS / TS usan import; hay que configurarlo
EndpointPOST https://api.typesafe.ai/v1/systemoneCompartido por las tres rutas
AutenticaciónAuthorization: Bearer <Key>El SDK la incluye automáticamente; curl usa $TYPESAFE_API_KEY
Variable de entornoTYPESAFE_API_KEYCompartida 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_id y un código mínimo de reproducción del error
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.