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.

​
Entry points

These are the top-level entry points (not in scripts/):
ScriptPurpose
trading.pyStart the live trading bot
backtest.pyRun a backtest
scripts/retrain.pyTrain all 4 models (signal, position, SLTP, risk)
# trading.py
python trading.py           # live
python trading.py --dry     # dry run — no real orders

# backtest.py
python backtest.py --balance 500 --no-swap --leverage 500 --spread 14.59 --oos-only --no-chart

# scripts/retrain.py
python scripts/retrain.py                   # all 4 models
python scripts/retrain.py --shap --refresh  # with SHAP + fresh data
python scripts/retrain.py --trials 50       # Optuna tuning first

​
scripts/

​
onboarding.py

First-time setup wizard. Run once. 
python scripts/onboarding.py --balance 500
  • Prompts for .env credentials
  • Pulls latest models from HF Hub
  • Runs risk questionnaire (6 questions → profile 1–5)
  • Runs first weekly optimize

​
weekly_optimize.py

Autonomous 13-phase weekly pipeline. 
python scripts/weekly_optimize.py                           # full + questionnaire
python scripts/weekly_optimize.py --profile balanced        # skip questionnaire
python scripts/weekly_optimize.py --profile 3               # by profile number
python scripts/weekly_optimize.py --skip-retrain            # sweep only (~45 min)
python scripts/weekly_optimize.py --from-phase 5            # resume after crash
python scripts/weekly_optimize.py --dry-run                 # show plan, don't run
Profiles: steady_income (1), conservative (2), balanced (3), growth (4), aggressive (5).

​
retrain.py

Standalone retrain — always trains all 4 models together to prevent feature/risk mismatches. 
python scripts/retrain.py               # retrain all 4 models
python scripts/retrain.py --shap        # include SHAP analysis after training
python scripts/retrain.py --refresh     # fetch fresh OHLCV from MT5 API first
python scripts/retrain.py --trials 50   # run Optuna tuning before retraining

​
sweep.py

Unified config parameter sweep. Replaces the old sweep_signal.py and sweep_pos_model.py. 
# Signal parameter sweeps (--target signal)
python scripts/sweep.py --target signal --mode confidence
python scripts/sweep.py --target signal --mode sltp
python scripts/sweep.py --target signal --mode risk
python scripts/sweep.py --target signal --mode full        # all signal modes
python scripts/sweep.py --target signal --mode ml_sltp     # confidence_sl/tp_adjust
python scripts/sweep.py --target signal --mode kelly       # Kelly lot-sizing toggle
python scripts/sweep.py --target signal --mode custom --param confidence_threshold 0.55 0.60 0.65

# Position model sweep (--target pos)
python scripts/sweep.py --target pos
python scripts/sweep.py --target pos --full    # include partial_close + trailing sweeps

# Both sweeps sequentially (--target both)
python scripts/sweep.py --target both --no-chart
Broker params (spread, leverage) are loaded from the live MT5 API on each run; override with --spread / --leverage.

​
optimize_loop.py

Iterative optimization loop — runs SHAP → tune → retrain → OOS in a loop, committing only when score improves by ≥ 2%. 
python scripts/optimize_loop.py                     # 1 iteration
python scripts/optimize_loop.py --iterations 3      # 3 iterations
python scripts/optimize_loop.py --trials 50         # 50 Optuna trials per iteration
python scripts/optimize_loop.py --analyze-only      # SHAP + backtest, no retrain
python scripts/optimize_loop.py --retrain-only      # skip SHAP, just tune+retrain
Feature dropping (--drop-threshold) is disabled by default (0.0). Near-zero SHAP at train time does not mean a feature is useless — news and session features score near-zero during training but carry live signal at inference time. Do not enable dropping without careful review.
_PKL_FILES must include .onnx files alongside their .pkl counterparts. If ONNX files are omitted from the snapshot, rollback restores the pkl scaler but leaves a stale ONNX — the predictor then uses mismatched models silently.

​
config_sync.py

Shared config authority helpers (imported by other scripts — not a standalone CLI). Validates config.json and ml_config.json on startup and exposes sync_generated_configs(). 
from scripts.config_sync import sync_generated_configs, assert_generated_configs_in_sync

​
notify.py

Send a manual Telegram notification. 
python scripts/notify.py "deploy complete — bot restarted"
python scripts/notify.py --level error "MT5 connection failed"

​
ml/hf_hub.py

Hugging Face Hub model management. 
python ml/hf_hub.py --pull                # download latest
python ml/hf_hub.py --push                # upload after retrain
python ml/hf_hub.py --push --tag phase-16 # push with version tag
python ml/hf_hub.py --list                # show available revisions

​
Go binary scripts

These scripts are used when building the compiled Go binary. They are not needed for the Python bot.

​
scripts/export_scalers.py

Exports fitted scikit-learn StandardScaler objects from .pkl to JSON for Go inference. 
python scripts/export_scalers.py
Outputs (in models/):
  • ensemble_scaler.json
  • position_scaler.json
  • risk_scaler.json
  • sltp_scaler.json
Run after every retrain before packing the Go binary.

​
scripts/export_onnx_regression.py

Converts LightGBM regression models (risk and SLTP) from their native .txt format to ONNX using onnxmltools. 
python scripts/export_onnx_regression.py
Outputs (in models/):
  • risk_lgb.onnx — 7 features
  • sltp_sl_lgb.onnx — market features + signal_direction
  • sltp_tp_lgb.onnx — same
Includes a smoke test with onnxruntime after each export.
Ensemble and position ONNX files are exported automatically by the Python trainer. Only risk and SLTP need this script.

​
scripts/pack_embedded.sh

Copies model files and configs into internal/embedded/ for Go’s //go:embed. Must be run before every go build. 
bash scripts/pack_embedded.sh            # dev build (placeholder license)
bash scripts/pack_embedded.sh --license  # production (copies license.json from repo root)
What it copies:
  • models/*.onnx → internal/embedded/models/
  • models/*_scaler.json, models/*_metadata.json → internal/embedded/models/
  • ml_config.json, strategy_params.json → internal/embedded/
  • license.json (if --license) → internal/embedded/license.json

​
cmd/licgen — license generator

A separate binary the owner builds to generate signed license.json files. Never ship licgen to customers. 
# Build licgen with the production key
go build \
  -ldflags="-X github.com/mokatific/novosky/internal/license.masterKey=SECRET" \
  -o licgen ./cmd/licgen/

# Create accounts.json (private — never ship this)
cat > accounts.json <<'EOF'
{
  "123456":  {"start": "2026-05-13", "end": "2026-08-13"},
  "1234567": {"start": "2026-05-13", "end": "2027-05-13"}
}
EOF

# Generate signed license.json
./licgen -key "NOVA-2026-XYZ" -f accounts.json -o license.json
Options:
FlagDescription
-keyHuman-readable product key (required)
-fPath to accounts JSON file (required)
-oOutput path (default: license.json)

​
Go binary — full build sequence

After make train or python scripts/retrain.py: 
# 1. Export models to ONNX and JSON
python scripts/export_scalers.py
python scripts/export_onnx_regression.py

# 2. (Production only) generate license
./licgen -key "NOVA-2026-XYZ" -f accounts.json -o license.json

# 3. Pack all assets into internal/embedded/
bash scripts/pack_embedded.sh             # dev
bash scripts/pack_embedded.sh --license   # production

# 4. Build
go build -o novosky_go ./cmd/novosky/     # dev
go build \
  -ldflags="-X github.com/mokatific/novosky/internal/license.masterKey=SECRET" \
  -o novosky_go ./cmd/novosky/            # production

# 5. Verify
./novosky_go --dry