Add professional model card for Nexus Shadow-Quant

README.md

@@ -0,0 +1,113 @@
+---
+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>