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

***


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.