Overall Explainers

Overall Explainers Module

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

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

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

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

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

def list_available_categories() -> List[str]

List all categories that have cached data.

Returns

list : List of available categories

---

list_category_plots()

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

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

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

---