Python trading bot project using machine learning to decide which assets should be held. The bot currently uses the Alpaca Markets API for market data and paper trading, with any future live trading kept behind explicit safeguards.

Project Status

This repository now has a working prototype flow for Alpaca market data, dataset generation, XGBoost training, prediction, and paper-trading rebalancing. The strategy is still intentionally narrow: it currently focuses on SPY exposure using a small market-regime feature set.

Main Parts

Training data collection
Model generation and training
Trading bot using the trained model
Optional read-only web UI for trading status

Environment

Use mise to manage Python and uv to manage Python packages.

mise install
mise exec -- uv sync
mise exec -- uv run python --version

The current local Python version is pinned in .mise.toml.

Dependencies

Runtime dependencies are declared in pyproject.toml.

alpaca-py for Alpaca market data and trading clients.
pandas for tabular candle data handling.
pyarrow for Parquet file support.
xgboost and scikit-learn for model training and evaluation.
python-dotenv for loading local Alpaca credentials from .env.

Trading Safety

The default target is Alpaca paper trading. Real trading should only be added later with explicit configuration, clear documentation, and tests around order generation and broker integration.

Do not commit secrets such as Alpaca API keys, account identifiers, API tokens, or private configuration.

Current Commands

Fetch Alpaca daily candles:

mise exec -- uv run python src/trading_bot/data/fetch_alpaca_daily.py SPY

Build the training dataset and train the current model:

mise exec -- uv run python src/trading_bot/data/train_pipeline.py

Run the current Alpaca paper-trading rebalance flow:

mise exec -- uv run python src/trading_bot/models/trade.py \
  --paper \
  --fetch-recent-data \
  --model-path models/spy_xgb_v1.json \
  --metadata-path models/spy_xgb_v1_meta.json

The main Python entry points are:

src/trading_bot/data/train_pipeline.py for dataset generation and model training.
src/trading_bot/models/trade.py for Alpaca account inspection and SPY rebalancing.
src/trading_bot/ui/dashboard.py for the read-only performance dashboard.

Serve the read-only dashboard:

mise exec -- uv run python -m trading_bot.ui.dashboard --paper

Documentation

See docs/README.md for the initial architecture notes and decision log.

The current data collection note is docs/data-fetcher.md, and the training dataset contract is docs/training-dataset.md.

The read-only dashboard design is documented in docs/read-only-ui.md.

The first dataset generation notebook is notebooks/spy_direction_dataset.ipynb.

Manual test instructions for the Alpaca fetcher are in docs/manual-test/README.md.