92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# 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](data-fetcher.md).
|
|
|
|
The initial supervised training dataset is documented in [training-dataset.md](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.
|