> 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/signal-evaluation.md).

# Signal Evaluation

**Module:** `sovai.extensions.signal_evaluation`

## Classes

### `SignalEvaluator`

```python
class SignalEvaluator
```

**Attributes**

* `verbose`
* `df_factor`
* `positions`
* `rebalance_mask`
* `holdings`
* `returns`
* `position_returns`
* `resampled_returns`
* `portfolio_returns`
* `cumulative_returns`
* `performance_plot`
* `performance_table`
* `stress_plot`
* `distribution_plot`
* `drawdown_plot`
* `drawdown_table`
* `returns_heatmap_plot`
* `turnover_plot`
* `signal_correlation_plot`
* `signal_decile_plot`

***

## Functions

### `enrich_figure_with_llm_metadata()`

```python
def enrich_figure_with_llm_metadata(
    fig,
    title: Optional[str] = None,
    description: Optional[str] = None,
    key_stats: Optional[Dict[str, Any]] = None,
    downsample: bool = False,
    target_points: int = 768,
    include_image_export: bool = True,
    image_format: str = 'png',
    image_width: int = 1600,
    image_height: int = 900,
    image_scale: int = 2,
    category: str = 'signal_evaluation',
) -> None
```

Enrich a Plotly figure with LLM-ready metadata.

This function adds metadata to fig.layout.meta that can be used for feeding the figure to an LLM. Modifies the figure in-place.

**Parameters**

| Parameter              | Type                       | Description                                                    |
| ---------------------- | -------------------------- | -------------------------------------------------------------- |
| `fig`                  | —                          | plotly.graph\_objects.Figure The Plotly figure to enrich       |
| `title`                | `Optional[str]`            | str, optional Chart title override                             |
| `description`          | `Optional[str]`            | str, optional Chart description                                |
| `key_stats`            | `Optional[Dict[str, Any]]` | dict, optional Dictionary of key statistics                    |
| `downsample`           | `bool`                     | bool Whether to apply LTTB downsampling in the compressed spec |
| `target_points`        | `int`                      | int Target number of points for downsampling                   |
| `include_image_export` | `bool`                     | bool Whether to generate image export metadata                 |
| `image_format`         | `str`                      | str Image format ('png', 'webp', 'jpeg', 'svg')                |
| `image_width`          | `int`                      | int Image width in pixels                                      |
| `image_height`         | `int`                      | int Image height in pixels                                     |
| `image_scale`          | `int`                      | int Image scale factor                                         |

**Returns**

None (modifies fig in-place)

***

### `export_figure_for_llm()`

```python
def export_figure_for_llm(
    fig,
    include_image: bool = True,
    image_format: str = 'png',
    return_base64: bool = True,
) -> Dict[str, Any]
```

Export a figure with LLM metadata for direct use in LLM prompts.

**Parameters**

| Parameter       | Type   | Description                                                      |
| --------------- | ------ | ---------------------------------------------------------------- |
| `fig`           | —      | plotly.graph\_objects.Figure The Plotly figure with LLM metadata |
| `include_image` | `bool` | bool Whether to export the actual image                          |
| `image_format`  | `str`  | str Image format ('png', 'webp', 'jpeg', 'svg')                  |
| `return_base64` | `bool` | bool Whether to return image as base64 (vs. raw bytes)           |

**Returns**

dict : Contains chart\_card, spec\_capsule, alt\_text, and optionally image

***