Chart Explainer

Chart Explanation Module using Gemini via Ephemeral Token Broker

Module: sovai.extensions.chart_explainer

Chart Explanation Module using Gemini via Ephemeral Token Broker

This module provides functionality to automatically explain chart metadata using Google's Gemini model through a secure ephemeral token broker.

Functions

cache_chart_data()

def cache_chart_data(category: str, plot_name: str, chart_card: Dict[str, Any]) -> None

Cache chart data hierarchically.

Parameters

Parameter	Type	Description
category	str	str The category (e.g., "signal_evaluation")
plot_name	str	str The name of the specific plot/analysis
chart_card	Dict[str, Any]	dict Chart metadata and statistics

Returns: None

---

cache_explanation()

def cache_explanation(category: str, plot_name: str, explanation: str) -> None

Cache explanation hierarchically.

Parameters

Parameter	Type	Description
category	str	str The category (e.g., "signal_evaluation")
plot_name	str	str The name of the specific plot/analysis
explanation	str	str The generated explanation

Returns: None

---

get_cached_data()

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

Retrieve cached data and explanations.

Parameters

Parameter	Type	Description
category	str	str, optional Filter by category. If None, returns all categories
plot_name	str	str, optional Filter by plot name. If None, returns all plots in category

Returns

dict : Hierarchical dictionary of cached data and explanations

---

list_cached_categories()

def list_cached_categories() -> list

List all available categories in the cache.

Returns

list : List of category names

---

list_cached_plots()

def list_cached_plots(category: str) -> list

List all available plots for a given category.

Parameters

Parameter	Type	Description
category	str	str The category to list plots for

Returns

list : List of plot names

---

get_ephemeral_token()

def get_ephemeral_token(
    sovai_token: str = SOVAI_TOKEN,
    broker_url: str = BROKER_URL,
) -> Optional[str]

Get ephemeral token from the broker using Sovai key.

Parameters

Parameter	Type	Description
sovai_token	str	str The Sovai authentication token
broker_url	str	str The broker endpoint URL

Returns

str or None : Ephemeral token if successful, None otherwise

---

explain_chart_async()

def explain_chart_async(
    chart_card: Dict[str, Any],
    key_stats: Dict[str, Any],
    description: str,
    ephemeral_token: str,
) -> str

Use Gemini to explain the chart using metadata.

Parameters

Parameter	Type	Description
chart_card	Dict[str, Any]	dict Chart metadata including title, axes, series info
key_stats	Dict[str, Any]	dict Key statistics from the chart
description	str	str Chart description
ephemeral_token	str	str Ephemeral token for Gemini API

Returns

str : Markdown explanation of the chart

---

explain_chart()

def explain_chart(
    fig,
    display_explanation: bool = True,
    category: str = None,
    plot_name: str = None,
) -> Optional[str]

Synchronous wrapper to explain a chart with LLM metadata.

Parameters

Parameter	Type	Description
fig	—	plotly.graph_objects.Figure The Plotly figure with LLM metadata
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")

Returns

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

---

auto_explain_chart()

def auto_explain_chart(fig)

Automatically explain a chart after it's created.

This is a convenience function that can be called after generating any plot to get an AI explanation.

Parameters

Parameter	Type	Description
fig	—	plotly.graph_objects.Figure The Plotly figure to explain

Returns

plotly.graph_objects.Figure : The same figure (for chaining)

---