---
license: mit
tags:
  - finance
  - trading
  - bitcoin
  - cryptocurrency
  - quantitative-analysis
  - ensemble
  - xgboost
  - pytorch
  - transformer
  - lstm
  - time-series
  - forecasting
language:
  - en
pipeline_tag: tabular-classification
library_name: pytorch
---

<div align="center">

# 🔮 Nexus Shadow-Quant — Trained Models

### Institutional-Grade Crypto Intelligence Engine

[![GitHub](https://img.shields.io/badge/Source-lukeedIII%2FPredictor-181717?style=for-the-badge&logo=github)](https://github.com/lukeedIII/Predictor)
[![Version](https://img.shields.io/badge/Version-v6.4.2-6366f1?style=for-the-badge)]()
[![License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)]()

</div>

---

## 📋 Overview

This repository contains the **pre-trained model artifacts** for [Nexus Shadow-Quant](https://github.com/lukeedIII/Predictor) — a 16-model ensemble engine for BTC/USDT directional forecasting.

**Why this exists:** Training the full model stack from scratch takes ~6 hours on a modern GPU. By hosting the trained weights here, new installations can pull them instantly and skip the initial training phase entirely.

---

## 🏗️ Model Architecture

| Model | Type | Parameters | Purpose |
|:---|:---|:---|:---|
| `predictor_v3.joblib` | XGBoost Ensemble | ~500 trees | Primary directional classifier |
| `nexus_lstm_v3.pth` | Bi-LSTM | ~2M | Sequence pattern recognition |
| `nexus_transformer_v2.pth` | Transformer | ~152M | Long-range dependency modeling |
| `feature_scaler_v3.pkl` | StandardScaler | — | Feature normalization state |

### Supporting Models (16-Model Quant Panel)
- **GARCH(1,1)** — Volatility regime detection
- **MF-DFA** — Multi-fractal detrended fluctuation analysis
- **TDA** — Topological Data Analysis (persistent homology)
- **Bates SVJ** — Stochastic volatility with jumps
- **HMM (3-state)** — Hidden Markov Model for regime classification
- **RQA** — Recurrence Quantification Analysis
- + 10 more statistical models

---

## 📊 Performance (Audited)

| Metric | Value |
|:---|:---|
| **Audit Size** | 105,031 predictions on 3.15M candles |
| **Accuracy** | 50.71% (statistically significant above 50%) |
| **Sharpe Ratio** | 0.88 (annualized, fee-adjusted) |
| **Prediction Horizon** | 15 minutes |
| **Features** | 42 scale-invariant (returns/ratios/z-scores) |
| **Fee Model** | Binance taker 0.04% + slippage 0.01% |

---

## ⚡ Quick Start

### Automatic (Recommended)
The Nexus Shadow-Quant app will **auto-pull** these models on first startup if no local models are found. Simply:
1. Set your `HUGGINGFACE_TOKEN` and `HF_REPO_ID` in Settings.
2. Restart the backend.
3. Models are downloaded and the predictor is ready instantly.

### Manual
```bash
pip install huggingface_hub
huggingface-cli download Lukeexus/Predictor-Models --local-dir ./models
```

---

## 🔄 Sync Protocol

| Action | What happens |
|:---|:---|
| **Push to Hub** | Uploads all files from `models/` folder to this repo |
| **Pull from Hub** | Downloads latest weights, re-initializes the predictor |
| **Auto-Pull** | On startup, if no local models found, pulls automatically |

---

## ⚠️ Disclaimer

These models are trained on historical BTC/USDT data and are provided for **educational and research purposes only**. They are not financial advice. Cryptocurrency markets are volatile. Past performance does not guarantee future results.

---

<div align="center">

**Dr. Nexus** · *Quantitative intelligence, engineered locally.*

</div>