> ## 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 (AI agent)

> Describe what you need in natural language and an AI agent builds an insights report with verified numbers, versioned and publishable

<Info>
  **Available on the Corporate plan.** This feature is part of woku's enterprise capabilities. [Talk to our sales team](https://woku.app/pricing).
</Info>

The **Data Studio** is woku's conversational analytics
module. Instead of configuring a report field by
field, you describe what you need in natural language and an AI agent
builds an **insights report** on your company's real
data: KPIs, evidence-backed findings, visualizations, and recommended
actions, ready to review and publish.

It complements the [report builder](/docs/en/reportes/builder-visual): the
builder is **deterministic and schedulable** (ideal for repeatable
deliveries in CSV/Excel/PDF); Data Studio is **exploratory and
conversational** (ideal for getting tailored insights in minutes).

## How it is used

1. You open a conversation and describe the report you want.
2. The agent proposes a **plan** (what data it will use and what it will show) and
   waits for your approval.
3. Once you approve it, it queries the data on the server, analyzes it,
   **verifies every number** against the datasets, and builds the report.
4. You can request **changes in natural language** (including changing the
   analyzed period), go back to a **previous version**, or compute
   **advanced metrics** such as predictions.
5. The report is versioned; you can **publish it** with a public link
   or one protected by a key.

Throughout the whole process the conversation receives live events (the
agent "thinking", the plan, the extracted data, the visual review, and the
finished report).

## How the agent works

The agent is a conversational **orchestrator** that proposes a plan,
waits for your approval, and then runs a deterministic pipeline: it queries
the data on the server, analyzes it, verifies the evidence, renders the
report, and reviews it visually before delivering it.

```mermaid theme={null}
flowchart TD
    U([User]) <-->|live conversation| AG{{"Orchestrator agent"}}

    AG --> P["1 · Propose the plan"]
    P --> OK{"Approve the plan?"}
    OK -->|yes| D["2 · Query the data<br/>always on the server side"]
    D -. query catalog .-> DATOS[("woku data")]

    D --> A["3 · Analyze<br/>KPIs, findings, actions"]
    A --> V["4 · Verify the evidence<br/>each number against the datasets"]
    V --> R["5 · Render the HTML<br/>self-contained, server-side SVG"]
    R --> REV{"Visual review<br/>approved?"}
    REV -->|no · fix| A
    REV -->|yes| LISTO([Versioned, publishable report])
```

### The five tools

| Tool                          | What it does                                                                                                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **generate\_plan**            | Builds the report plan from the full catalog of available queries and proposes it to the user. It does not run anything until you approve it.                            |
| **create\_insight\_report**   | Runs the deterministic pipeline that builds the approved report (see the next section).                                                                                  |
| **revise\_dashboard**         | Applies changes requested in natural language on the existing report, including changing the analyzed period (for example "exclude January" or "only the last quarter"). |
| **set\_dashboard\_version**   | Goes back to a previous version of the report.                                                                                                                           |
| **compute\_advanced\_metric** | Computes advanced metrics, for example predictions, using OpenAI's code interpreter. It only runs with your **explicit consent** to send aggregated data.                |

### The report pipeline

`create_insight_report` is not a free agent, but a **deterministic
pipeline**:

1. **Server data**: the datasets are always queried on the server
   side through the query catalog; the model never touches
   the database.
2. **Analysis**: the analyst produces a structured report with KPIs,
   evidence-backed findings, visualizations, and recommended
   actions.
3. **Evidence verification**: every numeric claim is verified
   against the datasets, with a corrective retry. Findings that
   do not pass verification are discarded: a report never publishes
   unverified numbers.
4. **Deterministic render**: the HTML is generated self-contained, with SVG
   rendered on the server and with no CDN dependencies.
5. **See and repair**: a multimodal model reviews the rendered
   result before delivering it, with a maximum of 2 repair
   rounds.
6. **Persistence**: the report is saved as a new version
   of the app.

### Data access (multi-tenant)

The agent never queries the database directly: it works over a **query
catalog** on the server. The `companyId` is **always** injected from the
authentication context and never from whatever the model says,
guaranteeing isolation between companies.

The catalog covers global KPIs, metrics by woku and by folder,
rating trends, clients and segments, NPS and its
tools, forms and response channels.

## Streaming events (SSE)

The agent endpoint responds as `text/event-stream`. These are the
events it emits:

| Event               | Meaning                                      |
| ------------------- | -------------------------------------------- |
| `thinking`          | Agent reasoning or progress.                 |
| `plan_proposed`     | Plan ready for user review.                  |
| `data_extracted`    | Dataset queried (key, rows).                 |
| `analysis_complete` | Analysis finished (key, type).               |
| `visual_review`     | Visual review result (approved, score).      |
| `screenshot`        | Generated capture of the report.             |
| `app_ready`         | Report built (id, version, URL).             |
| `title`             | Conversation title, generated automatically. |
| `message`           | Assistant's final response.                  |
| `error`             | Error summary.                               |
| `done`              | End of the stream.                           |

## Persistence and publishing

* **Conversation**: message history, captured plan, and executed
  tools.
* **App**: metadata and **immutable versions**, each one keeps its
  own HTML. Reviewing or going back to a previous version never alters
  the others.
* **Publishing**: each app can be published and unpublished; the link
  uses a slug and access can be **public** or **protected by
  key**, with key verification when opening it.

## Limits per conversation

To control cost and abuse, each conversation has caps:

| Limit                     | Value |
| ------------------------- | ----- |
| Messages                  | 20    |
| Built versions            | 5     |
| Cooldown between messages | 1 s   |
| Budget                    | 5 USD |

## Models

* **claude-sonnet-5**, the orchestrator conversation and the report
  analysis.
* **o4-mini**, only the multimodal visual review.
* **gpt-5.5**, fallback for the plan and the analysis under a transient
  overload.

## Data Studio vs. report builder

|                    | Data Studio                                                  | Report builder                               |
| ------------------ | ------------------------------------------------------------ | -------------------------------------------- |
| Input              | Natural language conversation                                | Selection of source, dimensions, and metrics |
| Output             | Interactive HTML report with verified numbers and versioning | Table or chart                               |
| Scheduled delivery | Not available                                                | Scheduled CSV/Excel/PDF by email or SFTP     |
| Nature             | Exploratory, conversational                                  | Deterministic, repeatable                    |

Both read the same data and coexist: use the agent to **explore and
get insights**, and the reports for **governed and scheduled
deliveries**.