# 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

***


---

# 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/table-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.