--- license: apache-2.0 language: - en library_name: pytorch pretty_name: Algorithmic Trading tags: - finance - algorithmic-trading - quantitative-finance - backtesting - reinforcement-learning - pytorch - yfinance --- --- license: apache-2.0 language: - en library_name: pytorch pretty_name: Algorithmic Trading tags: - finance - algorithmic-trading - quantitative-finance - backtesting - reinforcement-learning - pytorch - yfinance --- # Algorithmic Trading Parallel LLC. Two layers in one repository: 1. **algotrader 2.0** (`algotrader/`, `app.py`): a backtester that tries to prove a rule was luck (permutation, deflated Sharpe, PBO, walk-forward, cost stress). 2. **Agentic v1** (`agentic_ai_system/`): FinRL policies, Yahoo or Alpaca ingest, paper/live execution, Streamlit/Dash/Jupyter UIs, Docker. Default 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. --- ## 1. Title and Summary **Algorithmic Trading** Ingest 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. GitHub keeps two branches: `main` (protected) and `dev` (integration). **Design themes** * Yahoo as the default public tape (delayed, unofficial, lookback-limited) * Validation before belief: permutation, DSR, PBO/CSCV, walk-forward, 3× cost stress * FinRL (PPO, A2C, DDPG, TD3) unchanged on the v1 path * Alpaca optional for authenticated bars and orders; keys from the environment * Synthetic GBM / regime simulator only when requested * Secrets never in git --- ## 2. Quick start ```bash git clone https://github.com/ParallelLLC/algorithmic_trading.git cd algorithmic_trading python -m venv .venv && source .venv/bin/activate pip install -r requirements-space.txt # algotrader + Gradio # or: pip install -r requirements.txt # full v1 stack (FinRL, Dash, Docker CI) ``` ```bash python app.py # Gradio, localhost:7860, Yahoo by default python -m algotrader.cli lab --symbol SPY --strategy sma_cross python -m algotrader.cli lab --symbol NVDA --strategy rsi_reversion --permutations 500 python -m agentic_ai_system.main --mode backtest --start-date 2024-01-01 --end-date 2024-12-31 ``` `config.yaml` defaults: ```yaml data_source: type: 'yahoo' trading: symbol: 'AAPL' timeframe: '1d' # Yahoo 1m history is ~7 days; use 1d for multi-year windows yahoo: auto_adjust: true # raw Close turns splits into fake crashes ``` Alpaca is opt-in: `ALPACA_API_KEY` / `ALPACA_SECRET_KEY` and `data_source.type: alpaca` or `execution.broker_api: alpaca_paper`. --- ## 3. algotrader 2.0 (validation lab) Most backtests answer "how much would this have made?" This one asks **how much of that was luck?** ### Two labs **The Lab** validates a timing rule on one asset. **The Portfolio Lab** validates a cross-sectional book that ranks many names. ### The four ways a backtest lies | The lie | The test | Where | | --- | --- | --- | | The market had no structure to find | Monte-Carlo permutation (shuffle bar order, keep gap/high/low/body/volume) | `algotrader/validation/permutation.py` | | You tried 200 things and reported the best | Deflated Sharpe Ratio | `algotrader/validation/deflated_sharpe.py` | | Parameters were fitted to the past | PBO (CSCV) and walk-forward | `algotrader/validation/pbo.py`, `walkforward.py` | | The edge is smaller than the costs | Cost stress at 3× friction | `algotrader/lab.py` | Reality 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. Cross-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. Look-ahead: `position[t] = target[t - lag]` with `lag >= 1`. Turnover is measured against drifted weights, not `|target[t]-target[t-1]|`. ```python from algotrader import LabConfig, run_lab report = run_lab(LabConfig( symbol="SPY", start="2015-01-01", strategy="sma_cross", params={"fast": 20, "slow": 100}, source="yahoo", n_permutations=500, )) print(report.verdict["grade"], report.permutation.p_value, report.dsr["dsr"]) ``` ```bash python -m algotrader.cli strategies python -m algotrader.cli lab --symbol SPY --source yahoo python -m algotrader.cli portfolio --symbols SPY,QQQ,AAPL,MSFT,NVDA --strategy xs_momentum python -m algotrader.cli lab --source synthetic # offline tests only ``` Single-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`. Cross-sectional: `equal_weight`, `xs_momentum`, `xs_reversal`, `low_volatility`, `xs_value_proxy`, `xs_random`. **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. **HF Space:** `HF_TOKEN=hf_xxx ./scripts/deploy_hf_space.sh /backtest-reality-check`. Card is `SPACE_README.md`. Tests: `python -m pytest tests/test_v2_*.py -q`. References: Bailey & López de Prado (2014) DSR; Bailey et al. (2016) PBO; Masters (2018) permutation tests for trading systems. --- ## 4. Concepts and methods (v1 ingest and execution) | Source | Default? | Failure modes | | ------ | -------- | ------------- | | **Yahoo** | Yes (`config.yaml`, algotrader CLI, Gradio) | Unofficial API, ~15 min delay, 1m ≈ 7 days, split-adjustment required (`auto_adjust: true`) | | **Alpaca** | Optional | Auth, feed, rate limits | | **CSV** | Replay | Missing path or OHLCV columns | | **Synthetic** | Tests / `--source synthetic` | Not tradable edge | `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). * `StrategyAgent`: SMA, RSI, Bollinger, MACD on Close (teaching rule, not an alpha claim) * `FinRLAgent`: PPO / A2C / DDPG / TD3 via Stable-Baselines3 * `ExecutionAgent` / `AlpacaBroker`: paper simulation or Alpaca orders v1 `run_backtest` is a single in-sample pass unless you use algotrader walk-forward. Leakage is the null hypothesis. --- ## 5. Stack | Layer | Tools | | ----- | ----- | | Language | Python 3.11 (CI) | | Validation | algotrader (permutation, DSR, PBO, walk-forward) | | RL | FinRL / Stable-Baselines3, Gym/Gymnasium, PyTorch | | Market data | yfinance ≥ 1.0 (default); alpaca-py optional | | Tabular | pandas, NumPy, scikit-learn | | UI | Gradio (`app.py`); Streamlit, Dash, Jupyter (v1) | | Deploy | Docker Compose, GitHub Actions, Hugging Face Space | | Tests | pytest | --- ## 6. Structure ``` algorithmic_trading/ ├── algotrader/ # 2.0 lab, engine, validation, strategies ├── app.py # Gradio Reality Check ├── agentic_ai_system/ # v1 FinRL, Yahoo/Alpaca ingest, execution ├── ui/ # Streamlit, Dash, Jupyter, WebSocket ├── tests/ ├── docs/AGENTIC_SYSTEM_V1.md # v1 notes ├── config.yaml # default data_source.type: yahoo ├── requirements-space.txt # Space / algotrader ├── requirements.txt # full v1 + CI └── scripts/deploy_hf_space.sh ``` --- ## 7. Configuration | Key | Meaning | | --- | ------- | | `data_source.type` | `yahoo` (default) \| `csv` \| `synthetic` \| `alpaca` | | `trading.timeframe` | Mapped to Yahoo intervals; use `1d` for multi-year history | | `yahoo.auto_adjust` | Split/dividend adjust (keep true) | | `yahoo.emit_incomplete_bars` | Default false; forming bars are not closes | | `execution.broker_api` | `paper` \| `alpaca_paper` \| `alpaca_live` | | `finrl.algorithm` | PPO, A2C, DDPG, TD3 | | algotrader `--source` | `yahoo` (default) \| `auto` \| `cache` \| `synthetic` | --- ## 8. Tests and ops ```bash python -m pytest tests/test_v2_*.py -q python -m pytest tests/test_yahoo_data_stream.py tests/test_data_ingestion.py -q ``` UI launchers and Docker: `UI_SETUP.md`, `DOCKER_HUB_SETUP.md`. Branch policy: `main` and `dev` only. Do not re-enable Dependabot. --- **License:** Apache License 2.0 **Organization:** [Parallel LLC](https://github.com/ParallelLLC) **Repository:**