trading-bot/docs/README.md

Project Notes

Objective

Build a Python-based trading bot that uses machine learning to determine which assets should be held, then uses Alpaca Markets for market data and broker execution. The first supported trading mode is paper trading.

Planned Modules

Training Data Collection

Responsible for acquiring and storing market, asset, and any future feature data needed for model training and evaluation.

The current data tool is an Alpaca daily candle fetcher. It fetches open, high, low, close, and volume data for a ticker and date range, then persists that data to a ticker-named Parquet file. See data-fetcher.md.

The initial supervised training dataset is documented in training-dataset.md. It derives market-regime features from SPY, a volatility proxy, TLT, and USO, then labels whether SPY closes higher five trading days later. The checked-in configuration currently maps the volatility input to VIXY for Alpaca data availability.

Parquet files are partitioned by ticker, not by date.

Open decisions:

• asset universe;
• data vendors and data licensing;
• historical time range;
• data storage format;
• feature update cadence;
• handling missing data, delistings, corporate actions, and survivorship bias.

Model Generation And Training

Responsible for building datasets, training models, evaluating candidates, and writing versioned model artifacts.

The main entry point is src/trading_bot/data/train_pipeline.py. It reads raw Alpaca Parquet files from data/alpaca/daily, builds data/training/spy_direction_5d.parquet, trains an XGBoost classifier, and writes model artifacts to models/.

Open decisions:

• prediction target;
• model family;
• validation strategy;
• evaluation metrics;
• retraining schedule;
• model artifact format;
• reproducibility requirements.

Trading Bot

Responsible for loading a model, generating portfolio signals, deciding target holdings, and using the Alpaca trading API to place paper-trading orders.

The main entry point is src/trading_bot/models/trade.py. It loads a model and metadata, optionally refreshes recent Alpaca market data, estimates a target SPY exposure from the model probability, cancels open Alpaca orders, and submits a day market order when the desired rebalance exceeds the configured minimum notional amount. Pass --model-path models/spy_xgb_v1.json --metadata-path models/spy_xgb_v1_meta.json to trade with artifacts produced by the current training pipeline.

Initial expectations:

• Alpaca paper trading first;
• real trading later only behind explicit configuration;
• clear logging of model version, signals, target holdings, generated orders, and broker responses;
• separation between signal generation, portfolio construction, and broker execution.

Open decisions:

• rebalance cadence;
• position sizing;
• risk limits;
• cash handling;
• order types and time-in-force choices;
• failed order handling;
• market hours behavior;
• manual override behavior.

Read-Only Web UI

Optional future module for checking status without controlling trading behavior.

Possible scope:

• current holdings;
• latest signals;
• recent orders;
• account summary;
• model version;
• bot health and logs.

Near-Term Priorities

1. Decide the initial project package structure.
2. Keep Python packaging and dependency management current with uv.
3. Add a minimal configuration system.
4. Harden interfaces for data collection, model artifacts, and Alpaca broker execution.
5. Expand tests around trading decision boundaries, portfolio sizing, stale data handling, and broker API boundaries.

Decisions Deferred

Broader model design, asset selection rules, risk management rules, live-trading gates, and trading cadence are intentionally deferred for later discussion.