Agent Instructions

Project Purpose

This repository is for a Python trading bot that uses machine learning to decide which assets should be held. The bot will use the IBKR API to facilitate trades, starting with paper trading and allowing a carefully controlled path to real trading later.

Current Direction

The project is expected to grow into four main parts:

Training data collection.
Model generation and training.
The live trading bot that uses the trained model.
An optional read-only web UI for checking trading status.

Keep these areas loosely separated in code and documentation. Avoid coupling the live trading path to the training workflow unless there is a clear interface between them.

Development Environment

Use Python for implementation.
Use mise to control the Python version.
Use uv to manage Python packages and virtual environments.
The local Python version is pinned in .mise.toml.
Prefer commands run through mise exec -- ... when the Python environment matters.
Prefer mise exec -- uv run ... for project Python commands once dependencies are synced.
Git is the version control system for this project. A remote will be added later.

Safety And Trading Constraints

Default all trading behavior to paper trading.
Treat real-money trading as an explicit future capability, not an assumed behavior.
Do not add live trading behavior without clear configuration gates and documentation.
Keep credentials, account IDs, API keys, tokens, and broker connection details out of source control.
Make trade decisions explainable enough to audit after the fact. Log inputs, model version, generated signals, orders requested, and broker responses where practical.

Machine Learning Scope

The exact model design, features, labels, training windows, evaluation metrics, rebalancing cadence, asset universe, and risk controls are not decided yet. Do not hard-code those assumptions prematurely.

When adding ML-related code, prefer interfaces that make these choices configurable or easy to replace later:

data sources and symbols;
feature generation;
labeling strategy;
train, validation, and test split strategy;
model family;
portfolio construction rules;
backtesting and evaluation metrics;
model artifact format and versioning.

Code Style Guidance

Keep modules small and focused around the four project areas.
Prefer typed Python where it improves clarity.
Favor explicit configuration files over hidden constants.
Add tests around trading decisions, portfolio sizing, and broker API boundaries before increasing automation.
Use deterministic fixtures for tests where possible.
Avoid network calls in unit tests unless they are explicitly marked as integration tests.

Suggested Early Layout

This is a starting point, not a fixed requirement:

src/trading_bot/
  data/
  models/
  trading/
  ui/
tests/
docs/

Update this file as major architecture decisions become settled.

2.9 KiB Raw Blame History