> 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

**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)

***