Construir con TypeSafe

¿Qué hace Construir con TypeSafe?

TypeSafe hace que unidades de inteligencia artificial sean utilizables como primitivas de programación: pequeños juicios que puedes componer en capacidades más grandes. Sus modelos System One devuelven juicios rápidos y enfocados que el software puede consumir directamente. Jev es el modelo estrella y primero de TypeSafe. Entiende el lenguaje natural y devuelve respuestas tipadas y probabilidades, en lugar de generar texto o explicaciones de razonamiento. El código posee el flujo de trabajo; el modelo proporciona sentido común programable donde el código normal necesita comprensión semántica.

Llamar a Jev a través de OpenRouter

Esta variante de la habilidad llama a Jev a través de OpenRouter, no a través de la API propia de TypeSafe. La documentación de TypeSafe sigue siendo la referencia para conceptos y diseño de preguntas; solo cambian el acceso, los IDs de modelo y la facturación.

• Credencial: una clave API de OpenRouter, facturada a la cuenta de OpenRouter. No se necesita una cuenta de TypeSafe. Léela del entorno (OPENROUTER_API_KEY o TYPESAFE_API_KEY configurada con la clave de OpenRouter); nunca la codifiques directamente, y mantenla en el lado del servidor en aplicaciones web.
• API System One (por defecto): POST https://openrouter.ai/api/v1/systemone con Authorization: Bearer <clave OpenRouter>. Implementa las formas de solicitud y respuesta de TypeSafe y añade id, provider y usage.cost a la respuesta.
• SDK de TypeSafe (@typesafe-ai/sdk, typesafe_sdk): establece la URL base a https://openrouter.ai/api (el SDK añade /v1/systemone) mediante baseURL / base_url o TYPESAFE_BASE_URL, y pasa la clave de OpenRouter mediante apiKey / api_key o TYPESAFE_API_KEY. Todo lo demás sigue la documentación del SDK de TypeSafe.
• No llames a la lista de modelos del SDK (client.models.list()): en OpenRouter golpea la API de Modelos de OpenRouter, cuya forma de respuesta el SDK rechaza.
• IDs de modelo: jev-1.14 (actual), jev-1.13 o jev-latest; los IDs simples se asignan a typesafe/jev-… y ~typesafe/jev-latest. Fija una versión para umbrales reproducibles. Consulta los modelos TypeSafe en OpenRouter para versiones actuales, precios y longitud de contexto; el campo model de la respuesta nombra la versión exacta que sirvió la solicitud.
• Box (localiza un objetivo descrito en una imagen en state) necesita jev-1.14 o posterior; 1.13 lo rechaza con un 400. Box siempre devuelve bordes, así que combínalo con un Noul cuando el objetivo pueda estar ausente.
• Superficie alternativa: la API Decisions de OpenRouter (POST https://openrouter.ai/api/alpha/decisions) y sus SDK de TypeScript, Python y Go. Prefiérela solo cuando el proyecto ya usa el SDK de OpenRouter.
• No es la API tipada de Jev: typesafe/jev-router es un enrutador de chat-completions que usa Jev para elegir otro LLM. Devuelve texto generado, no respuestas tipadas, por lo que no encaja en los patrones de esta habilidad.
• Sesiones en la nube y en modo aislado: la lista de permitidos de red debe incluir openrouter.ai; almacena la clave como un secreto, no como una variable de entorno simple.

Documentación de OpenRouter: Jev en OpenRouter, SDK de TypeSafe en OpenRouter, tutorial de Jev y el índice de documentación (búscalo con "Jev" para encontrar los cookbooks). Cuando la documentación de OpenRouter y TypeSafe difieran sobre acceso, endpoints, IDs de modelo o precios, la documentación de OpenRouter es la que prevalece para esta configuración.

Leer la documentación en vivo

La documentación en vivo de TypeSafe es la fuente de verdad. Léela como parte de la tarea. Esta habilidad proporciona dirección; los documentos contienen conceptos actuales, guías de prompting, contratos de API, uso de SDK, modelos, límites y ejemplos prácticos.

• Comienza con el índice de documentación para descubrir páginas relevantes y cookbooks. Usa lecturas dirigidas en lugar de cargar todo el sitio.
• Mintlify sirve Markdown añadiendo .md a la ruta de la página, por ejemplo cómo construir con TypeSafe. Sigue los enlaces del índice; convierte los enlaces a páginas de documentación sin extensión a .md cuando sea útil. Resuelve los enlaces relativos contra https://docs.typesafe.ai.
• Antes de escribir una integración, lee la página actual de la API o del SDK elegido y la guía de preguntas relevante para el diseño. Para un nuevo flujo de trabajo, inspecciona también el cookbook más cercano: a menudo muestra una mejor descomposición que un clasificador genérico.
• Si el índice no está disponible, usa los enlaces directos a continuación o la navegación del sitio. Si la obtención de Markdown falla, prueba la página normal. Si el acceso en vivo no está disponible, usa la documentación local disponible o los tipos del SDK instalado, indica esa limitación y evita inventar detalles dependientes de la versión.

Tarea	Comienza aquí; sigue los detalles relevantes
Entender el modelo de programación	System One, guía de construcción
Explorar qué construir	Mapa de casos de uso, luego los cookbooks relevantes del índice
Preparar entradas y preguntas	Estado, primitivas, luego la página de la primitiva elegida
Decidir cómo manejar la incertidumbre	Confianza
Escribir código de API	SDK de TypeSafe en OpenRouter primero, luego API HTTP, SDK Python o SDK JavaScript para las formas de las solicitudes, con la URL base y la clave de OpenRouter
Encontrar cookbooks de OpenRouter	Control de llamadas a herramientas, cascada verificada, clasificación a escala, aprobación automática de solicitudes de permiso
Actualizar una integración antigua	Guía de migración y la referencia actual del SDK instalado

Encontrar la forma útil

Empieza desde el comportamiento que el usuario quiere: ¿qué mostrará, seleccionará, cambiará o delegará la aplicación? Trabaja hacia atrás hasta los juicios que necesita. Mantén las reglas conocidas, los cálculos, las búsquedas exactas y la ejecución en código. Preserva la pila y el alcance elegidos por el usuario; añade TypeSafe donde la comprensión semántica sea útil.

Al hacer una lluvia de ideas o elegir una arquitectura, considera más que la clasificación. Los patrones a continuación son puntos de partida: combina primitivas en torno al objetivo del usuario, incluyendo ideas que no encajen en una receta establecida.

• Enrutar y llenar argumentos conocidos. Una solicitud puede seleccionar un manejador y sus parámetros tipados. Haz preguntas específicas de la rama relevantes por adelantado y consume solo las respuestas pertinentes. Explora llamada a funciones y fan-out especulativo.
• Seleccionar en lugar de generar. Encuentra valores candidatos o intervalos de origen en el código, usa un juicio para seleccionar el deseado, luego cópialo o normalízalo. El código también puede ensamblar texto fuente en un documento formateado o una guía de lectura. Explora extracción de valores y recuperación de estructura.
• Encontrar y juzgar evidencia. Recupera candidatos, compara su relevancia con una consulta y selecciona el contexto útil. Explora reordenamiento y clasificación jerárquica.
• Convertir juicios en datos reutilizables. Puntúa dimensiones una vez, luego deja que el código o los controles del usuario cambien pesos, umbrales, clasificaciones y vistas. Con resultados etiquetados, esas señales pueden convertirse en características clásicas de ML. Explora puntuación compuesta y descubrimiento de características.
• Verificar y escalar. Comprueba afirmaciones o campos específicos contra su evidencia; envía casos inciertos o fallidos a una persona o a un modelo de razonamiento. Explora verificación de citas y cascadas de extracción.
• Responder a estados cambiantes. El código puede retener objetivos y observaciones mientras nuevos juicios guían el siguiente paso acotado. Mantén el estado inferido distinto de los hechos observados y verifica la frescura antes de aplicar un resultado a una situación cambiada.

Para solicitudes abiertas, ofrece las pocas direcciones que mejor sirvan al objetivo del usuario y recomienda un punto de partida. Para una solicitud concreta, elige el patrón relevante y construye; una lluvia de ideas no es un desvío obligatorio.

Diseñar los juicios

Elige según lo que signifique la respuesta, luego lee la página de primitiva correspondiente:

Necesidad	Primitiva	Distinción importante
Uno de un conjunto definido	Choice	Elige una opción; su distribución compara opciones competidoras
Si una condición se cumple	Noul	Probabilidad de sí; sin confianza separada; usa uno por etiqueta cuando puedan aplicarse varias
Grado a lo largo de una dimensión descrita	Score	Posición ponderada por probabilidad en niveles ordenados; usa Scores comparables por elemento para clasificación graduada
Dónde está un objetivo descrito en una imagen	Box	Solo Jev 1.14+; sin criterios; siempre devuelve bordes, así que pregunta a un Noul por la presencia

Proporciona a cada pregunta suficiente estado relevante para responder: texto fuente, identidades, relaciones, políticas y hechos actuales. Prefiere campos JSON con nombre cuando el contexto tenga varias partes. Pon el juicio en instrucciones y define sus posibles respuestas en criterios. Los IDs de pregunta son para el código y no se envían al modelo; incluye el significado completo en la pregunta. Referencia el estado anidado con rutas entre comillas invertidas como ticket.messages[0].text.

Haz una pregunta estrecha y coherente por juicio. Divide dimensiones independientemente útiles, sin destruir la relación que se está juzgando. Una selección de acción acotada o una interpretación contextual es válida; atómico no significa extracción literal de hechos o un límite de una oración. Las cadenas funcionan para preguntas simples. Usa objetos o arrays estructurados cuando las definiciones, contrastes, exclusiones o ejemplos aclaren instrucciones o criterios. Los niveles de Score deben describir situaciones concretas y ser autosuficientes.

Mantén las respuestas necesarias disponibles. Incluye un resultado de no coincidencia cuando nada pueda encajar; usa un juicio de presencia separado cuando sea independientemente útil. Para la selección de valores fuente, verifica la cobertura de candidatos: el modelo no puede elegir un valor omitido.

Componer y verificar

Haz preguntas independientes sobre el mismo estado juntas, incluyendo preguntas especulativas útiles. Se ejecutan en paralelo y no pueden ver las respuestas de las demás. Declara cada premisa especulativa explícitamente; el código consume las respuestas aplicables. Una segunda solicitud está justificada cuando una respuesta anterior es necesaria para obtener evidencia, construir nuevo estado o determinar las siguientes opciones. Las preguntas extra aún usan tokens; mide los presupuestos reales de solicitudes, el costo y la latencia de extremo a extremo.

Usa las probabilidades y la confianza para guiar el comportamiento, con umbrales evaluados en los datos del usuario y las consecuencias. La confianza de Choice/Score resume la concentración de la distribución, no la corrección general del flujo de trabajo ni el permiso para actuar. Un Noul cercano a 0.5 significa probabilidad similar para sí y no, no intensidad media. Varias alternativas aceptables también pueden distribuir la probabilidad; la baja confianza no necesita invalidar una elección de preferencia inofensiva. Ignora la incertidumbre en ramas no utilizadas.

Mantén la política explícita y los juicios sin procesar reutilizables. Las puntuaciones ponderadas son adecuadas para preferencias compensatorias; una regla de "cualquier violación grave" necesita condiciones separadas. Cambiar un peso o un filtro de visualización no necesita volver a ejecutar la inferencia cuando la evidencia y el significado de la pregunta no han cambiado. La salida tipada garantiza la interfaz, no la verdad. Los modelos System One están entrenados para decisiones calibradas; valida su rendimiento en el dominio objetivo.

Prueba casos representativos y el comportamiento resultante de la aplicación. Para fallos, inspecciona el estado exacto, las preguntas, los candidatos, las respuestas, la composición y el resultado observado. Separa la evidencia faltante, los errores del modelo, los errores de código y las fallas del servicio. Trata los umbrales de los cookbooks y los resultados de demostración como ejemplos a evaluar, no como reglas universales o limitaciones permanentes del modelo. Mantén las credenciales de API en el lado del servidor en aplicaciones web.