Hay un momento en el que un prompt deja de bastar.
No porque el modelo “no entienda”, sino porque tu sistema necesita algo que un párrafo libre no te da: una decisión con forma. ¿Este ticket es urgente? ¿Va a facturación o a técnico? ¿El lead es débil o es alguien con presupuesto y fecha?
Si la respuesta llega como texto, tú vuelves a interpretar. Si llega como un número, una categoría o una posición en una escala, el resto del sistema puede actuar.
Eso es lo que resuelve TypeSafe AI: no te pide que “converses” con el modelo. Te pide que formules preguntas tipadas sobre un estado (un ticket, un correo, un lead) y te devuelve respuestas validadas, listas para usar en código.
Este notebook es un tutorial. Vamos a recorrer los tres primitivos —Noul, Choice y Score—, cómo combinarlos en una sola llamada, el cliente asíncrono, reintentos y un caso real de enrutado de tickets.
Documentación oficial: docs.typesafe.ai. SDK de Python: typesafe-sdk.
Qué problema resuelve (y qué no)
Un modelo de lenguaje es excelente generando texto. Es mediocre, por sí solo, como pieza de un flujo de trabajo: la salida no tiene contrato.
TypeSafe invierte el encargo. Tú defines:
- El estado: el texto o el objeto que quieres evaluar.
- Las preguntas: cada una con un tipo y, cuando aplica, criterios.
- Lo que harás después en tu código: umbrales, enrutado, alertas.
El modelo no te escribe un ensayo. Te responde dentro de un esquema.
Analogía útil:
No le pides a un analista “dime qué opinas de este correo”. Le pasas una lista de casillas: ¿hay amenaza de cancelación? ¿qué cola le toca? ¿en qué tramo de urgencia está?
Eso es, en esencia, System One de TypeSafe.
Qué no es: no sustituye a FastAPI, no es un agente autónomo y no “entiende tu empresa” si el estado que le pasas está vacío. Es una capa de juicio estructurado sobre el texto que tú le entregas.
Instalación e importaciones
El paquete oficial en PyPI es typesafe-sdk (no typesafe-ai). Requiere Python 3.10 o superior. La clave se guarda en la variable de entorno TYPESAFE_API_KEY; puedes crearla en la consola de TypeSafe.
En este notebook la clave se carga desde un secreto de Google Colab llamado TYPESAFE_API_KEY (icono de llave → Notebook access). Si ejecutas fuera de Colab, exporta la misma variable de entorno.
Cierre
El salto que hay detrás de este SDK no es “usar un modelo más nuevo”. Es dejar de tratar la salida del modelo como prosa y empezar a tratarla como dato.
Noul, Choice y Score son tres formas de pregunta. El sistema aparece cuando esas respuestas entran en un servicio que valida, enruta y registra: una API tuya, no una pestaña de chat.
Si quieres ver cómo se construye ese tipo de servicio —recibir el texto, llamar a una capa de IA y devolver una respuesta controlada— el camino natural en Python es FastAPI. En mi ebook 5 Proyectos de IA con FastAPI y LangChain para tu portafolio trabajo precisamente ese salto: de experimentar en un notebook a tener un endpoint que otra persona puede consumir.
Recursos:
- Documentación: docs.typesafe.ai
- Producto: typesafe.ai
- SDK: github.com/typesafe-ai/typesafe-sdk-python
- PyPI: pypi.org/project/typesafe-sdk
- Notebook en mi GitHub