Table Explainer

Table Explanation Module using Gemini via Ephemeral Token Broker

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

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

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

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

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

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

def list_available_table_categories() -> List[str]

List all categories that have cached table explanations.

Returns

list : List of available categories

---