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

# Cloud services

> NOVOSKY integrates with three optional cloud services: Hugging Face Hub (model storage), Supabase (trade log), and Telegram (alerts). Hugging Face is required; the others are optional but strongly recommended.

## Hugging Face Hub

**Required for the Python bot. Not used by the Go binary.**

The Python bot stores all ML model binaries (`.pkl` and `.onnx`) on Hugging Face Hub and pulls the latest models at startup. The Go binary embeds all models at compile time and does not connect to Hugging Face Hub at runtime.

### Setup

1. Create a free account at [huggingface.co](https://huggingface.co)
2. Create a new model repository (private)
3. Generate an access token with `write` permission at Settings → Access Tokens
4. Add to your `.env`:

```bash theme={null}
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
HF_REPO_ID=yourname/novosky-models
```

### Usage

```bash theme={null}
# Pull latest models (run at startup / before trading)
python ml/hf_hub.py --pull

# Push after retrain
python ml/hf_hub.py --push

# Push with a tag (e.g. after a major retrain)
python ml/hf_hub.py --push --tag phase-16

# List available revisions
python ml/hf_hub.py --list
```

The push command uploads all `.pkl` and `.onnx` files from `models/` plus the `models/model_compat.json` and `models/risk_metadata.json` metadata files.

### What is stored

| File                                         | Description                                           |
| -------------------------------------------- | ----------------------------------------------------- |
| `rf_signal.pkl`                              | Random Forest signal model (raw)                      |
| `rf_signal_calibrated.pkl`                   | Calibrated RF signal model                            |
| `rf_signal.onnx`                             | ONNX export of RF signal model                        |
| `xgb_signal.pkl`, `_calibrated.pkl`, `.onnx` | XGBoost equivalents                                   |
| `lgb_signal.pkl`, `_calibrated.pkl`, `.onnx` | LightGBM signal equivalents                           |
| `position_*.pkl`                             | Position model files                                  |
| `sltp_*.pkl`                                 | SL/TP model files                                     |
| `risk_*.pkl`                                 | Risk multiplier model files                           |
| `model_compat.json`                          | Feature list hash + model paths — compatibility check |
| `risk_metadata.json`                         | Risk model metadata: trained\_at, val\_mae, features  |

***

## Supabase

**Optional.** Supabase stores trade logs, open position snapshots, and bot status. The website dashboard reads from Supabase for trade history display.

### Setup

1. Create a free project at [supabase.com](https://supabase.com)
2. Run the schema migrations from `supabase/migrations/`
3. Add to your `.env`:

```bash theme={null}
SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
SUPABASE_KEY=your-service-role-key
```

### Schema

```sql theme={null}
-- Core tables (from supabase/migrations/)
trades          -- closed trade records with broker deal data
positions       -- open position snapshots
account_snapshots  -- periodic balance/equity snapshots
bot_status      -- heartbeat and current state
```

### Data integrity rules

<Warning>
  For cent accounts, always store raw MT5 values — do not convert USC to USD before writing.

  * Store `closing_deal.profit` as-is (e.g. 230.0 USC, not 2.30 USD)
  * For price-based profit estimates: use `_usd_to_raw(price_diff × lot × contract_size)` which multiplies by 100 for cent accounts
  * `entry_at` timestamps: always strip microseconds → `datetime.now(UTC).replace(microsecond=0).isoformat()`
</Warning>

### Trade reconciliation

After every sync\_fallback or estimation path, `_reconcile_trade_bg(ticket, ...)` fires in the background. It retries `_get_deals_for_position()` every 60 seconds for up to 4 hours, then overwrites Supabase with real broker deal data.

RoboForex can delay closing deal history by hours for manual (mobile) closes. The reconciliation loop handles this automatically.

***

## Telegram

**Optional but strongly recommended.** Telegram sends trade alerts, weekly optimize reports, and error notifications.

### Setup

1. Create a bot with [@BotFather](https://t.me/BotFather) and copy the token
2. Get your chat ID (send a message to your bot, then check `https://api.telegram.org/bot<token>/getUpdates`)
3. Add to your `.env`:

```bash theme={null}
TELEGRAM_BOT_TOKEN=7234567890:AABxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHAT_ID=123456789
```

### Notification types

| Event                      | Message type                                         |
| -------------------------- | ---------------------------------------------------- |
| Trade opened               | BUY/SELL signal, lot, entry price, SL/TP, confidence |
| Trade closed               | P\&L, duration, exit reason (TP/SL/EXIT signal)      |
| Weekly optimize — success  | New score, improvement %, key config, pushed to HF   |
| Weekly optimize — rollback | Old score retained, reason                           |
| Hard halt                  | Equity drawdown % that triggered halt                |
| MT5 connection error       | API URL, error code                                  |

### Telegram commands

The bot responds to commands sent from your chat:

```
/status   — current position, equity, today's P&L
/stats    — last 20 trades summary
/pause    — pause trading (next cycle will skip)
/resume   — resume trading
/halt     — trigger immediate hard halt
```

Commands are handled by `trading/telegram_commands.py`.

***

## Service dependency summary

<Tabs>
  <Tab title="Python bot">
    | Service          | Required | Without it                         |
    | ---------------- | -------- | ---------------------------------- |
    | MT5 REST API     | Yes      | Bot cannot trade                   |
    | Hugging Face Hub | Yes      | Cannot load models                 |
    | Supabase         | No       | No trade log, no website dashboard |
    | Telegram         | No       | No alerts or reports               |
  </Tab>

  <Tab title="Go binary">
    | Service               | Required | Without it                         |
    | --------------------- | -------- | ---------------------------------- |
    | MT5 REST API          | Yes      | Bot cannot trade                   |
    | Hugging Face Hub      | No       | Models are embedded in the binary  |
    | Supabase              | No       | No trade log, no website dashboard |
    | Telegram              | No       | No alerts or reports               |
    | AI assistant endpoint | No       | Free-text commands disabled        |
  </Tab>
</Tabs>