# 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.