Cycles/IncrementalTrader/README.md

# IncrementalTrader

A high-performance, memory-efficient trading framework designed for real-time algorithmic trading and backtesting. Built around the principle of **incremental computation**, IncrementalTrader processes new data points efficiently without recalculating entire histories.

## 🚀 Key Features

- **Incremental Computation**: Constant memory usage and O(1) processing time per data point
- **Real-time Capable**: Designed for live trading with minimal latency
- **Modular Architecture**: Clean separation between strategies, execution, and testing
- **Built-in Strategies**: MetaTrend, BBRS, and Random strategies included
- **Comprehensive Backtesting**: Multi-threaded backtesting with parameter optimization
- **Rich Indicators**: Supertrend, Bollinger Bands, RSI, Moving Averages, and more
- **Performance Tracking**: Detailed metrics and portfolio analysis

## 📦 Installation

```bash
# Clone the repository
git clone <repository-url>
cd Cycles

# Install dependencies
pip install -r requirements.txt

# Import the module
from IncrementalTrader import *
```

## 🏃‍♂️ Quick Start

### Basic Strategy Usage

```python
from IncrementalTrader import MetaTrendStrategy, IncTrader
import pandas as pd

# Load your data
data = pd.read_csv('your_data.csv')

# Create strategy
strategy = MetaTrendStrategy("metatrend", params={
    "timeframe": "15min",
    "supertrend_periods": [10, 20, 30],
    "supertrend_multipliers": [2.0, 3.0, 4.0]
})

# Create trader
trader = IncTrader(strategy, initial_usd=10000)

# Process data
for _, row in data.iterrows():
    trader.process_data_point(
        timestamp=row['timestamp'],
        ohlcv=(row['open'], row['high'], row['low'], row['close'], row['volume'])
    )

# Get results
results = trader.get_results()
print(f"Final Portfolio Value: ${results['final_portfolio_value']:.2f}")
print(f"Total Return: {results['total_return_pct']:.2f}%")
```

### Backtesting

```python
from IncrementalTrader import IncBacktester, BacktestConfig

# Configure backtest
config = BacktestConfig(
    initial_usd=10000,
    stop_loss_pct=0.03,
    take_profit_pct=0.06,
    start_date="2024-01-01",
    end_date="2024-12-31"
)

# Run backtest
backtester = IncBacktester()
results = backtester.run_single_strategy(
    strategy_class=MetaTrendStrategy,
    strategy_params={"timeframe": "15min"},
    config=config,
    data_file="data/BTCUSDT_1m.csv"
)

# Analyze results
print(f"Sharpe Ratio: {results['performance_metrics']['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {results['performance_metrics']['max_drawdown_pct']:.2f}%")
```

## 📊 Available Strategies

### MetaTrend Strategy
A sophisticated trend-following strategy that uses multiple Supertrend indicators to detect market trends.

```python
strategy = MetaTrendStrategy("metatrend", params={
    "timeframe": "15min",
    "supertrend_periods": [10, 20, 30],
    "supertrend_multipliers": [2.0, 3.0, 4.0],
    "min_trend_agreement": 0.6
})
```

### BBRS Strategy
Combines Bollinger Bands and RSI with market regime detection for adaptive trading.

```python
strategy = BBRSStrategy("bbrs", params={
    "timeframe": "15min",
    "bb_period": 20,
    "bb_std": 2.0,
    "rsi_period": 14,
    "volume_ma_period": 20
})
```

### Random Strategy
A testing strategy that generates random signals for framework validation.

```python
strategy = RandomStrategy("random", params={
    "timeframe": "15min",
    "buy_probability": 0.1,
    "sell_probability": 0.1
})
```

## 🔧 Technical Indicators

All indicators are designed for incremental computation:

```python
from IncrementalTrader.strategies.indicators import *

# Moving Averages
sma = MovingAverageState(period=20)
ema = ExponentialMovingAverageState(period=20, alpha=0.1)

# Volatility
atr = ATRState(period=14)

# Trend
supertrend = SupertrendState(period=10, multiplier=3.0)

# Oscillators
rsi = RSIState(period=14)
bb = BollingerBandsState(period=20, std_dev=2.0)

# Update with new data
for price in price_data:
    sma.update(price)
    current_sma = sma.get_value()
```

## 🧪 Parameter Optimization

```python
from IncrementalTrader import OptimizationConfig

# Define parameter ranges
param_ranges = {
    "supertrend_periods": [[10, 20, 30], [15, 25, 35], [20, 30, 40]],
    "supertrend_multipliers": [[2.0, 3.0, 4.0], [1.5, 2.5, 3.5]],
    "min_trend_agreement": [0.5, 0.6, 0.7, 0.8]
}

# Configure optimization
opt_config = OptimizationConfig(
    base_config=config,
    param_ranges=param_ranges,
    max_workers=4
)

# Run optimization
results = backtester.optimize_strategy(
    strategy_class=MetaTrendStrategy,
    optimization_config=opt_config,
    data_file="data/BTCUSDT_1m.csv"
)

# Get best parameters
best_params = results['best_params']
best_performance = results['best_performance']
```

## 📈 Performance Analysis

```python
# Get detailed performance metrics
performance = results['performance_metrics']

print(f"Total Trades: {performance['total_trades']}")
print(f"Win Rate: {performance['win_rate']:.2f}%")
print(f"Profit Factor: {performance['profit_factor']:.2f}")
print(f"Sharpe Ratio: {performance['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {performance['max_drawdown_pct']:.2f}%")
print(f"Calmar Ratio: {performance['calmar_ratio']:.2f}")

# Access trade history
trades = results['trades']
for trade in trades[-5:]:  # Last 5 trades
    print(f"Trade: {trade['side']} at {trade['price']} - P&L: {trade['pnl']:.2f}")
```

## 🏗️ Architecture

IncrementalTrader follows a modular architecture:

```
IncrementalTrader/
├── strategies/          # Trading strategies and indicators
│   ├── base.py         # Base classes and framework
│   ├── metatrend.py    # MetaTrend strategy
│   ├── bbrs.py         # BBRS strategy
│   ├── random.py       # Random strategy
│   └── indicators/     # Technical indicators
├── trader/             # Trade execution and position management
│   ├── trader.py       # Main trader implementation
│   └── position.py     # Position management
├── backtester/         # Backtesting framework
│   ├── backtester.py   # Main backtesting engine
│   ├── config.py       # Configuration management
│   └── utils.py        # Utilities and helpers
└── docs/               # Documentation
```

## 🔍 Memory Efficiency

Traditional batch processing vs. IncrementalTrader:

| Aspect | Batch Processing | IncrementalTrader |
|--------|------------------|-------------------|
| Memory Usage | O(n) - grows with data | O(1) - constant |
| Processing Time | O(n) - recalculates all | O(1) - per data point |
| Real-time Capable | No - too slow | Yes - designed for it |
| Scalability | Poor - memory limited | Excellent - unlimited data |

## 📚 Documentation

- [Architecture Overview](docs/architecture.md) - Detailed system design
- [Strategy Development Guide](docs/strategies/strategies.md) - How to create custom strategies
- [Indicator Reference](docs/indicators/base.md) - Complete indicator documentation
- [Backtesting Guide](docs/backtesting.md) - Advanced backtesting features
- [API Reference](docs/api/api.md) - Complete API documentation

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For questions, issues, or contributions:
- Open an issue on GitHub
- Check the documentation in the `docs/` folder
- Review the examples in the `examples/` folder

---

**IncrementalTrader** - Efficient, scalable, and production-ready algorithmic trading framework.