Initial commit.

2026-07-25 21:20:07 +03:00
commit 470e243526
4 changed files with 191 additions and 0 deletions
@@ -0,0 +1,72 @@
+# 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.
+- The local Python version is pinned in `.mise.toml`.
+- Prefer commands run through `mise exec -- ...` when the Python environment matters.
+- 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.