Jev AI - System One, Typescript y Decisiones Tipadas para Aplicaciones Reactivas

Uso del Playground para validar primero una decisión antes de incorporarla a código productivo.

Preparación de un caso de negocio real y suficientemente delimitado.

Endpoint `POST /v1/systemone` como operación principal de evaluación.

Consulta de modelos disponibles mediante `GET /v1/models`.

Autenticación mediante API Key enviada como Bearer token.

Uso de variables de entorno para mantener la credencial fuera del código fuente.

Campos principales de la petición: `state`, `model` y `questions`.

Uso del alias `jev-latest` frente a una versión fijada explícitamente.

Relación entre los identificadores de las preguntas enviadas y las respuestas recibidas.

Interpretación inicial de `answers`, `model` y `usage`.

Lectura de tokens utilizados para comprender el coste de una evaluación.

Comparación entre llamada HTTP directa y utilización del SDK TypeScript.

Flujo recomendado Playground → contrato validado → backend → integración en producto.

`state` como representación del mundo que Jev debe evaluar antes de responder a las preguntas.

Uso de texto para mensajes, incidencias, descripciones y otros contextos sencillos.

Uso de objetos JSON para combinar información procedente de distintas entidades.

Uso de arrays cuando el contexto necesita representar varios elementos relacionados.

Diseño de estructuras JSON con campos semánticamente claros y predecibles.

Selección de la información realmente necesaria para tomar una decisión.

Reducción de ruido y campos irrelevantes que consumen contexto sin aportar señal.

Diferencia entre datos brutos y estado preparado específicamente para inferencia.

Composición de usuario, sesión, producto, evento, configuración y reglas dentro de un mismo state.

Normalización previa de fechas, categorías, flags, cantidades y valores de negocio.

Tratamiento de campos ausentes, opcionales, desconocidos o inconsistentes.

Prevención de información contradictoria dentro del estado suministrado.

Diseño de funciones TypeScript que construyan estados reproducibles a partir del estado real de la aplicación.

Versionado del contrato de state cuando evoluciona el producto.

Preparación de estados compactos para reducir latencia, consumo y ambigüedad.

Choice para seleccionar una alternativa dentro de un conjunto previamente definido.

Diseño de criterios semánticamente diferenciables para evitar opciones que se solapen.

Uso de alternativas como `other`, `unknown` o `needs_review` cuando el dominio lo requiera.

Interpretación de la opción seleccionada y distribución de probabilidades en Choice.

Score para evaluar un estado mediante una rúbrica ordenada.

Diseño de niveles que representen diferencias reales y no etiquetas arbitrarias.

Interpretación del score ponderado, la leyenda y las probabilidades por nivel.

Noul para evaluar probabilísticamente una condición de sí/no.

Interpretación de `noul` como probabilidad de que la afirmación sea verdadera.

Diferencia entre Noul y el campo de confianza utilizado por Choice y Score.

Incorporación de `criteria` para precisar qué significa cada posible resultado.

Construcción de instrucciones concretas, delimitadas y evaluables.

Selección del tipo de pregunta según la decisión de negocio.

Evitación de preguntas abiertas que deberían resolverse mediante un modelo generativo.

Combinación de varias primitivas para representar decisiones más sofisticadas.

`questions` como mapa de decisiones independientes evaluadas sobre un state común.

Diseño de IDs estables que tengan significado dentro de la lógica de aplicación.

Separación de una decisión compleja en señales atómicas más fáciles de validar.

Evaluación paralela de clasificación, urgencia, riesgo, intención y necesidad de revisión.

Reutilización del mismo estado sin crear una llamada independiente para cada juicio.

Diseño de mapas TypeScript cuya estructura determine también el tipo de respuesta esperado.

Agrupación de preguntas que comparten realmente el mismo contexto.

Separación de preguntas cuando necesitan estados o políticas materialmente diferentes.

Evitación de dependencias ocultas donde una pregunta presupone la respuesta de otra.

Composición posterior de resultados mediante lógica determinista.

Construcción de reglas `if`, matrices de decisión y máquinas de estados a partir de varias respuestas.

Uso de probabilidades completas en lugar de consumir únicamente la opción ganadora.

Diseño de respuestas orientadas a routing, ranking, priorización y selección de comportamiento.

Identificación de contradicciones entre señales y escalado del caso para revisión.

Creación de contratos de preguntas versionables junto al código de producto.

Instalación de `@typesafe-ai/sdk` dentro de un proyecto Node.js o TypeScript.

Creación y configuración de `TypeSafeClient`.

Carga automática de `TYPESAFE_API_KEY` desde el entorno.

Uso de `client.systemOne()` para enviar estados y preguntas.

Helpers `choice`, `score` y `noul` para construir contratos tipados.

Inferencia TypeScript del tipo de cada respuesta a partir de las preguntas enviadas.

Acceso seguro a `answers` sin necesidad de parsear texto generado.

Tipado de estados, criterios y resultados dentro del dominio de la aplicación.

Configuración del modelo predeterminado y override por solicitud cuando resulte necesario.

Consulta del catálogo de modelos desde el cliente.

Configuración de timeout, cancelación y comportamiento de retry.

Manejo de errores del SDK mediante tipos específicos.

Separación entre cliente Jev, lógica de negocio y código de interfaz.

Creación de wrappers propios para encapsular decisiones reutilizables.

Testing de la integración mediante clientes y transportes controlados.

Razones para no incluir una API Key de Jev directamente dentro del bundle del navegador.

Arquitectura navegador → backend/BFF → System One → backend → interfaz.

Uso de Route Handlers, API Routes, server functions o endpoints propios según el framework seleccionado.

Separación entre state de interfaz y state enviado realmente al modelo.

Validación server-side de los datos recibidos desde el navegador.

Construcción de un contrato TypeScript compartido entre frontend y backend.

Encapsulado del cliente Jev exclusivamente en módulos server-side.

Uso de variables de entorno y secret managers para proteger credenciales.

Diseño de endpoints de decisión estrechos frente a proxies genéricos capaces de ejecutar cualquier pregunta.

Autorización de usuario antes de permitir determinadas evaluaciones.

Protección frente a manipulación del state enviado desde el navegador.

Rate limiting y límites de consumo por usuario, sesión o funcionalidad.

Caching selectivo cuando el state y la decisión permiten reutilización segura.

Server Components, server actions o arquitecturas equivalentes cuando aporten ventajas al framework utilizado.

Patrón de integración aplicable a React, Next.js, Vue, Nuxt, SvelteKit y otros stacks TypeScript.

Transformación de respuestas Jev en estado directamente consumible por componentes visuales.

Interfaces que cambian rutas, prioridad, copy, orden o acciones según una decisión tipada.

Uso de probabilidades para adaptar gradualmente una experiencia y no únicamente mediante decisiones binarias.

Patrones high confidence → acción directa, medium confidence → confirmación y low confidence → fallback.

Renderizado condicional basado en Choice.

Indicadores, prioridad y ordenación basados en Score.

Gates y condiciones basadas en Noul.

Estados de carga breves que no bloqueen innecesariamente la experiencia.

Optimistic UI únicamente cuando la reversibilidad de la acción lo permita.

Cancelación de peticiones cuando el state de la interfaz ha quedado obsoleto.

Prevención de race conditions cuando varias evaluaciones terminan en diferente orden.

Debounce y reducción de llamadas durante cambios rápidos del usuario.

Actualización progresiva del contexto sin reevaluar información que no ha cambiado.

Fallback determinista cuando Jev no está disponible o la respuesta no supera el umbral definido.

Diseño de UX donde la incertidumbre del modelo modifica el comportamiento de la aplicación de forma explícita.

Diferencia entre una opción seleccionada y la probabilidad asociada a todas las alternativas.

Interpretación de `confidence` en respuestas Choice y Score.

Interpretación de Noul sin un campo de confianza separado.

Umbrales de automatización definidos por riesgo y no por una cifra universal.

Thresholds diferentes para acciones reversibles, sensibles e irreversibles.

Zona de incertidumbre donde el sistema solicita más información.

Ruta de revisión humana cuando la señal es insuficiente.

Abstención como comportamiento correcto frente a decisiones forzadas.

Uso de historiales etiquetados para seleccionar thresholds adecuados.

Medición de falsos positivos y falsos negativos.

Coste empresarial asociado a cada tipo de error.

Matrices de riesgo para determinar política de actuación.

Calibración periódica cuando cambia el dominio o los datos de entrada.

Registro de probabilidad, decisión final y outcome observado.

Separación entre señal probabilística y política determinista de negocio.

Clasificación de tickets, mensajes, solicitudes o contenido mediante Choice.

Routing hacia equipos, productos, flujos o modelos especializados.

Scoring de prioridad, gravedad, intención o calidad mediante Score.

Detección de condiciones específicas mediante Noul.

Priorización de colas utilizando valores probabilísticos.

Selección dinámica de una experiencia de usuario según contexto.

Personalización de pasos siguientes sin generar contenido libre.

Validación previa de acciones propuestas por un sistema o agente.

Guardrails probabilísticos complementarios a reglas de seguridad deterministas.

Detección de necesidad de revisión humana antes de continuar.

Model routing entre alternativas previamente autorizadas.

Clasificación semántica de información que sería frágil mediante reglas basadas solo en palabras clave.

Control de acceso funcional condicionado siempre por autorización determinista posterior.

Detección de información insuficiente antes de ejecutar un workflow.

Composición de varias señales Jev dentro de una única política de producto.

Diferencia entre usar Jev para decidir y utilizar un LLM generativo para producir contenido.

Jev como router previo a la selección de un modelo generativo.

Verificación de condiciones antes de permitir que un agente utilice una herramienta.

Selección de workflow según intención, riesgo o complejidad de la solicitud.

Combinación de Jev con RAG sin convertir cada recuperación en una conversación completa.

Uso de Noul para comprobar si existe evidencia suficiente antes de continuar.

Choice para seleccionar una estrategia o herramienta previamente autorizada.

Score para ordenar alternativas que después procesa otro componente.

LLM generativo para texto, código, explicación y planificación abierta.

Código determinista para permisos, pagos, borrados y reglas que no deben depender de probabilidad.

Human-in-the-Loop para decisiones de alto impacto.

Agentes donde Jev reduce decisiones que de otro modo consumirían un ciclo completo de razonamiento.

Prevención de arquitecturas donde una llamada de IA se utiliza innecesariamente para cada `if`.

Diseño de fallback entre System One, reglas, LLM y revisión humana.

Arquitectura de decisión por capas según coste, latencia, incertidumbre y riesgo.

Medición del tiempo extremo a extremo de cada evaluación.

Separación conceptual entre tiempo del modelo, red, backend y renderizado de interfaz.

Reducción del state a los datos estrictamente necesarios.

Evaluación conjunta de preguntas que comparten contexto para evitar llamadas repetidas.

Evitación de preguntas redundantes que proporcionan la misma señal.

Selección de modelos mediante aliases o versiones fijadas según estabilidad requerida.

Uso de respuestas tipadas para eliminar parsing y reparación de texto generado.

Comparación de coste y latencia frente a utilizar un LLM generativo para decisiones pequeñas.

Cache de resultados cuando la misma decisión y el mismo estado pueden reutilizarse.

Debounce y request coalescing en interfaces altamente interactivas.

Cancelación mediante `AbortSignal` cuando una respuesta ya no resulta necesaria.

Timeouts diferenciados según criticidad de la experiencia.

Medición de input tokens y consumo por caso de uso.

Detección de decisiones cuyo coste supera el valor que aportan.

Optimización conjunta de state, questions, thresholds y frecuencia de invocación.

Tratamiento diferenciado de errores de autenticación, validación, rate limiting y sobrecarga.

Manejo de `401` cuando falta la credencial o no resulta válida.

Uso de `422` para localizar solicitudes o preguntas que no cumplen el contrato.

Backoff ante `429` y errores temporales del servicio.

Retry de fallos transitorios sin crear loops ilimitados.

Política de retry predeterminada del SDK y personalización por llamada.

Timeouts y cancelación para evitar peticiones que sobrevivan al contexto que las originó.

Fallback determinista cuando System One no puede responder.

Logging estructurado de decisión, latencia y resultado sin exponer datos innecesarios.

Correlation IDs para relacionar interacción de usuario, evaluación y acción posterior.

Métricas de éxito, error, timeout, retry y escalado a humano.

Observabilidad de distribuciones de probabilidad y no únicamente de decisiones finales.

Alertas ante cambios bruscos en patrones de respuesta.

Separación de problemas de red, API, modelo y lógica de producto.

Runbooks de operación para degradación controlada del servicio.

Dataset representativo de estados reales y decisiones esperadas.

Golden cases para comprobar que los contratos fundamentales permanecen estables.

Evaluación independiente de Choice, Score y Noul.

Medición de precisión por clase y segmento.

Análisis de falsos positivos y falsos negativos.

Evaluación específica de casos cercanos a los thresholds.

Regression tests cuando cambian preguntas, criteria, state o versión del modelo.

Comparación controlada de modelos antes de modificar una versión fijada.

Tests unitarios sobre la lógica determinista que consume las respuestas.

Tests de integración sobre backend, SDK y contrato de respuesta.

Protección de la API Key mediante variables de entorno y gestores de secretos.

Prevención de logs que expongan credenciales o información sensible.

Validación server-side de estados suministrados por clientes no confiables.

Human review y autorización determinista para operaciones de alto impacto.

Checklist de producción con calidad, seguridad, latencia, coste, fallback, observabilidad y rollback.

Arquitectura de una aplicación fullstack TypeScript que utilice Jev como capa de decisión.

Definición del problema empresarial y del conjunto cerrado de decisiones que debe resolver System One.

Modelo de state tipado y optimizado para transmitir únicamente contexto relevante.

Contrato versionado entre estado de aplicación y estado enviado a Jev.

Mapa de preguntas que combine Choice, Score y Noul sobre un mismo contexto.

Backend seguro con API Key aislada del navegador.

Wrapper TypeScript encargado de ejecutar y tipar las evaluaciones.

Política de thresholds asociada al riesgo de cada decisión.

Interfaz hiperreactiva cuyo estado cambie en función de las probabilidades recibidas.

Ruta automática para señales claras, solicitud de contexto adicional para casos intermedios y fallback para incertidumbre elevada.

Integración opcional con un LLM generativo para tareas que requieran producir contenido.

Reglas deterministas para permisos y acciones que no deben depender exclusivamente del modelo.

Estrategia de errores, timeout, retry y degradación controlada.

Suite de evaluación con casos representativos y medición de falsos positivos y negativos.

Modelo final de observabilidad, seguridad, coste, mantenimiento y evolución del contrato de decisiones.