ParallelLLC/algorithmic_trading

1---2license: apache-2.03language:4  - en5library_name: pytorch6pretty_name: Algorithmic Trading7tags:8  - finance9  - algorithmic-trading10  - quantitative-finance11  - backtesting12  - reinforcement-learning13  - pytorch14  - yfinance15---16 17---18license: apache-2.019language:20  - en21library_name: pytorch22pretty_name: Algorithmic Trading23tags:24  - finance25  - algorithmic-trading26  - quantitative-finance27  - backtesting28  - reinforcement-learning29  - pytorch30  - yfinance31---32 33# Algorithmic Trading34 35Parallel LLC. Two layers in one repository:36 371. **algotrader 2.0** (`algotrader/`, `app.py`): a backtester that tries to prove a rule was luck (permutation, deflated Sharpe, PBO, walk-forward, cost stress).382. **Agentic v1** (`agentic_ai_system/`): FinRL policies, Yahoo or Alpaca ingest, paper/live execution, Streamlit/Dash/Jupyter UIs, Docker.39 40Default market data is **Yahoo Finance** (`yfinance>=1.0`), not simulated prices. The simulator exists for offline tests (`--source synthetic` or `ALGOTRADER_OFFLINE=1` with `source=auto`). Live capital still needs a separate evaluation contract. This is research tooling, not investment advice.41 42---43 44## 1. Title and Summary45 46**Algorithmic Trading**  47Ingest real OHLCV, test whether a timing or cross-sectional rule survives a hostile null, optionally train a FinRL policy, size orders under position and drawdown caps, route to paper or live Alpaca.48 49GitHub keeps two branches: `main` (protected) and `dev` (integration).50 51**Design themes**52 53* Yahoo as the default public tape (delayed, unofficial, lookback-limited)54* Validation before belief: permutation, DSR, PBO/CSCV, walk-forward, 3× cost stress55* FinRL (PPO, A2C, DDPG, TD3) unchanged on the v1 path56* Alpaca optional for authenticated bars and orders; keys from the environment57* Synthetic GBM / regime simulator only when requested58* Secrets never in git59 60---61 62## 2. Quick start63 64```bash65git clone https://github.com/ParallelLLC/algorithmic_trading.git66cd algorithmic_trading67python -m venv .venv && source .venv/bin/activate68pip install -r requirements-space.txt   # algotrader + Gradio69# or: pip install -r requirements.txt   # full v1 stack (FinRL, Dash, Docker CI)70```71 72```bash73python app.py                                      # Gradio, localhost:7860, Yahoo by default74python -m algotrader.cli lab --symbol SPY --strategy sma_cross75python -m algotrader.cli lab --symbol NVDA --strategy rsi_reversion --permutations 50076python -m agentic_ai_system.main --mode backtest --start-date 2024-01-01 --end-date 2024-12-3177```78 79`config.yaml` defaults:80 81```yaml82data_source:83  type: 'yahoo'84trading:85  symbol: 'AAPL'86  timeframe: '1d'    # Yahoo 1m history is ~7 days; use 1d for multi-year windows87yahoo:88  auto_adjust: true  # raw Close turns splits into fake crashes89```90 91Alpaca is opt-in: `ALPACA_API_KEY` / `ALPACA_SECRET_KEY` and `data_source.type: alpaca` or `execution.broker_api: alpaca_paper`.92 93---94 95## 3. algotrader 2.0 (validation lab)96 97Most backtests answer "how much would this have made?" This one asks **how much of that was luck?**98 99### Two labs100 101**The Lab** validates a timing rule on one asset. **The Portfolio Lab** validates a cross-sectional book that ranks many names.102 103### The four ways a backtest lies104 105| The lie | The test | Where |106| --- | --- | --- |107| The market had no structure to find | Monte-Carlo permutation (shuffle bar order, keep gap/high/low/body/volume) | `algotrader/validation/permutation.py` |108| You tried 200 things and reported the best | Deflated Sharpe Ratio | `algotrader/validation/deflated_sharpe.py` |109| Parameters were fitted to the past | PBO (CSCV) and walk-forward | `algotrader/validation/pbo.py`, `walkforward.py` |110| The edge is smaller than the costs | Cost stress at 3× friction | `algotrader/lab.py` |111 112Reality Score (0–100, grades A–F): significance 30%, selection 25%, walk-forward 20%, overfitting 15%, robustness 10%. The scale is harsh on purpose. Buy-and-hold and a coin-flip stay in the arena as controls.113 114Cross-sectional books use a **within-date weight permutation** so market correlation survives; path-shuffle is the wrong null for a long-short ranker. Survivorship is measured. Style regression (market, momentum, low-vol, reversal, liquidity) with White standard errors.115 116Look-ahead: `position[t] = target[t - lag]` with `lag >= 1`. Turnover is measured against drifted weights, not `|target[t]-target[t-1]|`.117 118```python119from algotrader import LabConfig, run_lab120 121report = run_lab(LabConfig(122    symbol="SPY",123    start="2015-01-01",124    strategy="sma_cross",125    params={"fast": 20, "slow": 100},126    source="yahoo",127    n_permutations=500,128))129print(report.verdict["grade"], report.permutation.p_value, report.dsr["dsr"])130```131 132```bash133python -m algotrader.cli strategies134python -m algotrader.cli lab --symbol SPY --source yahoo135python -m algotrader.cli portfolio --symbols SPY,QQQ,AAPL,MSFT,NVDA --strategy xs_momentum136python -m algotrader.cli lab --source synthetic   # offline tests only137```138 139Single-asset zoo: `buy_and_hold`, `sma_cross`, `ema_cross`, `macd_trend`, `rsi_reversion`, `bollinger_reversion`, `donchian_breakout`, `momentum`, `vol_target_momentum`, `channel_trend`, `coin_flip`.140 141Cross-sectional: `equal_weight`, `xs_momentum`, `xs_reversal`, `low_volatility`, `xs_value_proxy`, `xs_random`.142 143**Data:** `load_ohlcv(..., source="yahoo")` downloads from Yahoo and **raises** if the download is empty. `source="auto"` is the Space fallback (cache, then simulator). `ALGOTRADER_OFFLINE=1` disables the network.144 145**HF Space:** `HF_TOKEN=hf_xxx ./scripts/deploy_hf_space.sh <user>/backtest-reality-check`. Card is `SPACE_README.md`. Tests: `python -m pytest tests/test_v2_*.py -q`.146 147References: Bailey & López de Prado (2014) DSR; Bailey et al. (2016) PBO; Masters (2018) permutation tests for trading systems.148 149---150 151## 4. Concepts and methods (v1 ingest and execution)152 153| Source | Default? | Failure modes |154| ------ | -------- | ------------- |155| **Yahoo** | Yes (`config.yaml`, algotrader CLI, Gradio) | Unofficial API, ~15 min delay, 1m ≈ 7 days, split-adjustment required (`auto_adjust: true`) |156| **Alpaca** | Optional | Auth, feed, rate limits |157| **CSV** | Replay | Missing path or OHLCV columns |158| **Synthetic** | Tests / `--source synthetic` | Not tradable edge |159 160`agentic_ai_system.data_ingestion.load_data` dispatches on `data_source.type`. Yahoo stream: `yahoo_data_stream.py` (clamped lookback, no incomplete bars by default).161 162* `StrategyAgent`: SMA, RSI, Bollinger, MACD on Close (teaching rule, not an alpha claim)163* `FinRLAgent`: PPO / A2C / DDPG / TD3 via Stable-Baselines3164* `ExecutionAgent` / `AlpacaBroker`: paper simulation or Alpaca orders165 166v1 `run_backtest` is a single in-sample pass unless you use algotrader walk-forward. Leakage is the null hypothesis.167 168---169 170## 5. Stack171 172| Layer | Tools |173| ----- | ----- |174| Language | Python 3.11 (CI) |175| Validation | algotrader (permutation, DSR, PBO, walk-forward) |176| RL | FinRL / Stable-Baselines3, Gym/Gymnasium, PyTorch |177| Market data | yfinance ≥ 1.0 (default); alpaca-py optional |178| Tabular | pandas, NumPy, scikit-learn |179| UI | Gradio (`app.py`); Streamlit, Dash, Jupyter (v1) |180| Deploy | Docker Compose, GitHub Actions, Hugging Face Space |181| Tests | pytest |182 183---184 185## 6. Structure186 187```188algorithmic_trading/189├── algotrader/                 # 2.0 lab, engine, validation, strategies190├── app.py                      # Gradio Reality Check191├── agentic_ai_system/          # v1 FinRL, Yahoo/Alpaca ingest, execution192├── ui/                         # Streamlit, Dash, Jupyter, WebSocket193├── tests/194├── docs/AGENTIC_SYSTEM_V1.md   # v1 notes195├── config.yaml                 # default data_source.type: yahoo196├── requirements-space.txt      # Space / algotrader197├── requirements.txt            # full v1 + CI198└── scripts/deploy_hf_space.sh199```200 201---202 203## 7. Configuration204 205| Key | Meaning |206| --- | ------- |207| `data_source.type` | `yahoo` (default) \| `csv` \| `synthetic` \| `alpaca` |208| `trading.timeframe` | Mapped to Yahoo intervals; use `1d` for multi-year history |209| `yahoo.auto_adjust` | Split/dividend adjust (keep true) |210| `yahoo.emit_incomplete_bars` | Default false; forming bars are not closes |211| `execution.broker_api` | `paper` \| `alpaca_paper` \| `alpaca_live` |212| `finrl.algorithm` | PPO, A2C, DDPG, TD3 |213| algotrader `--source` | `yahoo` (default) \| `auto` \| `cache` \| `synthetic` |214 215---216 217## 8. Tests and ops218 219```bash220python -m pytest tests/test_v2_*.py -q221python -m pytest tests/test_yahoo_data_stream.py tests/test_data_ingestion.py -q222```223 224UI launchers and Docker: `UI_SETUP.md`, `DOCKER_HUB_SETUP.md`. Branch policy: `main` and `dev` only. Do not re-enable Dependabot.225 226---227 228**License:** Apache License 2.0  229**Organization:** [Parallel LLC](https://github.com/ParallelLLC)  230**Repository:** <https://github.com/ParallelLLC/algorithmic_trading>231