╔══════════════════════════════════════════════════════════════════╗
║  PYTHON FOR ALGORITHMIC TRADING — Companion Package             ║
║  Waskey Press  |  www.waskeypress.com                           ║
╚══════════════════════════════════════════════════════════════════╝

WHAT'S IN THIS PACKAGE
────────────────────────
alpha/              The complete Alpha trading system, assembled
                    across all 16 chapters and both capstone projects.
                    This is the final, runnable source code.

chapters/           Per-chapter Python files — one file per chapter,
                    containing all code listings from that chapter in order.
                    Use these to follow along without retyping every snippet.

capstone_starters/  Starter scaffolding for both capstone projects:
  capstone1_momentum/   Guided momentum rotation system
  capstone2_pairs/      Self-directed pairs trading challenge

requirements.txt    All required packages (install once with pip)
.env.example        Template for your Alpaca API credentials


SETUP (do this once)
─────────────────────
1. Make sure Python 3.11+ is installed: python --version

2. Create a virtual environment:
     python -m venv venv
     source venv/bin/activate        # Mac/Linux
     venv\Scripts\activate           # Windows

3. Install packages:
     pip install -r requirements.txt

4. For Part 4 (broker connectivity):
   - Open a free paper trading account at alpaca.markets
   - Copy .env.example to .env
   - Add your API key and secret key to .env
   - NEVER commit .env to Git


HOW TO USE THE CHAPTER FILES
──────────────────────────────
Open chapters/ch03_Market_Data_Sourcing_Cleaning_and_Storing.py
alongside Chapter 3 of the book. The code is in the same order as
the listings in the book. Run sections in your editor as you read.

Use the alpha/ folder to see how each piece fits into the final system.


HOW TO USE THE CAPSTONE STARTERS
──────────────────────────────────
capstone1 is guided — the starter file has detailed TODO comments
walking you through each step. Attempt it before looking at the solution.

capstone2 is self-directed — less scaffolding is provided intentionally.
The reference solution is in alpha/capstone/pairs_strategy.py.


ALPHA PROJECT STRUCTURE
────────────────────────
alpha/
  data/
    fetch.py                  Ch 3  — yfinance data fetching
    store.py                  Ch 3  — caching and storage
    timeseries_utils.py       Ch 4  — pandas time series tools
  strategies/
    indicators.py             Ch 5  — SMA, EMA, RSI, MACD, Bollinger
    base.py                   Ch 6  — Strategy base class
    moving_average_crossover.py Ch 7 — First complete strategy
  risk/
    position_sizing.py        Ch 8  — Kelly, fixed-fraction, volatility sizing
    portfolio.py              Ch 9  — Correlation and diversification
    manager.py                Ch 9  — Risk veto and portfolio limits
  backtesting/
    trade.py                  Ch 10 — Trade object
    engine.py                 Ch 10 — Backtesting engine
    test_log.py               Ch 11 — Lookahead bias detection
    performance.py            Ch 12 — Sharpe, drawdown, Calmar, etc.
    walk_forward.py           Ch 13 — Walk-forward validation
  execution/
    broker.py                 Ch 14 — Broker interface (abstract)
    alpaca_broker.py          Ch 14 — Alpaca implementation
    circuit_breaker.py        Ch 15 — Order-level safety checks
    resilient_execution.py    Ch 16 — Retry, timeout, failsafe execution
  monitoring/
    logger.py                 Ch 16 — Structured runtime logging
    failsafes.py              Ch 16 — System-level halt conditions
  capstone/
    momentum_universe.py      Capstone 1 — Universe definition
    momentum_signals.py       Capstone 1 — Momentum scoring
    momentum_strategy.py      Capstone 1 — Complete system
    pairs_cointegration.py    Capstone 2 — Cointegration testing
    pairs_signal.py           Capstone 2 — Spread and z-score
    pairs_strategy.py         Capstone 2 — Complete system
  main.py                     Ch 16 — Entry point for live/paper trading


QUICK START — RUN A BACKTEST
──────────────────────────────
cd alpha/
python -c "
from data.store import get_price_history
from strategies.moving_average_crossover import MovingAverageCrossover
from backtesting.engine import BacktestEngine
from backtesting.performance import PerformanceReport

prices = get_price_history('SPY', period='5y')
strategy = MovingAverageCrossover(fast=50, slow=200)
engine = BacktestEngine(strategy, prices, initial_capital=100_000)
results = engine.run()
PerformanceReport(results).print()
"


CONTACT
────────
www.waskeypress.com  |  contact@waskeypress.com
