> For the complete documentation index, see [llms.txt](https://docs.sov.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sov.ai/api-reference/extensions/chart-explainer.md).

# Chart Explainer

Chart Explanation Module using Gemini via Ephemeral Token Broker

**Module:** `sovai.extensions.chart_explainer`

Chart Explanation Module using Gemini via Ephemeral Token Broker

This module provides functionality to automatically explain chart metadata using Google's Gemini model through a secure ephemeral token broker.

## Functions

### `cache_chart_data()`

```python
def cache_chart_data(category: str, plot_name: str, chart_card: Dict[str, Any]) -> None
```

Cache chart data hierarchically.

**Parameters**

| Parameter    | Type             | Description                                   |
| ------------ | ---------------- | --------------------------------------------- |
| `category`   | `str`            | str The category (e.g., "signal\_evaluation") |
| `plot_name`  | `str`            | str The name of the specific plot/analysis    |
| `chart_card` | `Dict[str, Any]` | dict Chart metadata and statistics            |

**Returns:** `None`

***

### `cache_explanation()`

```python
def cache_explanation(category: str, plot_name: str, explanation: str) -> None
```

Cache explanation hierarchically.

**Parameters**

| Parameter     | Type  | Description                                   |
| ------------- | ----- | --------------------------------------------- |
| `category`    | `str` | str The category (e.g., "signal\_evaluation") |
| `plot_name`   | `str` | str The name of the specific plot/analysis    |
| `explanation` | `str` | str The generated explanation                 |

**Returns:** `None`

***

### `get_cached_data()`

```python
def get_cached_data(category: str = None, plot_name: str = None) -> Dict[str, Any]
```

Retrieve cached data and explanations.

**Parameters**

| Parameter   | Type  | Description                                                               |
| ----------- | ----- | ------------------------------------------------------------------------- |
| `category`  | `str` | str, optional Filter by category. If None, returns all categories         |
| `plot_name` | `str` | str, optional Filter by plot name. If None, returns all plots in category |

**Returns**

dict : Hierarchical dictionary of cached data and explanations

***

### `list_cached_categories()`

```python
def list_cached_categories() -> list
```

List all available categories in the cache.

**Returns**

list : List of category names

***

### `list_cached_plots()`

```python
def list_cached_plots(category: str) -> list
```

List all available plots for a given category.

**Parameters**

| Parameter  | Type  | Description                        |
| ---------- | ----- | ---------------------------------- |
| `category` | `str` | str The category to list plots for |

**Returns**

list : List of plot names

***

### `get_ephemeral_token()`

```python
def get_ephemeral_token(
    sovai_token: str = SOVAI_TOKEN,
    broker_url: str = BROKER_URL,
) -> Optional[str]
```

Get ephemeral token from the broker using Sovai key.

**Parameters**

| Parameter     | Type  | Description                        |
| ------------- | ----- | ---------------------------------- |
| `sovai_token` | `str` | str The Sovai authentication token |
| `broker_url`  | `str` | str The broker endpoint URL        |

**Returns**

str or None : Ephemeral token if successful, None otherwise

***

### `explain_chart_async()`

```python
def explain_chart_async(
    chart_card: Dict[str, Any],
    key_stats: Dict[str, Any],
    description: str,
    ephemeral_token: str,
) -> str
```

Use Gemini to explain the chart using metadata.

**Parameters**

| Parameter         | Type             | Description                                            |
| ----------------- | ---------------- | ------------------------------------------------------ |
| `chart_card`      | `Dict[str, Any]` | dict Chart metadata including title, axes, series info |
| `key_stats`       | `Dict[str, Any]` | dict Key statistics from the chart                     |
| `description`     | `str`            | str Chart description                                  |
| `ephemeral_token` | `str`            | str Ephemeral token for Gemini API                     |

**Returns**

str : Markdown explanation of the chart

***

### `explain_chart()`

```python
def explain_chart(
    fig,
    display_explanation: bool = True,
    category: str = None,
    plot_name: str = None,
) -> Optional[str]
```

Synchronous wrapper to explain a chart with LLM metadata.

**Parameters**

| Parameter             | Type   | Description                                                        |
| --------------------- | ------ | ------------------------------------------------------------------ |
| `fig`                 | —      | plotly.graph\_objects.Figure The Plotly figure with LLM metadata   |
| `display_explanation` | `bool` | bool Whether to display the explanation immediately                |
| `category`            | `str`  | str, optional Category for caching (e.g., "signal\_evaluation")    |
| `plot_name`           | `str`  | str, optional Plot name for caching (e.g., "performance\_metrics") |

**Returns**

str or None : The explanation markdown, or None if failed

***

### `auto_explain_chart()`

```python
def auto_explain_chart(fig)
```

Automatically explain a chart after it's created.

This is a convenience function that can be called after generating any plot to get an AI explanation.

**Parameters**

| Parameter | Type | Description                                               |
| --------- | ---- | --------------------------------------------------------- |
| `fig`     | —    | plotly.graph\_objects.Figure The Plotly figure to explain |

**Returns**

plotly.graph\_objects.Figure : The same figure (for chaining)

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sov.ai/api-reference/extensions/chart-explainer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.