From 470e243526eac5d2797cb3ea9a5d939d90ebdaf9 Mon Sep 17 00:00:00 2001 From: Jarno Date: Sat, 25 Jul 2026 21:20:07 +0300 Subject: [PATCH] Initial commit. --- .mise.toml | 2 ++ AGENTS.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 35 +++++++++++++++++++++ docs/README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 191 insertions(+) create mode 100644 .mise.toml create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 docs/README.md diff --git a/.mise.toml b/.mise.toml new file mode 100644 index 0000000..2bc04e1 --- /dev/null +++ b/.mise.toml @@ -0,0 +1,2 @@ +[tools] +python = "3.11.15" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c2f7b15 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..58dd6db --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# Trading Bot + +Python trading bot project using machine learning to decide which assets should be held. The bot is intended to trade through the IBKR API, beginning with paper trading and potentially supporting real trades later behind explicit safeguards. + +## Project Status + +This repository is at the planning and scaffolding stage. The machine learning model, trading parameters, asset universe, and risk rules will be designed later. + +## Main Parts + +1. Training data collection +2. Model generation and training +3. Trading bot using the trained model +4. Optional read-only web UI for trading status + +## Environment + +Use `mise` to manage Python. + +```sh +mise install +mise exec -- python --version +``` + +The current local Python version is pinned in `.mise.toml`. + +## Trading Safety + +The default target is 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 IBKR credentials, account identifiers, API tokens, or private configuration. + +## Documentation + +See [docs/README.md](docs/README.md) for the initial architecture notes and decision log. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..904eefc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,82 @@ +# Project Notes + +## Objective + +Build a Python-based trading bot that uses machine learning to determine which assets should be held, then uses the IBKR API to facilitate trades. The first supported trading mode should be paper trading. + +## Planned Modules + +### Training Data Collection + +Responsible for acquiring and storing market, asset, and any future feature data needed for model training and evaluation. + +Open decisions: + +- asset universe; +- data vendors and data licensing; +- historical time range; +- data storage format; +- feature update cadence; +- handling missing data, delistings, corporate actions, and survivorship bias. + +### Model Generation And Training + +Responsible for building datasets, training models, evaluating candidates, and writing versioned model artifacts. + +Open decisions: + +- prediction target; +- feature set; +- model family; +- validation strategy; +- evaluation metrics; +- retraining schedule; +- model artifact format; +- reproducibility requirements. + +### Trading Bot + +Responsible for loading a model, generating portfolio signals, deciding target holdings, and using the IBKR API to place or simulate orders. + +Initial expectations: + +- paper trading first; +- real trading later only behind explicit configuration; +- clear logging of model version, signals, target holdings, generated orders, and broker responses; +- separation between signal generation, portfolio construction, and broker execution. + +Open decisions: + +- rebalance cadence; +- position sizing; +- risk limits; +- cash handling; +- order types; +- failed order handling; +- market hours behavior; +- manual override behavior. + +### Read-Only Web UI + +Optional future module for checking status without controlling trading behavior. + +Possible scope: + +- current holdings; +- latest signals; +- recent orders; +- account summary; +- model version; +- bot health and logs. + +## Near-Term Priorities + +1. Decide the initial project package structure. +2. Add Python packaging and dependency management. +3. Add a minimal configuration system. +4. Define interfaces for data collection, model artifacts, and broker execution. +5. Add tests for the core trading decision boundaries before connecting real broker behavior. + +## Decisions Deferred + +The model, features, labels, asset selection rules, risk management rules, and trading cadence are intentionally deferred for later discussion.