75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
1. Training data collection.
|
|
2. Model generation and training.
|
|
3. The live trading bot that uses the trained model.
|
|
4. 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:
|
|
|
|
```text
|
|
src/trading_bot/
|
|
data/
|
|
models/
|
|
trading/
|
|
ui/
|
|
tests/
|
|
docs/
|
|
```
|
|
|
|
Update this file as major architecture decisions become settled.
|