Rewrite README to be concise and project-oriented

Author: nctzen0

README.md

@@ -1,122 +1,39 @@
-# TradingBot: Professional Quantitative Trading Framework
+# TradingBot
 
-A comprehensive Python framework for backtesting intraday trading strategies using real market data. Built with institutional-grade architecture and sophisticated market microstructure modeling, this project demonstrates advanced quantitative finance concepts through clean, production-ready code.
+A simple, practical Python framework for backtesting intraday trading strategies on real or synthetic data. It includes a small set of strategies, a realistic backtester (bid/ask, latency, fees), and basic analytics.
 
-## 🎯 What We Built
+## Features
+- **Data**: Yahoo Finance intraday download (no API key), CSV input, or synthetic data
+- **Strategies**: Mean reversion, momentum, market making (extensible via `BaseStrategy`)
+- **Backtester**: Bid/ask matching, latency, slippage, transaction fees, average-cost P&L
+- **Metrics & Plots**: Sharpe, drawdown, win rate, equity curve and drawdown charts
+- **CLI**: Single entry point with sensible defaults
 
-This isn't just another trading bot—it's a complete quantitative research platform that bridges the gap between academic finance theory and practical implementation. We've created a system that:
-
-- **Fetches real market data** automatically from Yahoo Finance (no API keys needed)
-- **Models realistic market microstructure** with proper bid-ask spread dynamics
-- **Implements proven trading strategies** with rigorous backtesting methodology  
-- **Provides institutional-quality metrics** including risk-adjusted performance measures
-- **Demonstrates professional software architecture** suitable for quantitative finance teams
-
-## 🧮 Core Financial Concepts Implemented
-
-### Market Microstructure Modeling
-Real markets don't just have prices—they have **bid-ask spreads** that reflect liquidity costs and information asymmetry. We model this by:
-
-```python
-# Realistic spread calculation based on volatility and volume
-volatility_component = returns.std() * 10000  # Vol drives spreads
-volume_component = np.where(volume < volume_ma, 3, 1)  # Low volume = wider spreads
-spread_bps = base_spread + volatility_component + volume_component
-```
-
-This captures the fundamental relationship where spreads widen during:
-- High volatility periods (uncertainty increases trading costs)
-- Low volume periods (reduced market depth)
-- Market stress events (flight to liquidity)
-
-### Order Matching Engine
-Our backtester simulates realistic order execution by modeling:
-
-- **Latency effects**: Orders don't execute instantly in real markets
-- **Slippage**: Price impact from crossing the spread
-- **Transaction costs**: Realistic fee structures
-- **Average cost accounting**: Proper P&L attribution with FIFO/weighted average methods
-
-### Risk-Adjusted Performance Metrics
-We implement the full suite of professional performance measures:
-
-- **Sharpe Ratio**: `(Return - RiskFreeRate) / Volatility` - risk-adjusted returns
-- **Calmar Ratio**: `AnnualizedReturn / MaxDrawdown` - return per unit of downside risk  
-- **Maximum Drawdown**: Peak-to-trough decline measuring worst-case scenario
-- **Win Rate**: Percentage of profitable trades (important for strategy psychology)
-
-## 🏗️ System Architecture
-
-### Modular Data Pipeline
-```
-Data Sources → Normalization → Quality Assessment → Strategy Engine → Backtester → Analytics
-```
-
-**Real Market Data Integration**: We use Yahoo Finance's free API to download actual 1-minute intraday data, then apply sophisticated microstructure models to synthesize realistic bid-ask spreads. This gives us real price movements with realistic trading costs.
-
-**Data Quality Framework**: Every dataset gets comprehensive quality scoring:
-- Spread analysis (checking for crossed markets, unrealistic spreads)
-- Price dynamics validation (volatility clustering, return distributions)
-- Microstructure health (order size distributions, tick frequency)
-
-### Strategy Implementation
-Each strategy inherits from `BaseStrategy` and implements `on_tick()` for real-time decision making:
-
-**Mean Reversion**: 
-```python
-z_score = (current_price - rolling_mean) / rolling_std
-if z_score > threshold: sell_signal()
-if z_score < -threshold: buy_signal()
-```
-Captures the tendency for prices to revert to their statistical mean.
-
-**Momentum**: 
-```python
-price_velocity = (current_price - historical_price) / lookback_period
-if velocity > threshold: buy_signal()  # Price acceleration
-```
-Exploits the behavioral finance phenomenon of trend continuation.
-
-**Market Making**:
-```python
-place_bid(mid_price - half_spread)
-place_ask(mid_price + half_spread) 
-```
-Provides liquidity while capturing the bid-ask spread as profit.
-
-### Backtesting Engine
-Our simulation engine models realistic trading conditions:
-
-- **Order book dynamics**: Proper limit order matching against historical bid/ask
-- **Execution timing**: Configurable latency between order submission and fill
-- **Cost modeling**: Variable transaction fees and market impact
-- **Position tracking**: Real-time portfolio valuation with mark-to-market
-
-## 🚀 Getting Started
-
-### Installation
+## Installation
 ```bash
 git clone <your-repo-url>
 cd TradingBot
 pip install -r requirements.txt
 ```
 
-### Basic Usage - Real Market Data
-The system defaults to fetching real market data automatically:
-
+## Quick Start
 ```bash
-# Trade Apple stock with mean reversion strategy
+# Run with real market data from Yahoo Finance (e.g., AAPL)
 python main.py --symbol AAPL
 
-# Tesla momentum trading with custom parameters  
+# Choose a different strategy and parameters
 python main.py --symbol TSLA --strategy momentum --lookback 30 --threshold 0.002
 
-# Market making on SPY with position limits
+# Market making with position limits
 python main.py --symbol SPY --strategy market_making --max-position 200
 ```
 
-### Advanced Configuration
+### More Options
 ```bash
+# Show all CLI options
+python main.py -h
+
+# Advanced configuration example
 python main.py \
   --symbol NVDA \
   --strategy mean_reversion \
@@ -128,169 +45,23 @@ python main.py \
   --period 5d
 ```
 
-### Multi-Asset Demo
-```bash
-python demo.py  # Runs backtests across multiple symbols and strategies
-```
-
-## 📊 Real Data Example
-
-When you run the system, you'll see output like this:
-
-```
-🔄 Fetching real market data for AAPL...
-✅ Downloaded 1,946 bars of real market data for AAPL
-
-📊 MARKET DATA QUALITY ASSESSMENT
-============================================================
-📈 Dataset Overview:
-  • Total ticks: 1,946
-  • Time span: 6 days 06:29:00
-  • Tick frequency: 0.2/min
-
-💰 Price Dynamics:
-  • Mean price: $233.04
-  • Annualized volatility: 25.1%
-  • Return skew: -0.15 (slightly left-tailed)
-  • Return kurtosis: 4.2 (fat tails - typical for financial data)
-
-📏 Spread Analysis:
-  • Mean spread: 9.6 bps (realistic for large-cap stock)
-  • Median spread: 8.7 bps 
-  • Tight spreads (<5 bps): 1.5%
-  • Wide spreads (>20 bps): 2.2%
-
-🎯 Overall Quality Score: 100/100 ✅ Excellent
-
-📈 Performance Results:
-========================================
-Sharpe Ratio: 1.84 (good risk-adjusted returns)
-Max Drawdown: -12.3% (acceptable downside risk)
-Win Rate: 0.52 (slightly better than random)
-```
-
-## � What Makes This Professional
-
-### 1. Real Market Data Integration
-Instead of toy datasets, we use actual market data with realistic microstructure properties. This means spreads, volatility, and trading costs reflect real-world conditions.
-
-### 2. Sophisticated Risk Management
-- Position limits prevent excessive exposure
-- Transaction cost modeling includes both fixed fees and market impact
-- Realistic latency simulation prevents unrealistic alpha generation
-
-### 3. Proper Statistical Methods
-- Annualized Sharpe ratios with correct time-scaling
-- Drawdown analysis for tail risk assessment  
-- Return distribution analysis (skewness, kurtosis) for model validation
-
-### 4. Production-Ready Architecture
-- Modular design allows easy extension with new data sources
-- Comprehensive error handling and data validation
-- Professional logging and quality assessment
-- CLI interface suitable for automated trading research
-
-## 🧪 For Quantitative Researchers
-
-This framework demonstrates several advanced concepts:
-
-**Volatility Clustering**: Our real data exhibits the stylized fact that high volatility periods cluster together, which our strategies can exploit.
-
-**Bid-Ask Spread Dynamics**: We model spreads as functions of volatility and volume, capturing the inventory risk and adverse selection costs that market makers face.
-
-**Statistical Arbitrage**: The mean reversion strategy exploits temporary mispricings that occur due to market microstructure noise and temporary supply/demand imbalances.
-
-**Market Impact**: Our slippage modeling captures the reality that large orders move prices—a key consideration in institutional trading.
-
-## 🔧 Extending the Framework
-
-### Adding New Data Sources
-Implement the `DataSourceInterface`:
-
-```python
-class YourDataSource(DataSourceInterface):
-    def fetch_data(self, symbol, **kwargs):
-        # Your data fetching logic
-        return normalized_dataframe
-    
-    def validate_data(self, df):
-        # Your validation logic
-        return is_valid
-```
-
-### Creating Custom Strategies
-```python
-class YourStrategy(BaseStrategy):
-    def on_tick(self, market_data, current_position):
-        # Your trading logic
-        return list_of_orders
-```
-
-### Parameter Optimization
-```python
-from tuning import grid_search_strategy
-
-results = grid_search_strategy(
-    data, 'mean_reversion',
-    {'lookback': [30, 60, 120], 'threshold': [0.5, 1.0, 1.5]}
-)
-```
-
-## 📚 Mathematical Foundation
-
-The framework implements several key financial mathematics concepts:
-
-- **Geometric Brownian Motion**: Realistic price process modeling
-- **Ornstein-Uhlenbeck Process**: Mean-reverting dynamics in spread modeling
-- **Kelly Criterion**: Optimal position sizing (can be extended)
-- **Value at Risk**: Downside risk quantification through drawdown analysis
-- **Information Ratio**: Risk-adjusted alpha measurement
-
-## ⚠️ Important Notes
-
-This is a research and educational framework. While it uses real market data and implements professional-grade backtesting, it should not be used for live trading without extensive additional testing and risk management systems.
-
-The performance results shown are historical simulations and do not guarantee future performance. All trading involves risk of loss.
-
----
-
-**Built for quantitative researchers who demand both theoretical rigor and practical implementation quality.** 📈
-
-## CLI Options
-Run `python main.py -h` for all options. Key flags:
-- `--strategy {mean_reversion,momentum,market_making}`
-- `--lookback INT`, `--threshold FLOAT`, `--max-position INT`
-- `--latency-ms INT`, `--fee-per-share FLOAT`, `--slippage-bps FLOAT`
-- `--csv PATH` or `--synthetic`
-- `--no-plot`
-
-## Parameter Tuning
-See `tuning.py` for a simple grid search utility:
-```python
-from tuning import grid_search_strategy
-summary, best_metrics, best_results = grid_search_strategy(data, 'mean_reversion', {
-    'lookback': [30, 60, 120],
-    'threshold': [0.3, 0.5, 0.7],
-    'max_position': [50, 100]
-})
-print(summary.head())
-```
-
-## Architecture
+## Project Structure
 - `main.py` — CLI entry point
-- `data_loader.py` — I/O, CSV normalization, synthetic generator
-- `strategies/` — Strategy implementations inherit `BaseStrategy`
-- `backtester.py` — Matching on bid/ask, latency, fees, slippage, avg-cost P&L
-- `metrics.py` — Sharpe, drawdown, Calmar, win-rate
-- `plotting.py` — Equity, drawdown, exposure, P&L distribution, spread
-- `tests/` — Basic pytest to ensure runs complete
+- `data_loader.py` — Yahoo Finance download, CSV I/O, synthetic data
+- `backtester.py` — Core execution (bid/ask, latency, fees, slippage, P&L)
+- `strategies/` — `base.py`, `mean_reversion.py`, `momentum.py`, `market_making.py`
+- `metrics.py` — Sharpe, drawdown, win rate, etc.
+- `plotting.py` — Equity, drawdown, exposure, P&L distribution
+- `tests/` — Basic pytest for a synthetic run
+
+## Extending
+- Add a strategy by subclassing `strategies/base.py` and implementing `on_tick()`
+- Add a data source under `data_sources/` implementing the base interface
 
 ## Development
-- Lint/type-check as desired (ruff/mypy can be added)
-- Run tests:
 ```bash
 pytest -q
 ```
 
 ## Disclaimer
-This project is for educational and research purposes only; not investment advice or for live trading.
+This project is for educational and research purposes only. It is not investment advice and not intended for live trading.