# 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

***


---

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