> 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/overall-explainers.md).

# Overall Explainers

**Module:** `sovai.extensions.overall_explainers`

Overall Explainers Module

This module provides functionality to generate comprehensive explanations across multiple charts and analyses within a category. It leverages the hierarchical caching system from chart\_explainer to aggregate data and explanations for holistic insights. Now includes support for table explanations.

## Functions

### `generate_overall_explanation_async()`

```python
def generate_overall_explanation_async(
    category: str,
    cached_data: Dict[str, Any],
    ephemeral_token: str,
) -> str
```

Generate an overall explanation using Gemini AI.

**Parameters**

| Parameter         | Type             | Description                                              |
| ----------------- | ---------------- | -------------------------------------------------------- |
| `category`        | `str`            | str The category to explain (e.g., "signal\_evaluation") |
| `cached_data`     | `Dict[str, Any]` | dict Hierarchical cached data and explanations           |
| `ephemeral_token` | `str`            | str Ephemeral token for Gemini API                       |

**Returns**

str : Comprehensive overall explanation

***

### `explain_overall()`

```python
def explain_overall(
    category: str,
    display_explanation: bool = True,
    force_refresh: bool = False,
) -> Optional[str]
```

Generate a comprehensive explanation for an entire category of analyses.

**Parameters**

| Parameter             | Type   | Description                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| `category`            | `str`  | str The category to explain (e.g., "signal\_evaluation")  |
| `display_explanation` | `bool` | bool Whether to display the explanation immediately       |
| `force_refresh`       | `bool` | bool Whether to regenerate the explanation even if cached |

**Returns**

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

***

### `explain_signal_evaluation()`

```python
def explain_signal_evaluation(display_explanation: bool = True) -> Optional[str]
```

Convenience function to generate overall explanation for signal\_evaluation.

**Parameters**

| Parameter             | Type   | Description                                         |
| --------------------- | ------ | --------------------------------------------------- |
| `display_explanation` | `bool` | bool Whether to display the explanation immediately |

**Returns**

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

***

### `get_category_summary()`

```python
def get_category_summary(category: str) -> Dict[str, Any]
```

Get a summary of all cached data and explanations for a category.

**Parameters**

| Parameter  | Type  | Description                   |
| ---------- | ----- | ----------------------------- |
| `category` | `str` | str The category to summarize |

**Returns**

dict : Summary of cached data and explanations

***

### `list_available_categories()`

```python
def list_available_categories() -> List[str]
```

List all categories that have cached data.

**Returns**

list : List of available categories

***

### `list_category_plots()`

```python
def list_category_plots(category: str) -> List[str]
```

List all plots available for a specific category.

**Parameters**

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

**Returns**

list : List of plot names

***

### `cache_overall_explanation()`

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

Cache an overall explanation for a category.

**Parameters**

| Parameter     | Type  | Description                          |
| ------------- | ----- | ------------------------------------ |
| `category`    | `str` | str The category name                |
| `explanation` | `str` | str The overall explanation to cache |

**Returns:** `None`

***

### `get_cached_overall_explanation()`

```python
def get_cached_overall_explanation(category: str) -> Optional[str]
```

Get a cached overall explanation for a category.

**Parameters**

| Parameter  | Type  | Description           |
| ---------- | ----- | --------------------- |
| `category` | `str` | str The category name |

**Returns**

str or None : The cached explanation, or None if not found

***