Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.novosky.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Before you change anything

  1. Read AGENTS.md — it is the canonical shared context for all contributors
  2. Check docs/ for the relevant page before relying on memory
  3. Read the affected source files before changing behavior
  4. Make the smallest change that solves the request

​
Development workflow

1

Validate the current state

python backtest.py --balance 500 --no-swap --leverage 500 --spread 14.59 --oos-only --no-chart
Record the baseline score before making changes.
2

Make your change

For ML changes: follow the three-file rule — feature_engineering.py, ml_config.json, and retrain all 4 models.For execution changes: update both trading/bot.py and backtest/run.py.For config changes only: use scripts/sweep.py without retraining.
3

Retrain if needed

python scripts/retrain.py
Always use this strict order.
4

Validate OOS

python backtest.py --balance 500 --no-swap --leverage 500 --spread 14.59 --oos-only --no-chart
The new score should beat the baseline. If it doesn’t, investigate before proceeding.
5

Dry-run the bot

python trading.py --dry
Watch a few cycles to verify no errors.
6

Push models

python ml/hf_hub.py --push
Only push if the OOS score improved.

​
Invariants

These rules must never be violated:
  • Never reorder, add, or remove ML features without updating ml_config.json and retraining all 4 models
  • Never change execution logic in trading/bot.py without mirroring the change in backtest/run.py
  • Training order is strict: Signal → Position → SLTP → Risk
  • Never diverge RISK_FEATURES across ml/risk_trainer.py, ml/risk_predictor.py, and ml_config.json
  • Never drop protected features (is_news_near, news_minutes_away, news_count_today, is_news_risk_window, is_london_session, is_ny_session, is_asian_session) based on SHAP alone
  • Never run live trading before a dry-run
  • Never train on Azure ML — training is local-only, GPU first, CPU fallback

​
What to check before committing

  • python backtest.py --oos-only --no-chart passes with equal or better score
  • python trading.py --dry runs without errors for 3+ cycles
  • ml_config.json and models/model_compat.json are in sync if features changed
  • trading/bot.py and backtest/run.py are in parity if execution logic changed
  • RISK_FEATURES is consistent across all three risk files if risk features changed
  • New models pushed to HF Hub: python ml/hf_hub.py --push

​
Roadmap and open work

Active priorities (as of April 2026):
  • Multi-account support — --account flag to run multiple profiles simultaneously
  • Multi-instrument — XAUUSD, EURUSD alongside BTCUSD
  • Multi-datasource OHLCV — secondary data source fallback
  • Broker-agnostic refactor — full config/brokers.json registry coverage
To contribute to any of these, start a discussion or open a PR against main. Include an OOS backtest result showing the change is neutral or positive before requesting a merge.