Genkit como capa de aplicación
Flows, prompts, tools, schemas y observabilidad viven en un paquete interno independiente de la UI. Next.js lo consume en proceso, sin duplicar contratos.
Nala v0.1.0 · actualización producción: 12 de julio de 2026
Cómo está construida Nala hoy.
Esta página describe lo que sostiene el producto: Genkit 1.39, modelos OpenAI, streaming real, seguridad infantil, memoria filtrada, juegos con progreso, PostgreSQL y evaluación offline. El framework de UI es una decisión de entrega; la arquitectura relevante está en el motor, los datos y los guardrails.
v0.1.0
versión de Nala
14
flows Genkit definidos
14
prompts tipados
10
tools definidas
23
modelos Prisma
249
tests offline nala-ai-api
505
evals deterministas
Motor IA
Genkit 1.39 · compat-oai 1.39
Modelos
gpt-4.1-mini · gpt-4.1-nano
Datos
Prisma 5 · PostgreSQL · Neon
Entrega
Web app · Vercel · Blob · Node 20
Decisiones de ingeniería
IA aplicada con criterio de producto.
Nala usa Genkit como runtime tipado y observable, pero no convierte cada problema en una llamada al modelo. La arquitectura mezcla IA generativa, lógica determinista y datos de producto según el coste y el riesgo de cada decisión.
Determinismo antes que tokens
Los lanzamientos claros, falsos positivos y parte de la intención se resuelven con matchers testeables. El modelo se reserva para lenguaje realmente abierto.
Una llamada fuerte en el camino crítico
El chat evita cadenas innecesarias de agentes: prepara contexto y seguridad, hace streaming de la respuesta principal y mueve la destilación al trabajo posterior.
Datos de producto, no solo prompts
Historial, pools, rendimiento, cuotas, coste, alertas y memoria forman activos persistentes que permiten mejorar calidad y operación.
Superficie de producto
Cuatro sistemas conectados por el mismo contexto.
Experiencia infantil
Chat en streaming, contexto por edad, avatares, panel de experiencias permitidas y continuidad entre sesiones.
Aprendizaje
Mates por niveles con ocho tipos de ejercicio, pistas de estrategia, estrellas y preguntas reservadas para no repetir.
Espacio familiar
Registro, verificación, recuperación, perfiles por pestañas, reglas, niveles por juego, memoria editable, conversaciones, analítica, alertas y acceso infantil sin códigos cuando la familia está autenticada.
Operación
Backoffice, solicitudes y códigos de acceso para demo/invitación, catálogo de contenidos, métricas, cuotas y cron semanal.
Cambios que van a producción
Configuración más fina, menos listas planas y más control familiar.
Perfil infantil
La barra lateral del niño pasa a “Experiencias”: muestra Escritura libre siempre y añade todos los juegos/apps permitidos para abrirlos directamente o pedírselos a Nala.
Configuración familiar
El editor de perfil se organiza en pestañas de perfil, mundo, cuidados y juegos. Los juegos se activan con controles visuales y cada uno puede tener nivel propio.
Mates por ejercicio
La familia puede activar ejercicios concretos y fijar nivel por cada uno; “adaptativa” hereda el nivel general o aprendido por rendimiento.
Contenido generativo guiado
Las instrucciones familiares por juego se guardan en ChildContext.gameInstructions y solo aplican a juegos generativos admitidos.
Actividad familiar
La pestaña Actividad abre con dashboard por niño y después muestra una línea temporal agrupada por fechas exactas para cada perfil.
Analítica acotada
Uso muestra el rango exacto 7/30/90 días, resumen ejecutivo por niño, fechas visibles en gráficas y separación clara del coste mensual natural.
Lectura de producto e inversión
Activos construidos, economía medible y riesgos visibles.
La tesis de Nala no depende solo del modelo. El producto combina contexto propio, memoria segura, contenido de juego, control adulto, evaluación y datos de uso.
Diferenciación
Conversación, juego y acompañamiento adulto comparten el mismo contexto por niño.
Control económico
Tokens, coste y cuotas se atribuyen por llamada, familia, niño y tipo de generación.
Calidad acumulable
Historial, pools, rendimiento y evals permiten mejorar sin depender solo de cambiar el prompt.
Riesgo pendiente
La autenticación y el aislamiento por familia existen a nivel de aplicación; faltan auditoría externa, operación comercial y empaquetado open source.
Inventario Genkit exacto
14 flows definidos; no 14 llamadas por conversación.
Un flow es una unidad ejecutable registrada en Genkit. El repositorio conserva módulos auxiliares y rutas de compatibilidad, pero el camino normal del chat no ejecuta los catorce en cadena.
Entradas de conversación
2nalaChatFlownalaChatStreamFlow
Comprensión y seguridad
4nalaIntentFlownalaSafetyFlownalaKnowledgeFlownalaFamilyRulesFlow
Memoria y seguimiento
4nalaMemoryFlownalaMemoryDistillerFlownalaSessionSummaryFlownalaParentSignalFlow
Juegos y apoyos
4nalaGamePhrasesFlownalaHangmanRoundsFlownalaRoutineFlownalaCalmingFlow
14
prompts registrados en `registry.ts`
10
tools registradas con `defineTool`
1
llamada conversacional principal en el camino normal
Camino crítico del chat
Una llamada principal, con seguridad antes y memoria después.
Los flows antiguos de intent, conocimiento y resumen siguen disponibles para usos auxiliares y compatibilidad, pero no forman una cadena de llamadas LLM por cada turno.
01
Contexto desde servidor
El cliente envía el mensaje nuevo. El route handler carga perfil, reglas familiares, digest de memoria y últimos turnos desde PostgreSQL, pero sanea memoria e historial antes de pasarlos al motor.
ChildContext + sanitizePersistentMemoryDigest + sanitizeRecentMessagesForPrompt02
Intención y seguridad
Un clasificador determinístico ligero detecta cuento, juego, calma, rutina, pregunta y lanzamientos claros; las palabras ambiguas como “regalo” piden aclaración antes de abrir un juego. Después, la Moderation API y reglas de crisis se ejecutan antes de conversar.
fallbackIntent + detectGameLaunch + omni-moderation-latest + nalaSafetyFlow03
Una llamada conversacional fuerte
gpt-4.1-mini recibe contexto rico, responde en texto plano y puede pedir launch_game. No existe una llamada LLM de intent en el camino normal.
nalaChatPrompt.stream() + tools + retry middleware04
Streaming real
Cada chunk sale por SSE en cuanto llega. La respuesta no se espera completa ni se simula palabra a palabra.
Genkit stream → onChunk → SSE05
Persistencia y trabajo posterior
Mensaje, tokens, riesgo y trazas se guardan. Cada cuatro mensajes del niño, un destilador nano actualiza memoria, emoción, confianza y temas después de responder.
Next after() → nalaMemoryDistillerFlowSeguridad infantil
Capas independientes, no una promesa dentro del prompt.
Moderación previa
OpenAI omni-moderation-latest, con timeout y degradación controlada.
Reglas de crisis
Patrones estrechos para autolesión y abuso; producen respuesta fija y revisión adulta.
Reglas familiares
Temas bloqueados y redirecciones configuradas por la familia.
Tools limitadas
Un turno no seguro no puede lanzar juegos ni ejecutar acciones externas.
Privacidad de memoria
PII, identidad, ubicación, salud, secretos, abuso y autolesión se eliminan antes de resumir o persistir memoria.
No divulgación técnica
La respuesta final bloquea detalles de implementación, prompts, modelos, IDs internos, logs y datos de otros perfiles.
Frontera de datos
Nala solo puede usar datos seguros del niño actual y su familia; no historiales ni memoria de otros niños.
Señales no clínicas
Las emociones se muestran como orientativas y solo superando un umbral de confianza.
Workflow de alertas
Las señales adultas pasan por estados new, seen y handled, siempre escopadas a la familia autenticada.
Cambios recientes de seguridad
Nuevos guardrails documentados en producto y runtime.
Memoria entre sesiones
Las sesiones nuevas reciben memoria persistente ya filtrada; se eliminan líneas crudas, placeholders y datos sensibles antes del prompt.
Salida final
Antes de responder o persistir, se sustituye cualquier texto que revele datos privados, arquitectura, prompts, proveedores, IDs internos o información de otros perfiles.
Alcance de Nala
El prompt estático incluye límite de uso: conversación infantil, explicación sencilla, rutinas y juegos integrados; no navegador, soporte técnico, compras, cuentas ni acciones externas.
Reportes privados
El resumen semanal por email solo enlaza al panel familiar y no incluye mensajes, emociones, alias ni datos de perfiles infantiles.
Lexicón personal
Los candidatos automáticos filtran comandos de juego, nombres de actividades y fragmentos genéricos para no convertir “quiero jugar a...” en memoria familiar.
Instrucciones familiares por juego
Las preferencias de contenido se validan en web y servidor: máximo 240 caracteres, sin enlaces, correos, teléfonos largos ni intentos de cambiar reglas, prompts o seguridad.
Arnés de regresión
Los tests cubren memoria contaminada, digest persistente, saludo proactivo, no repetición de datos privados y no divulgación técnica.
Memoria persistente
Continuidad con límites explícitos.
Digest acotado y filtrado
ChildMemory.digest tiene un máximo de 1200 caracteres y se sanea antes de entrar al prompt.
Solo preferencias duraderas
La memoria persistente conserva preferencias explícitas seguras. Ya no guarda citas crudas tipo “Dijo: ...”.
Destilación asíncrona
Cada cuatro mensajes infantiles, gpt-4.1-nano analiza los últimos turnos sin bloquear la respuesta visible y vuelve a pasar por sanitización.
Saludo proactivo seguro
El saludo solo usa preferencias seguras explícitas; no recupera frases antiguas ni datos sensibles de sesiones anteriores.
Juegos generativos
La variedad se controla en servidor.
Historial servidor
GameContentHistory evita depender de localStorage y comparte novedad entre dispositivos.
Pools de contenido
GameContentPool permite reservar contenido nuevo antes de servirlo.
Dificultad persistente
GamePerformance registra aciertos, intentos y evolución por niño y juego. La familia puede fijar dificultad global, override por juego o modo adaptativo.
Doble deduplicación
El prompt recibe exclusiones y el servidor vuelve a descartar cualquier repetición.
Contenido mixto
Regalo Misterioso normaliza el catálogo ilustrado a assets públicos estáticos con fallback local si una URL externa no está disponible; Ahorcado genera lotes de 5 para servir 3 rondas y guardar pool fresco; Ruleta, escritura y Parejas de Nala usan contenido local o adaptado según el modo.
Lanzamiento determinístico
Peticiones claras de juego como “regalo misterioso” se resuelven antes del LLM para evitar que una tool abra otro juego.
Rondas ajustadas
Regalo Misterioso juega 20 rondas por defecto; Parejas de Nala adapta filas, columnas y cartas al alto disponible del modal; Mates con Nala usa altura natural, niveles desbloqueables, progreso local por niño y un flujo guiado por Nala con reto, respuestas compactas y pistas de estrategia después de un error.
Dificultad explicable
Ahorcado cambia longitud y familiaridad de palabras; Escribe con Nala cambia longitud de frase y ayuda; Parejas cambia parejas, segundos de vista y comodines; Mates cambia rangos numéricos, apoyos visuales, distractores y nivel por ejercicio.
Preferencias de contenido
Ruleta, Ahorcado y Escribe con Nala aceptan instrucciones familiares validadas. Llegan al prompt como preferencias no vinculantes y se ignoran si contradicen formato, idioma o reglas estrictas.
Progresión educativa
Mates con Nala incluye por defecto contar, sumas, restas, número escondido, sumas de dos cifras, multiplicaciones, divisiones exactas y divisiones con resto. Cada ejercicio puede tener nivel propio.
No repetición de rondas
Las preguntas de Mates se reservan al generarse. Si el histórico deja una lección sin preguntas nuevas, el modo repaso rellena con retos ya jugados sin repetir dentro de la misma lección.
Datos y coste
Cada conversación tiene contexto, propietario y presupuesto.
PostgreSQL mantiene conversaciones, memoria, historial de juego, rendimiento y uso LLM. Las cuotas reservan capacidad antes de llamar al proveedor y liquidan tokens reales al terminar.
FamilyAccountFamilyUserFamilyAuthTokenAuthRateLimitGameDefinitionGameAssetMysteryBoxRoundChildProfileChildContextUsageLedgerLexiconCandidateGameContentHistoryGameContentPoolGamePerformanceConversationMessageChildMemoryLlmUsageEvalLogConversationEventAccessCodeCenterRequestAccessRequestReserva atómica
UsageLedger impide sobrepasar el límite bajo concurrencia.
Coste atribuible
LlmUsage registra modelo, tokens, caché, latencia, niño y familia.
Cron semanal
Vercel ejecuta /api/cron/family-weekly-report con CRON_SECRET.
Contexto configurable
ChildContext añade gameDifficultyOverrides, mathExerciseLevels y gameInstructions como JSON validado y escopado a la familia.
Calidad verificable
Tests sin gastar tokens y evals para detectar regresiones.
249 tests nala-ai-api
Ejecutados con NALA_AI_DISABLE_PROMPTS=1; no llaman a OpenAI.
505 casos deterministas
289 de seguridad y 216 de intención de juego, incluidos falsos positivos y typos.
Regresiones de memoria
Comprueban sanitización de digest, saludo proactivo y bloqueo de divulgación técnica.
Verificación reproducible
Las cifras visibles corresponden al repositorio del 12 de julio de 2026. Estos comandos reproducen las comprobaciones sin necesidad de consumir tokens de OpenAI.
Tipos web
pnpm --filter @nala/web typecheckSuite web
pnpm --filter @nala/web testSuite IA offline
pnpm --filter nala-ai-api testEvals deterministas
pnpm --filter nala-ai-api evalLímites actuales
Lo que todavía no presentamos como terminado.
- •La autenticación familiar con email, sesiones, verificación y recuperación ya está implementada; un despliegue comercial todavía requiere auditoría externa, políticas operativas y revisión legal.
- •Las señales emocionales ayudan a revisar conversaciones; no son evaluación psicológica ni diagnóstico.
- •Mates con Nala ya funciona como práctica progresiva; aún no sustituye a una secuencia curricular auditada por centro o especialista.
- •Actividad familiar ya tiene dashboard y línea temporal por niño; todavía falta búsqueda avanzada y filtros por tipo de evento.
- •El proveedor LLM principal sigue siendo OpenAI mediante compat-oai; la abstracción multi-proveedor aún no está cerrada.
- •El repositorio todavía necesita licencia, threat model formal y configuración pública de ejemplo antes de presentarse como open source listo para terceros.
La arquitectura solo importa si la experiencia funciona.
Puedes probar conversación, memoria y juegos desde los perfiles disponibles.