> ## 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 (agente de IA)

> Crea dashboards a partir de tus datos describiéndolos en lenguaje natural: el agente planifica, extrae, analiza y genera una app publicable

<Info>
  **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing).
</Info>

**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](/reportes/builder-visual): 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

1. Abres una conversación y describes el dashboard que quieres.
2. El agente propone un **plan** (qué datos usará y qué mostrará).
3. Al aprobarlo, **extrae** los datos, los **analiza** si hace falta y
   **genera** la app.
4. 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.

```mermaid theme={null}
flowchart TD
    U([Usuario]) <-->|conversación en vivo| AG{{"Agente orquestador"}}

    AG --> P["1 · Planificar<br/>qué mostrar y con qué datos"]
    P --> E["2 · Extraer los datos"]
    E --> A["3 · Analizar · si hace falta"]
    A --> C["4 · Generar el dashboard"]

    P -. consulta .-> RAG[("Conocimiento · RAG<br/>qué datos y consultas existen")]
    E -. consulta .-> DATOS[("Datos de woku")]

    C --> BUILD
    subgraph BUILD["Generar el dashboard"]
      direction TB
      G["Crear los componentes"] --> V["Validar y ensamblar"]
      V --> R{"¿Se ve bien?"}
      R -->|no · reintenta| G
      R -->|sí| OK([Dashboard publicable])
    end
```

### 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**:

1. **Generación de componentes**: Claude Sonnet escribe el JSX de cada
   componente, validado con `esbuild` (hasta 2 reintentos por componente).
2. **Ensamblado**: se concatenan los componentes (hojas primero, raíz al
   final) y se monta una raíz de React sobre una plantilla HTML.
3. **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).
4. **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                     |

Ambos leen los mismos datos y conviven: usa el agente para **crear y
explorar**, y los reportes para **entregas gobernadas y agendadas**.