Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,76 @@
+---
+license: mit
+library_name: xgboost
+tags:
+  - finance
+  - cryptocurrency
+  - market-microstructure
+  - liquidity-stress
+  - time-series
+---
+
+# MAIC — Liquidity Stress Detection (XGBoost, Pooled, Binary)
+
+Production model from "An Early Warning System for Liquidity Stress in
+Cryptocurrency Markets Using Trade Flow Analysis and Machine Learning."
+
+Code: https://github.com/Goodie-Goody/maic
+Results, labels, logs: https://huggingface.co/datasets/Goooddy/maic-results
+
+## What this model does
+
+Given seven market-microstructure features (OFI, RV, Kyle's lambda, ILLIQ,
+VWAP deviation, trade intensity, TCI) plus fractionally differenced price,
+computed on 300-second bars of Binance BTC/ETH/SOL trade data, predicts the
+probability the current bar reflects a liquidity-stress regime.
+
+## Performance (Fold 4, 18.8M training rows, held-out test set)
+
+| Metric          | Score  |
+|-----------------|--------|
+| F1 (weighted)   | 0.9706 |
+| Seed variance   | 0.0006 |
+
+56-108 minutes of advance warning before externally documented crisis
+timestamps (FTX bankruptcy, Terra-Luna collapse), measured against reference
+definitions the model never saw during training.
+
+## Files
+
+- `xgb_binary_pooled_fold4_seed42.pkl` -- production model, pooled across
+  BTC/ETH/SOL with an asset identifier feature. **Recommended default.**
+- `xgb_multiclass_pooled_fold4_seed42.pkl` -- multiclass variant (calm /
+  elevated / stress), backs Table 2's multiclass row.
+- `lr_binary_pooled_fold4_seed42.pkl`, `lr_multiclass_pooled_fold4_seed42.pkl`
+  -- logistic regression baselines used for comparison in the paper.
+
+**No Random Forest pickle is published.** `06d_train_production.py`
+deliberately saves `{"model": None, "scaler": scaler}` for RF rather than the
+fitted model object, since the underlying cuML RF classifier doesn't reliably
+reload across different GPU sessions/driver versions. RF's metrics and
+predictions are still valid and included in the results dataset -- only the
+serialized model artifact itself doesn't exist in a usable form.
+
+Asset-specific models at the same 5-seed production rigor don't exist:
+`06d_train_production.py` trains pooled only by design (see code comment).
+Single-seed asset-specific models exist in the results dataset repo under
+`v2/results_run1/` but are exploratory, not production-grade.
+
+## Usage
+
+Load with `pickle.load()`. Expects a dict with `model` (XGBoost classifier)
+and `scaler` (fitted feature scaler). See `scripts/12_inference.py` in the
+code repo for the full feature-construction and inference pipeline --
+loading the pickle alone is not sufficient without matching feature
+engineering.
+
+## Important caveats
+
+- Stress probability reflects liquidity *conditions*, not a price prediction.
+  Price impact is not guaranteed.
+- Labels are HMM-derived (see paper Section 3.3) with a documented
+  look-ahead in retrospective Viterbi decoding, justified empirically via a
+  three-tier external validation framework (Section 3.4/4.4).
+- Live inference reconstructs features on a single 300s window; this differs
+  from the multi-scale rolling-window construction used in training. See the
+  code repo for details on this known gap.