backend redesign

backend.old/src/agent/tools/CHART_UTILS_README.md

@@ -0,0 +1,139 @@
+# 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)