README.md

---
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 <user>/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:** <https://github.com/ParallelLLC/algorithmic_trading>