# Chart Utilities - Standard OHLC Plotting

## Overview

The `chart_utils.py` module provides convenience functions for creating beautiful, professional OHLC candlestick charts with a consistent look and feel. This is designed to be used by the LLM in `analyze_chart_data` scripts, eliminating the need to write custom matplotlib code for every chart.

## Key Features

- **Beautiful by default**: Uses mplfinance with seaborn-inspired aesthetics
- **Consistent styling**: Professional color scheme (teal green up, coral red down)
- **Easy to use**: Simple function calls instead of complex matplotlib code
- **Customizable**: Supports all mplfinance options via kwargs
- **Volume integration**: Optional volume subplot

## Installation

The required package `mplfinance` has been added to `requirements.txt`:

```bash
pip install mplfinance
```

## Available Functions

### 1. `plot_ohlc(df, title=None, volume=True, figsize=(14, 8), **kwargs)`

Main function for creating standard OHLC candlestick charts.

**Parameters:**
- `df`: pandas DataFrame with DatetimeIndex and OHLCV columns
- `title`: Optional chart title
- `volume`: Whether to include volume subplot (default: True)
- `figsize`: Figure size in inches (default: (14, 8))
- `**kwargs`: Additional mplfinance.plot() arguments

**Example:**
```python
fig = plot_ohlc(df, title='BTC/USDT 15min', volume=True)
```

### 2. `add_indicators_to_plot(df, indicators, **plot_kwargs)`

Creates OHLC chart with technical indicators overlaid.

**Parameters:**
- `df`: DataFrame with OHLCV data and indicator columns
- `indicators`: Dict mapping indicator column names to display parameters
- `**plot_kwargs`: Additional arguments for plot_ohlc()

**Example:**
```python
df['SMA_20'] = df['close'].rolling(20).mean()
df['SMA_50'] = df['close'].rolling(50).mean()

fig = add_indicators_to_plot(
    df,
    indicators={
        'SMA_20': {'color': 'blue', 'width': 1.5},
        'SMA_50': {'color': 'red', 'width': 1.5}
    },
    title='Price with Moving Averages'
)
```

### 3. Preset Functions

- `plot_price_volume(df, title=None)` - Standard price + volume chart
- `plot_price_only(df, title=None)` - Candlesticks without volume

## Integration with analyze_chart_data

These functions are automatically available in the `analyze_chart_data` tool's script environment:

```python
# In an analyze_chart_data script:
# df is already provided

# Simple usage
fig = plot_ohlc(df, title='Price Action')

# With indicators
df['SMA'] = df['close'].rolling(20).mean()
fig = add_indicators_to_plot(
    df,
    indicators={'SMA': {'color': 'blue', 'width': 1.5}},
    title='Price with SMA'
)

# Return data for the assistant
df[['close', 'SMA']].tail(10)
```

## Styling

The default style includes:
- **Up candles**: Teal green (#26a69a)
- **Down candles**: Coral red (#ef5350)
- **Background**: Light gray with white axes
- **Grid**: Subtle dashed lines with 30% alpha
- **Professional fonts**: Clean, readable sizes

## Why This Matters

**Before:**
```python
# LLM had to write this every time
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(12, 6))
ax.plot(df.index, df['close'], label='Close')
# ... lots more code for styling, colors, etc.
```

**After:**
```python
# LLM can now just do this
fig = plot_ohlc(df, title='BTC/USDT')
```

Benefits:
- ✅ Less code to generate → faster response
- ✅ Consistent appearance across all charts
- ✅ Professional look out of the box
- ✅ Easier to maintain and customize
- ✅ Better use of mplfinance's candlestick rendering

## Example Output

See `chart_utils_example.py` for runnable examples demonstrating:
1. Basic OHLC chart with volume
2. OHLC chart with multiple indicators
3. Price-only chart
4. Custom styling options

## File Locations

- **Main module**: `backend/src/agent/tools/chart_utils.py`
- **Integration**: `backend/src/agent/tools/chart_tools.py` (lines 306-328)
- **Examples**: `backend/src/agent/tools/chart_utils_example.py`
- **Dependency**: `backend/requirements.txt` (mplfinance added)