Cycles/README.md

# Cycles - Advanced Trading Strategy Backtesting Framework

A sophisticated Python framework for backtesting cryptocurrency trading strategies with multi-timeframe analysis, strategy combination, and advanced signal processing.

## Features

- **Multi-Strategy Architecture**: Combine multiple trading strategies with configurable weights and rules
- **Multi-Timeframe Analysis**: Strategies can operate on different timeframes (1min, 5min, 15min, 1h, etc.)
- **Advanced Strategies**:
  - **Default Strategy**: Meta-trend analysis using multiple Supertrend indicators
  - **BBRS Strategy**: Bollinger Bands + RSI with market regime detection
- **Flexible Signal Combination**: Weighted consensus, majority voting, any/all combinations
- **Precise Stop-Loss**: 1-minute precision for accurate risk management
- **Comprehensive Backtesting**: Detailed performance metrics and trade analysis
- **Data Visualization**: Interactive charts and performance plots

## Quick Start

### Prerequisites

- Python 3.8+
- [uv](https://github.com/astral-sh/uv) package manager (recommended)

### Installation

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

# Install dependencies with uv
uv sync

# Or install with pip
pip install -r requirements.txt
```

### Running Backtests

Use the `uv run` command to execute backtests with different configurations:

```bash
# Run default strategy on 5-minute timeframe
uv run .\main.py .\configs\config_default_5min.json

# Run default strategy on 15-minute timeframe
uv run .\main.py .\configs\config_default.json

# Run BBRS strategy with market regime detection
uv run .\main.py .\configs\config_bbrs.json

# Run combined strategies
uv run .\main.py .\configs\config_combined.json
```

### Configuration Examples

#### Default Strategy (5-minute timeframe)
```bash
uv run .\main.py .\configs\config_default_5min.json
```

#### BBRS Strategy with Multi-timeframe Analysis
```bash
uv run .\main.py .\configs\config_bbrs_multi_timeframe.json
```

#### Combined Strategies with Weighted Consensus
```bash
uv run .\main.py .\configs\config_combined.json
```

## Configuration

Strategies are configured using JSON files in the `configs/` directory:

```json
{
    "start_date": "2024-01-01",
    "stop_date": "2024-01-31",
    "initial_usd": 10000,
    "timeframes": ["15min"],
    "stop_loss_pcts": [0.03, 0.05],
    "strategies": [
        {
            "name": "default",
            "weight": 1.0,
            "params": {
                "timeframe": "15min"
            }
        }
    ],
    "combination_rules": {
        "entry": "any",
        "exit": "any",
        "min_confidence": 0.5
    }
}
```

### Available Strategies

1. **Default Strategy**: Meta-trend analysis using Supertrend indicators
2. **BBRS Strategy**: Bollinger Bands + RSI with market regime detection

### Combination Rules

- **Entry**: `any`, `all`, `majority`, `weighted_consensus`
- **Exit**: `any`, `all`, `priority` (prioritizes stop-loss signals)

## Project Structure

```
Cycles/
├── configs/                 # Configuration files
├── cycles/                  # Core framework
│   ├── strategies/         # Strategy implementation
│   │   ├── base.py        # Base strategy classes
│   │   ├── default_strategy.py
│   │   ├── bbrs_strategy.py
│   │   └── manager.py     # Strategy manager
│   ├── Analysis/          # Technical analysis
│   ├── utils/             # Utilities
│   └── charts.py          # Visualization
├── docs/                   # Documentation
├── data/                   # Market data
├── results/               # Backtest results
└── main.py               # Main entry point
```

## Documentation

Detailed documentation is available in the `docs/` directory:

- **[Strategy Manager](./docs/strategy_manager.md)** - Multi-strategy orchestration and signal combination
- **[Strategies](./docs/strategies.md)** - Individual strategy implementations and usage
- **[Timeframe System](./docs/timeframe_system.md)** - Advanced timeframe management and multi-timeframe strategies
- **[Analysis](./docs/analysis.md)** - Technical analysis components
- **[Storage Utils](./docs/utils_storage.md)** - Data storage and retrieval
- **[System Utils](./docs/utils_system.md)** - System utilities

## Examples

### Single Strategy Backtest
```bash
# Test default strategy on different timeframes
uv run .\main.py .\configs\config_default.json      # 15min
uv run .\main.py .\configs\config_default_5min.json # 5min
```

### Multi-Strategy Backtest
```bash
# Combine multiple strategies with different weights
uv run .\main.py .\configs\config_combined.json
```

### Custom Configuration
Create your own configuration file and run:
```bash
uv run .\main.py .\configs\your_config.json
```

## Output

Backtests generate:
- **CSV Results**: Detailed performance metrics per timeframe/strategy
- **Trade Log**: Individual trade records with entry/exit details
- **Performance Charts**: Visual analysis of strategy performance (in debug mode)
- **Log Files**: Detailed execution logs

## License

[Add your license information here]

## Contributing

[Add contributing guidelines here]