Documentation Index
Fetch the complete documentation index at: https://woku.app/docs/llms.txt
Use this file to discover all available pages before exploring further.
Data Studio es el módulo de analítica generativa de woku. En lugar de
configurar un reporte campo por campo, describes lo que necesitas en
lenguaje natural y un agente de IA arma un dashboard interactivo sobre
los datos reales de tu empresa, listo para revisar y publicar.
Complementa al constructor de reportes: el
constructor es determinista y agendable (ideal para entregas
repetibles en CSV/Excel/PDF); Data Studio es exploratorio y creativo
(ideal para crear vistas a medida en minutos).
Cómo se usa
- Abres una conversación y describes el dashboard que quieres.
- El agente propone un plan (qué datos usará y qué mostrará).
- Al aprobarlo, extrae los datos, los analiza si hace falta y
genera la app.
- La app queda versionada; puedes publicarla con un enlace público o
protegido por clave.
Durante todo el proceso la conversación recibe eventos en vivo (el agente
“pensando”, el plan, el progreso de cada componente y la revisión visual).
Arquitectura del agente
El agente es un orquestador que coordina cuatro pasos: planificar,
extraer los datos, analizarlos (si hace falta) y generar el dashboard.
Durante todo el proceso envía eventos en vivo a la conversación, así ves
el avance en tiempo real.
Las cuatro herramientas
| Herramienta | Modelo | Qué hace |
|---|
| generate_plan | Claude Opus | Busca contexto en la base de conocimiento (Pinecone) y produce un plan de usuario + un plan técnico (consultas, transformaciones, análisis y componentes). |
| extract_data | sub-agente o4-mini | Selecciona y ejecuta consultas CQRS, transforma los resultados y sube cada dataset a S3. |
| analyze_data | sub-agente o4-mini | Análisis numérico (intérprete de código) o de texto (NLP) sobre los datasets; solo se ejecuta si el plan lo requiere. |
| create_app | Claude Sonnet + o4-mini | Genera los componentes React, valida, ensambla el HTML, hace revisión visual y guarda la app versionada. |
Bucle de construcción de la app
create_app no es un agente libre, sino un bucle determinista:
- Generación de componentes: Claude Sonnet escribe el JSX de cada
componente, validado con
esbuild (hasta 2 reintentos por componente).
- Ensamblado: se concatenan los componentes (hojas primero, raíz al
final) y se monta una raíz de React sobre una plantilla HTML.
- Revisión visual: se captura una screenshot (escritorio y móvil) con
Puppeteer y un modelo o4-mini la puntúa de 0 a 10; si no aprueba, se
regeneran los componentes señalados (hasta 2 reconstrucciones).
- Persistencia: el HTML se sube a S3 y se crea la
DataApp con su
primera versión.
Acceso a los datos (multi-tenant)
El agente nunca consulta la base directo: usa un Tool Registry que
expone consultas CQRS (wokus, carpetas, clientes, formularios, NPS, etc.)
como herramientas. El companyId siempre se inyecta desde el contexto
de autenticación y nunca desde lo que diga el modelo, garantizando el
aislamiento entre empresas.
Eventos en streaming (SSE)
El endpoint del agente responde como text/event-stream. Estos son los
eventos que emite:
| Evento | Significado |
|---|
thinking | Razonamiento o progreso del agente. |
plan_proposed | Plan listo para revisión del usuario. |
data_extracted | Dataset extraído (clave, filas). |
analysis_complete | Análisis terminado (clave, tipo). |
component_progress | Estado de generación de un componente. |
visual_review | Resultado de la revisión visual (aprobado, puntaje). |
screenshot | Captura generada (escritorio o móvil). |
app_ready | App construida (id, versión, URL). |
message | Respuesta final del asistente. |
error | Resumen de error. |
done | Fin del stream. |
Persistencia
- Conversación (
DataAppConversation): historial de mensajes, plan
capturado, herramientas ejecutadas y adjuntos.
- App (
DataApp): metadatos, versiones (cada una apunta a su HTML
en S3), modo static o dynamic, consultas asociadas, y estado de
publicación (slug, acceso public o key).
Una app dynamic re-ejecuta sus consultas al renderizar (datos frescos);
una static sirve el HTML tal cual se generó.
Límites por conversación
Para controlar costo y abuso, cada conversación tiene topes:
| Límite | Valor |
|---|
| Mensajes | 20 |
| Apps construidas | 5 |
| Enfriamiento entre mensajes | 1 s |
| Presupuesto | 5 USD |
Modelos y dependencias
- Claude Opus, planificación.
- Claude Sonnet, orquestación, generación de componentes y resúmenes.
- o4-mini, extracción, análisis y revisión visual.
- Pinecone, base de conocimiento (búsqueda semántica con embeddings).
- Puppeteer, capturas para la revisión visual.
- S3, almacenamiento de HTML, datasets y screenshots.
Data Studio vs. constructor de reportes
| Data Studio | Constructor de reportes |
|---|
| Entrada | Conversación en lenguaje natural | Selección de fuente, dimensiones y métricas |
| Salida | Dashboard HTML interactivo y publicable | Tabla o gráfico |
| Entrega agendada | | CSV/Excel/PDF por cron (email/SFTP) |
| Naturaleza | Exploratorio, creativo | Determinista, repetible |
