> 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/table-explainer.md).

# Table Explainer

**Module:** `sovai.extensions.table_explainer`

Table Explanation Module using Gemini via Ephemeral Token Broker

This module provides functionality to automatically explain table data using Google's Gemini model through a secure ephemeral token broker. It integrates with the existing chart explanation caching system.

## Functions

### `explain_table_async()`

```python
def explain_table_async(
    table_data: pd.DataFrame,
    table_metadata: Dict[str, Any],
    ephemeral_token: str,
) -> str
```

Use Gemini to explain the table using metadata.

**Parameters**

| Parameter         | Type             | Description                                                     |
| ----------------- | ---------------- | --------------------------------------------------------------- |
| `table_data`      | `pd.DataFrame`   | pd.DataFrame The table data to explain                          |
| `table_metadata`  | `Dict[str, Any]` | dict Table metadata including title, description, and key stats |
| `ephemeral_token` | `str`            | str Ephemeral token for Gemini API                              |

**Returns**

str : Markdown explanation of the table

***

### `explain_table()`

```python
def explain_table(
    table_data: pd.DataFrame,
    title: str,
    description: Optional[str] = None,
    table_type: str = 'general',
    display_explanation: bool = True,
    category: str = None,
    plot_name: str = None,
    cache_data: bool = True,
) -> Optional[str]
```

Generate an explanation for a table with LLM analysis.

**Parameters**

| Parameter             | Type            | Description                                                          |
| --------------------- | --------------- | -------------------------------------------------------------------- |
| `table_data`          | `pd.DataFrame`  | pd.DataFrame The table data to explain                               |
| `title`               | `str`           | str Table title                                                      |
| `description`         | `Optional[str]` | str, optional Table description                                      |
| `table_type`          | `str`           | str Type of table (e.g., "performance\_stats", "drawdown\_analysis") |
| `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")   |
| `cache_data`          | `bool`          | bool Whether to cache the table data and explanation                 |

**Returns**

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

***

### `explain_performance_table()`

```python
def explain_performance_table(
    evaluator,
    display_explanation: bool = True,
    cache_data: bool = True,
) -> Optional[str]
```

Convenience function to explain the performance table from a SignalEvaluator.

**Parameters**

| Parameter             | Type   | Description                                                          |
| --------------------- | ------ | -------------------------------------------------------------------- |
| `evaluator`           | —      | SignalEvaluator The SignalEvaluator instance with performance\_table |
| `display_explanation` | `bool` | bool Whether to display the explanation immediately                  |
| `cache_data`          | `bool` | bool Whether to cache the table data and explanation                 |

**Returns**

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

***

### `explain_drawdown_table()`

```python
def explain_drawdown_table(
    evaluator,
    display_explanation: bool = True,
    cache_data: bool = True,
) -> Optional[str]
```

Convenience function to explain the drawdown table from a SignalEvaluator.

**Parameters**

| Parameter             | Type   | Description                                                       |
| --------------------- | ------ | ----------------------------------------------------------------- |
| `evaluator`           | —      | SignalEvaluator The SignalEvaluator instance with drawdown\_table |
| `display_explanation` | `bool` | bool Whether to display the explanation immediately               |
| `cache_data`          | `bool` | bool Whether to cache the table data and explanation              |

**Returns**

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

***

### `get_cached_table_explanations()`

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

Retrieve cached table explanations.

**Parameters**

| Parameter   | Type  | Description                       |
| ----------- | ----- | --------------------------------- |
| `category`  | `str` | str, optional Filter by category  |
| `plot_name` | `str` | str, optional Filter by plot name |

**Returns**

dict : Cached table explanations

***

### `list_available_table_categories()`

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

List all categories that have cached table explanations.

**Returns**

list : List of available categories

***