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.
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
- Create a free account at huggingface.co
- Create a new model repository (private)
- Generate an access token with
write permission at Settings → Access Tokens
- Add to your
.env:
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
HF_REPO_ID=yourname/novosky-models
Usage
# 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
.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
- Create a free project at supabase.com
- Run the schema migrations from
supabase/migrations/
- Add to your
.env:
SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
SUPABASE_KEY=your-service-role-key
Schema
-- 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
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()
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
- Create a bot with @BotFather and copy the token
- Get your chat ID (send a message to your bot, then check
https://api.telegram.org/bot<token>/getUpdates)
- Add to your
.env:
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
trading/telegram_commands.py.
Service dependency summary
| 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 |
| 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 |
