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

# NOVOSKY — Market Pulse Trading Intelligence

> Quantitative trading automation driven by an ML ensemble. Multi-timeframe feature engineering, gradient boosting fusion, and a layered capital protection system.

## What is NOVOSKY?

NOVOSKY is a live BTCUSD M15 trading system that combines a **4-model ML ensemble** with a fully autonomous weekly optimization pipeline. It ingests real-time candles, scores every bar with three signal models, filters trades through circuit breakers, sizes positions dynamically via an equity-aware risk multiplier, and manages open positions with a dedicated hold/exit model.

Every Sunday at 2 am UTC it retrains itself — SHAP analysis, Optuna hyperparameter search, fresh model training, config sweep, OOS validation — then either commits the improvement or rolls back automatically. Zero human input required after initial setup.

<CardGroup cols={2}>
  <Card title="For traders" icon="chart-candlestick" href="/quickstart">
    Install, run the onboarding wizard, answer 6 questions about your risk tolerance, and let the bot trade 24/7. No coding required.
  </Card>

  <Card title="For developers" icon="terminal" href="/developer/architecture">
    Full Python codebase. Sweep configs, retrain models, run backtests, push to Hugging Face Hub.
  </Card>

  <Card title="For ML researchers" icon="brain" href="/ml/models">
    4-model ensemble with 62 engineered features. LightGBM risk multiplier, dynamic SL/TP regression, SHAP-driven feature analysis, Optuna tuning loop.
  </Card>

  <Card title="Go binary distribution" icon="box" href="/developer/go-binary">
    Compiled binary with all models embedded. License-locked per MT5 account. Customers receive one executable — no Python, no model files, no HF Hub.
  </Card>
</CardGroup>

***

## Live performance

<Note>
  Performance is updated after each weekly optimization run. The OOS window uses the final 30% of data as a true holdout — never seen by the sweep.
</Note>

| Metric           | Latest OOS result |
| ---------------- | ----------------- |
| Win rate         | 71.7%             |
| Profit factor    | 5.46              |
| Max drawdown     | 4.3%              |
| Sharpe ratio     | 59.54             |
| Return           | +194.6%           |
| Trades (37d OOS) | 184               |
| Score            | 18.48             |

*Phase 17.3 — May 2026. OOS period: 37 days.*

See [Performance](/performance) for full history and methodology.

***

## How it works

```mermaid theme={null}
flowchart TD
    A[BTCUSD M15 candles\nMT5 REST API] --> B[Feature engineering\n62 features]
    B --> C{Signal model\nRF + XGB + LGB}
    C -->|confidence >= threshold| D[Signal: BUY / SELL]
    C -->|below threshold| E[HOLD — skip]
    D --> F[Filters\nATR floor · circuit breaker\nweekly DD pause · hard halt]
    F -->|pass| S{Dynamic SL/TP model\nLightGBM regression}
    S -->|SL/TP multipliers| G{Risk multiplier model\nLightGBM regression\n7 equity-state features}
    G -->|risk multiplier 0.10–1.25| H[Position sizing\nbase_risk% × multiplier × equity ÷ SL]
    H --> I[Execute order\nMT5 REST API]
    I --> J{Position model\nRF + XGB + LGB}
    J -->|HOLD| K[Wait for TP or SL]
    J -->|EXIT| L[Early close]
    K & L --> M[Log trade\nTelegram · Supabase]
```

See [How it works](/how-it-works) for a full walkthrough of each stage.

***

## Key capabilities

<CardGroup cols={2}>
  <Card title="4-model ML ensemble" icon="layers">
    Signal model (RF + XGB + LGB majority vote), position model (HOLD/EXIT/ADD), dynamic SL/TP regression, and a risk multiplier that scales exposure with equity health.
  </Card>

  <Card title="Autonomous weekly retraining" icon="rotate">
    13-phase pipeline runs every Sunday: data refresh → SHAP → Optuna → retrain (4 models) → sweep → OOS validation → auto-rollback if score drops.
  </Card>

  <Card title="5-profile risk system" icon="shield">
    From Steady Income (0.5% risk/trade) to Aggressive (4%). Every profile has a hard halt that calls `sys.exit(99)` before margin call is even close.
  </Card>

  <Card title="Broker-agnostic design" icon="plug">
    Broker-agnostic by design. Symbol, account type, pip value, digits, and server UTC offset are all auto-detected from the live MT5 API. Currently running on RoboForex BTCUSD at 1:500 leverage.
  </Card>

  <Card title="Equity-aware position sizing" icon="scale-balanced">
    Lot size scales with account equity. The SL/TP hard cap adjusts automatically so drawdown never exceeds your profile's limit regardless of account size.
  </Card>

  <Card title="Model calibration pipeline" icon="sliders">
    After every retrain, `calibrate_models()` runs automatically. Inference priority: calibrated pkl → ONNX → raw pkl. Hugging Face Hub stores all revisions.
  </Card>
</CardGroup>

***

## Quick start

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone <repo> && cd novosky
    python3.11 -m venv .venv && source .venv/bin/activate
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Run the onboarding wizard">
    ```bash theme={null}
    python scripts/onboarding.py --balance 500
    ```

    The wizard configures your `.env`, pulls the latest models from Hugging Face Hub, asks 6 risk questions, and runs the first optimization. Takes \~2.5 hours.
  </Step>

  <Step title="Go live">
    ```bash theme={null}
    python trading.py --dry    # dry run first — no real orders
    python trading.py          # live
    ```
  </Step>
</Steps>

Want to skip the optimization and trade with current models immediately?

```bash theme={null}
python ml/hf_hub.py --pull
python trading.py --dry
python trading.py
```

See [Quick start](/quickstart) for full prerequisites and setup options.