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

# Scripts reference

> All scripts in scripts/ and their command-line options. Covers training, sweeps, optimization, and utilities.

## Entry points

These are the top-level entry points (not in `scripts/`):

| Script               | Purpose                                           |
| -------------------- | ------------------------------------------------- |
| `trading.py`         | Start the live trading bot                        |
| `backtest.py`        | Run a backtest                                    |
| `scripts/retrain.py` | Train all 4 models (signal, position, SLTP, risk) |

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
# 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%.

```bash theme={null}
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
```

<Note>
  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.
</Note>

<Note>
  `_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.
</Note>

***

### 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()`.

```python theme={null}
from scripts.config_sync import sync_generated_configs, assert_generated_configs_in_sync
```

***

### notify.py

Send a manual Telegram notification.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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.

<Note>
  Ensemble and position ONNX files are exported automatically by the Python trainer. Only risk and SLTP need this script.
</Note>

***

### 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 theme={null}
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.

```bash theme={null}
# 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:

| Flag   | Description                           |
| ------ | ------------------------------------- |
| `-key` | Human-readable product key (required) |
| `-f`   | Path to accounts JSON file (required) |
| `-o`   | Output path (default: `license.json`) |

***

### Go binary — full build sequence

After `make train` or `python scripts/retrain.py`:

```bash theme={null}
# 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
```