Desarrollar una plataforma con guardrails IA para empresa mediana significa separar dos capas: los KPIs y métricas se calculan en código determinístico (TypeScript, SQL o Python), y el modelo de IA solo genera narrativa sobre datos ya verificados. Cuesta entre 20,000 y 35,000 USD y entrega cero hallucinations en números. Lo que antes tomaba 30 ingenieros y 18 meses, hoy se entrega en 12 semanas. KPIs en código, no hallucinations.
Si tu empresa ya usó ChatGPT, Claude o un copilot interno para generar reportes y descubrió que los números no cuadran entre ejecuciones, este artículo es la arquitectura que necesitas adoptar.
Por qué los modelos no deben calcular KPIs
Un modelo de lenguaje grande es no determinístico por diseño. Si le pides el promedio de ventas del último trimestre dos veces, puede darte dos respuestas distintas porque genera tokens probabilísticamente. Para narrativa, ese rasgo es valioso. Para un total que se reporta al directorio, es inaceptable.
La consecuencia operativa es directa: en sectores como retail, distribución, salud o legal, una hallucination de 8% en un KPI puede significar una decisión de 6 cifras tomada con datos falsos. La arquitectura con guardrails resuelve el problema en la raíz: el cálculo nunca toca al modelo.
La arquitectura two-level que sí funciona
| Capa | Responsabilidad | Tecnología |
|---|---|---|
| KPI engine en código | Cálculo determinístico, auditable, versionado | TypeScript, SQL puro, Python |
| Validation layer | Schema checks, range checks, integridad referencial | Zod, Pydantic, JSON Schema |
| Data freshness check | Confirma que el dato no está obsoleto antes de servir | Timestamp + TTL configurable |
| Narrative layer (IA) | Texto que explica el número, no lo calcula | Claude Sonnet, GPT-4o, Llama 3 |
| Audit log | Quién pidió qué, qué se devolvió, hash inmutable | PostgreSQL append-only + SHA-256 |
| Citation layer | Cada afirmación referencia una fila o vista origen | Foreign keys explícitas en JSON respuesta |
La capa de cálculo y la de narrativa nunca comparten memoria de ejecución. El KPI engine devuelve un objeto JSON con números y referencias. La narrativa recibe ese JSON como contexto y genera prosa. Si el modelo intenta inventar un número, no tiene cómo, solo puede reformular los que ya vienen calculados.
El caso real: 28 KPIs hardcoded en JS con AI solo narrativa
En un proyecto reciente para una distribuidora multi-país con 100 franquicias, Catalizadora construyó una reportería avanzada con 5 secciones (Financials, Sales, Services, Complaints, System Usage) y 28 KPIs. La arquitectura aplicada fue:
- Los 28 KPIs se calculan browser-side en JavaScript puro, cero llamadas a servidor
- La IA solo recibe el JSON con los números ya calculados y genera un párrafo de narrativa por sección
- Patrón two-level: KPI headline numérico arriba, párrafo IA explicativo abajo
- Audit trail append-only con SHA-256 hash chain verificable por cualquiera con acceso al schema
- Browser-side compute significa cero CPU de servidor y cero costo variable por reporte
El resultado: visibilidad consolidada entre 100 unidades operativas con cero hallucinations en KPIs, narrativa explicativa de calidad ejecutiva y audit trail compliance-ready. La arquitectura se incluyó dentro de un proyecto de 12 semanas con metodología MAGIA Forge. Cuando los datos se unifican, los problemas se anuncian solos.
Stack recomendado para producción
Para una empresa mediana de 50 a 300 empleados que quiera adoptar guardrails IA desde el día 1, el stack que funciona en LATAM es:
- KPI engine en TypeScript con Zod para validación de schemas en runtime
- Base de datos PostgreSQL 16 con vistas materializadas para KPIs pesados, refresh por cron
- Capa de IA con Claude Sonnet o GPT-4o vía API oficial, con system prompt que prohíbe inventar números
- Audit log en tabla append-only con trigger SHA-256 que firma cada inserción
- Frontend en Next.js con server components, RSC streaming para que el usuario vea el KPI antes que la narrativa
- Tracing con OpenTelemetry para correlacionar requests entre capas
Evitar al inicio: bases de datos vectoriales para todo, agentes autónomos sin supervisor y modelos open source sin benchmark interno. Para empresa mediana se gana más con disciplina arquitectónica que con lo último en hype.
Cómo migrar una plataforma existente a guardrails
Si ya tienes un copilot interno o una plataforma que usa IA y descubres errores en métricas, el plan de migración es de 4 a 6 semanas:
- Inventario de cada prompt que produce un número o cálculo, clasificado por criticidad
- Extracción de cada cálculo a función pura en TypeScript o SQL, con tests unitarios y de propiedad
- Refactor del prompt para que reciba el resultado calculado como contexto y solo lo narre
- Validación A/B con un mes de tráfico real, comparando respuestas viejas vs nuevas
- Cutover con audit log activado desde el día 1 del nuevo motor
- Capacitación al equipo en cómo agregar nuevos KPIs sin tocar el prompt
Este proceso se ha aplicado con éxito en plataformas de reportería ejecutiva, asistentes de ventas y dashboards financieros. El payback del refactor está entre 2 y 4 meses cuando se cuenta el costo evitado de tomar decisiones con datos malos.
Errores comunes al agregar IA a una plataforma
Cinco errores que vemos repetir en plataformas con IA sin guardrails:
- Pedir al modelo que ejecute SQL directamente sobre la base de producción
- Confiar en la herramienta de function calling sin validar el output con Zod o Pydantic
- No tener audit log y descubrir 3 meses después que el modelo se inventó 200 reportes
- Mezclar prompts de cálculo y de narrativa en el mismo system prompt
- Sin tests de regresión, cada upgrade de modelo introduce silenciosamente nuevos bugs
La arquitectura two-level con KPIs en código resuelve los 5 errores en una sola decisión de diseño. Es el patrón que recomendamos como base para cualquier plataforma con IA que toque dinero, salud o decisiones críticas.
Próximos pasos
Si tu empresa mediana ya usa IA en producción y necesitas migrar a una arquitectura con guardrails y KPIs auditables, MAGIA Forge entrega plataforma completa en 12 semanas por 20,000 USD, código a tu nombre, sin licencias atadas. Si tu operación todavía no tiene IA pero quieres empezar con el diseño correcto desde el día 1, MAGIA Core integra el data lake unificado y la primera capa de reportería en 12 semanas por 15,000 USD. Contexto adicional en Wikipedia: Hallucination (artificial intelligence).