Upload folder using huggingface_hub

README.md

@@ -0,0 +1,141 @@
+---
+library_name: pytorch-forecasting
+tags:
+- finance
+- quantitative-finance
+- systematic-trading
+- alpha-discovery
+- temporal-fusion-transformer
+- time-series
+- macro-economics
+- liquidity-cycles
+- nvidia-blackwell
+- deep-learning
+license: mit
+datasets:
+- proprietary-global-macro-10y
+metrics:
+- mae
+- rmse
+- quantile-loss
+pipeline_tag: time-series-forecasting
+widget:
+- text: "Predicting 7-day probabilistic alpha for S&P 500 assets using latent global liquidity states."
+---
+
+# Quantitative-Equity-Alpha-Transformer (QEAT)
+
+[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model%20Card-blue)](https://huggingface.co/assix-research/Quantitative-Equity-Alpha-Transformer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Hardware](https://img.shields.io/badge/Compute-NVIDIA%20DGX%20Blackwell-green)](https://www.nvidia.com/)
+
+**A Systematic, Multi-Horizon Macro-Liquidity Model for Probabilistic Alpha Discovery.**
+
+* **Architecture:** Temporal Fusion Transformer (TFT) with Quantile Regression
+* **Compute Infrastructure:** NVIDIA DGX Spark (Grace Blackwell GB10 Superchip)
+
+---
+
+## 🏛️ Abstract
+The **Quantitative-Equity-Alpha-Transformer (QEAT)** is a state-of-the-art deep learning model designed to solve the *Non-Stationarity* problem in financial time-series forecasting. Unlike traditional stochastic calculus models or naive LSTM networks, QEAT utilizes a **Temporal Fusion Transformer (TFT)** architecture to interpretably map high-dimensional macro-liquidity features to asset returns.
+
+## 🧠 Model Architecture
+
+### 1. Temporal Fusion Transformer (TFT)
+The core engine is a specialized Transformer designed for multi-horizon forecasting:
+* **Variable Selection Networks (VSN):** Automatically filters irrelevant noise inputs, focusing on high-signal liquidity events.
+* **Gated Residual Networks (GRN):** Enables deep processing of non-linear relationships while suppressing the "Vanishing Gradient" problem.
+* **Multi-Head Attention Mechanism:** Learns long-term dependencies and "Regime Shifts" by attending to historical patterns across different time scales.
+
+### 2. Probabilistic Forecasting
+Instead of a single price target, QEAT outputs a **Probability Distribution** (10th, 50th, and 90th percentiles) for institutional Risk Management (VaR).
+
+---
+
+## 📊 Data Engineering & Methodology
+
+The model was trained on a proprietary **Global Macro-Liquidity Dataset** engineered to capture cross-asset correlations under specific liquidity regimes.
+
+### 1. The Asset Universe (518 Tickers)
+A diverse, cross-asset training set designed to learn non-linear correlations:
+* **Equities:** Full **S&P 500** constituents (approx. 503 tickers).
+* **Cryptocurrency:** Top 10 Liquid L1 Protocols (BTC, ETH, SOL, AVAX, DOT, etc.).
+* **Commodities:** Key Industrial/Precious Metals ETFs (SLV, GLW) acting as proxies for global physical demand.
+
+### 2. The Time Series (10-Year History)
+* **Range:** **2014 – 2024** (Training/Validation), with Inference on **2026**.
+* **Resolution:** Daily (OHLCV) adjusted for splits and dividends.
+* **Scale:** **1.2 Million** individual training examples.
+
+### 3. The "Alpha" Features (Exogenous Liquidity Vectors)
+The model's edge comes from **6 custom-engineered liquidity flags** that serve as static covariates:
+* **🇺🇸 US Fiscal Flows:**
+    * \`is_401k_window\` (Jan 1-15): Capture automated retirement inflows.
+    * \`is_tax_refund\` (Apr 1-15): Retail capital injection cycles.
+    * \`is_bonus_window\` (Mar 1-15): Corporate performance bonus allocation.
+* **🌏 Global Cultural Flows:**
+    * \`is_diwali_window\` (Nov 1-5): Modeled physical Gold/Silver demand in India.
+    * \`is_cny_window\` (Feb 1-7): Chinese New Year liquidity shifts.
+    * \`is_holiday_season\` (Dec 24-Jan 2): Retail sentiment and volume anomalies.
+
+### 4. Target Variable
+* **Objective:** **7-Day Forward Log Returns**.
+* **Optimization:** The model minimizes Quantile Loss across three horizons (P10, P50, P90) simultaneously.
+
+---
+
+## 📈 Key Research Findings (Alpha Signals)
+
+### The "Diwali Alpha" Anomaly
+Post-training analysis of the **Attention Weights** revealed a significant market inefficiency:
+* **Observation:** The model assigned a **0.58 Importance Score** to the Diwali Liquidity Window, identifying it as the strongest predictor of Precious Metals volatility.
+* **Validation:** Backtesting the "Diwali Long" strategy yielded a High-Sharpe outcome for the Jan-Feb 2026 window.
+
+### Current Regime Prediction (Feb 2026)
+* **Signal:** **Strong Rotation (Risk-On)**
+* **Long Conviction:** Hardware Technology (\$ANET, \$GLW) & Industrial Metals.
+* **Short Conviction:** Defensive Healthcare (\$HUM, \$CNC) & Speculative L1 Crypto (\$AVAX).
+
+---
+
+## 🛠️ Usage for Quantitative Research
+
+\`\`\`python
+import torch
+from pytorch_forecasting import TemporalFusionTransformer
+
+# 1. Load the Pre-Trained Weights
+model = TemporalFusionTransformer.load_from_checkpoint("model.ckpt")
+
+# 2. Prepare Your Data
+# Data must be a Pandas DataFrame with columns:
+# ['Ticker', 'date', 'close', 'liquidity_flags', 'time_idx']
+
+# 3. Generate Probabilistic Predictions
+raw_prediction = model.predict(your_dataframe, mode="raw", return_x=True)
+
+# 4. Extract Quantiles
+interpretation = model.interpret_output(raw_prediction.output, reduction="sum")
+print("Attention Weights:", interpretation["attention"].shape)
+\`\`\`
+
+---
+
+## 📉 Hardware & Training Specifications
+
+This model was trained on **NVIDIA's next-generation accelerated computing platform**.
+
+* **System:** NVIDIA DGX Spark
+* **Compute Unit:** NVIDIA Grace Blackwell GB10 Superchip
+* **Precision:** Mixed-Precision (FP16/FP32) Matrix Multiplication (Tensor Cores)
+* **Throughput:** 1.2 Million training samples processed 8 Epochs.
+
+---
+
+## 📜 Citation & License
+
+If you use this model in your research or trading systems, please cite:
+
+> **Assi, A. (2026).** *Quantitative-Equity-Alpha-Transformer: A Systematic Approach to Macro-Liquidity Modeling using Temporal Fusion Transformers.* Hugging Face Model Hub.
+
+**License:** MIT License. Free for academic and research use.

model.ckpt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9d1dfc276565ea111163b8e238ae908611362f72cba150cb47d1dff0c5e632b
+size 11118074

requirements.txt

@@ -0,0 +1,4 @@
+torch
+pytorch-forecasting
+pandas
+numpy

sector_mapping.csv

@@ -0,0 +1,519 @@
+Ticker,Sector
+MMM,Industrials
+AOS,Industrials
+ABT,Health Care
+ABBV,Health Care
+ACN,Information Technology
+ADBE,Information Technology
+AMD,Information Technology
+AES,Utilities
+AFL,Financials
+A,Health Care
+APD,Materials
+ABNB,Consumer Discretionary
+AKAM,Information Technology
+ALB,Materials
+ARE,Real Estate
+ALGN,Health Care
+ALLE,Industrials
+LNT,Utilities
+ALL,Financials
+GOOGL,Communication Services
+GOOG,Communication Services
+MO,Consumer Staples
+AMZN,Consumer Discretionary
+AMCR,Materials
+AEE,Utilities
+AEP,Utilities
+AXP,Financials
+AIG,Financials
+AMT,Real Estate
+AWK,Utilities
+AMP,Financials
+AME,Industrials
+AMGN,Health Care
+APH,Information Technology
+ADI,Information Technology
+AON,Financials
+APA,Energy
+APO,Financials
+AAPL,Information Technology
+AMAT,Information Technology
+APP,Information Technology
+APTV,Consumer Discretionary
+ACGL,Financials
+ADM,Consumer Staples
+ARES,Financials
+ANET,Information Technology
+AJG,Financials
+AIZ,Financials
+T,Communication Services
+ATO,Utilities
+ADSK,Information Technology
+ADP,Industrials
+AZO,Consumer Discretionary
+AVB,Real Estate
+AVY,Materials
+AXON,Industrials
+BKR,Energy
+BALL,Materials
+BAC,Financials
+BAX,Health Care
+BDX,Health Care
+BRK-B,Financials
+BBY,Consumer Discretionary
+TECH,Health Care
+BIIB,Health Care
+BLK,Financials
+BX,Financials
+XYZ,Financials
+BK,Financials
+BA,Industrials
+BKNG,Consumer Discretionary
+BSX,Health Care
+BMY,Health Care
+AVGO,Information Technology
+BR,Industrials
+BRO,Financials
+BF-B,Consumer Staples
+BLDR,Industrials
+BG,Consumer Staples
+BXP,Real Estate
+CHRW,Industrials
+CDNS,Information Technology
+CPT,Real Estate
+CPB,Consumer Staples
+COF,Financials
+CAH,Health Care
+CCL,Consumer Discretionary
+CARR,Industrials
+CVNA,Consumer Discretionary
+CAT,Industrials
+CBOE,Financials
+CBRE,Real Estate
+CDW,Information Technology
+COR,Health Care
+CNC,Health Care
+CNP,Utilities
+CF,Materials
+CRL,Health Care
+SCHW,Financials
+CHTR,Communication Services
+CVX,Energy
+CMG,Consumer Discretionary
+CB,Financials
+CHD,Consumer Staples
+CI,Health Care
+CINF,Financials
+CTAS,Industrials
+CSCO,Information Technology
+C,Financials
+CFG,Financials
+CLX,Consumer Staples
+CME,Financials
+CMS,Utilities
+KO,Consumer Staples
+CTSH,Information Technology
+COIN,Financials
+CL,Consumer Staples
+CMCSA,Communication Services
+FIX,Industrials
+CAG,Consumer Staples
+COP,Energy
+ED,Utilities
+STZ,Consumer Staples
+CEG,Utilities
+COO,Health Care
+CPRT,Industrials
+GLW,Information Technology
+CPAY,Financials
+CTVA,Materials
+CSGP,Real Estate
+COST,Consumer Staples
+CTRA,Energy
+CRH,Materials
+CRWD,Information Technology
+CCI,Real Estate
+CSX,Industrials
+CMI,Industrials
+CVS,Health Care
+DHR,Health Care
+DRI,Consumer Discretionary
+DDOG,Information Technology
+DVA,Health Care
+DAY,Industrials
+DECK,Consumer Discretionary
+DE,Industrials
+DELL,Information Technology
+DAL,Industrials
+DVN,Energy
+DXCM,Health Care
+FANG,Energy
+DLR,Real Estate
+DG,Consumer Staples
+DLTR,Consumer Staples
+D,Utilities
+DPZ,Consumer Discretionary
+DASH,Consumer Discretionary
+DOV,Industrials
+DOW,Materials
+DHI,Consumer Discretionary
+DTE,Utilities
+DUK,Utilities
+DD,Materials
+ETN,Industrials
+EBAY,Consumer Discretionary
+ECL,Materials
+EIX,Utilities
+EW,Health Care
+EA,Communication Services
+ELV,Health Care
+EME,Industrials
+EMR,Industrials
+ETR,Utilities
+EOG,Energy
+EPAM,Information Technology
+EQT,Energy
+EFX,Industrials
+EQIX,Real Estate
+EQR,Real Estate
+ERIE,Financials
+ESS,Real Estate
+EL,Consumer Staples
+EG,Financials
+EVRG,Utilities
+ES,Utilities
+EXC,Utilities
+EXE,Energy
+EXPE,Consumer Discretionary
+EXPD,Industrials
+EXR,Real Estate
+XOM,Energy
+FFIV,Information Technology
+FDS,Financials
+FICO,Information Technology
+FAST,Industrials
+FRT,Real Estate
+FDX,Industrials
+FIS,Financials
+FITB,Financials
+FSLR,Information Technology
+FE,Utilities
+FISV,Financials
+F,Consumer Discretionary
+FTNT,Information Technology
+FTV,Industrials
+FOXA,Communication Services
+FOX,Communication Services
+BEN,Financials
+FCX,Materials
+GRMN,Consumer Discretionary
+IT,Information Technology
+GE,Industrials
+GEHC,Health Care
+GEV,Industrials
+GEN,Information Technology
+GNRC,Industrials
+GD,Industrials
+GIS,Consumer Staples
+GM,Consumer Discretionary
+GPC,Consumer Discretionary
+GILD,Health Care
+GPN,Financials
+GL,Financials
+GDDY,Information Technology
+GS,Financials
+HAL,Energy
+HIG,Financials
+HAS,Consumer Discretionary
+HCA,Health Care
+DOC,Real Estate
+HSIC,Health Care
+HSY,Consumer Staples
+HPE,Information Technology
+HLT,Consumer Discretionary
+HOLX,Health Care
+HD,Consumer Discretionary
+HON,Industrials
+HRL,Consumer Staples
+HST,Real Estate
+HWM,Industrials
+HPQ,Information Technology
+HUBB,Industrials
+HUM,Health Care
+HBAN,Financials
+HII,Industrials
+IBM,Information Technology
+IEX,Industrials
+IDXX,Health Care
+ITW,Industrials
+INCY,Health Care
+IR,Industrials
+PODD,Health Care
+INTC,Information Technology
+IBKR,Financials
+ICE,Financials
+IFF,Materials
+IP,Materials
+INTU,Information Technology
+ISRG,Health Care
+IVZ,Financials
+INVH,Real Estate
+IQV,Health Care
+IRM,Real Estate
+JBHT,Industrials
+JBL,Information Technology
+JKHY,Financials
+J,Industrials
+JNJ,Health Care
+JCI,Industrials
+JPM,Financials
+KVUE,Consumer Staples
+KDP,Consumer Staples
+KEY,Financials
+KEYS,Information Technology
+KMB,Consumer Staples
+KIM,Real Estate
+KMI,Energy
+KKR,Financials
+KLAC,Information Technology
+KHC,Consumer Staples
+KR,Consumer Staples
+LHX,Industrials
+LH,Health Care
+LRCX,Information Technology
+LW,Consumer Staples
+LVS,Consumer Discretionary
+LDOS,Industrials
+LEN,Consumer Discretionary
+LII,Industrials
+LLY,Health Care
+LIN,Materials
+LYV,Communication Services
+LMT,Industrials
+L,Financials
+LOW,Consumer Discretionary
+LULU,Consumer Discretionary
+LYB,Materials
+MTB,Financials
+MPC,Energy
+MAR,Consumer Discretionary
+MRSH,Financials
+MLM,Materials
+MAS,Industrials
+MA,Financials
+MTCH,Communication Services
+MKC,Consumer Staples
+MCD,Consumer Discretionary
+MCK,Health Care
+MDT,Health Care
+MRK,Health Care
+META,Communication Services
+MET,Financials
+MTD,Health Care
+MGM,Consumer Discretionary
+MCHP,Information Technology
+MU,Information Technology
+MSFT,Information Technology
+MAA,Real Estate
+MRNA,Health Care
+MOH,Health Care
+TAP,Consumer Staples
+MDLZ,Consumer Staples
+MPWR,Information Technology
+MNST,Consumer Staples
+MCO,Financials
+MS,Financials
+MOS,Materials
+MSI,Information Technology
+MSCI,Financials
+NDAQ,Financials
+NTAP,Information Technology
+NFLX,Communication Services
+NEM,Materials
+NWSA,Communication Services
+NWS,Communication Services
+NEE,Utilities
+NKE,Consumer Discretionary
+NI,Utilities
+NDSN,Industrials
+NSC,Industrials
+NTRS,Financials
+NOC,Industrials
+NCLH,Consumer Discretionary
+NRG,Utilities
+NUE,Materials
+NVDA,Information Technology
+NVR,Consumer Discretionary
+NXPI,Information Technology
+ORLY,Consumer Discretionary
+OXY,Energy
+ODFL,Industrials
+OMC,Communication Services
+ON,Information Technology
+OKE,Energy
+ORCL,Information Technology
+OTIS,Industrials
+PCAR,Industrials
+PKG,Materials
+PLTR,Information Technology
+PANW,Information Technology
+PSKY,Communication Services
+PH,Industrials
+PAYX,Industrials
+PAYC,Industrials
+PYPL,Financials
+PNR,Industrials
+PEP,Consumer Staples
+PFE,Health Care
+PCG,Utilities
+PM,Consumer Staples
+PSX,Energy
+PNW,Utilities
+PNC,Financials
+POOL,Consumer Discretionary
+PPG,Materials
+PPL,Utilities
+PFG,Financials
+PG,Consumer Staples
+PGR,Financials
+PLD,Real Estate
+PRU,Financials
+PEG,Utilities
+PTC,Information Technology
+PSA,Real Estate
+PHM,Consumer Discretionary
+PWR,Industrials
+QCOM,Information Technology
+DGX,Health Care
+Q,Information Technology
+RL,Consumer Discretionary
+RJF,Financials
+RTX,Industrials
+O,Real Estate
+REG,Real Estate
+REGN,Health Care
+RF,Financials
+RSG,Industrials
+RMD,Health Care
+RVTY,Health Care
+HOOD,Financials
+ROK,Industrials
+ROL,Industrials
+ROP,Information Technology
+ROST,Consumer Discretionary
+RCL,Consumer Discretionary
+SPGI,Financials
+CRM,Information Technology
+SNDK,Information Technology
+SBAC,Real Estate
+SLB,Energy
+STX,Information Technology
+SRE,Utilities
+NOW,Information Technology
+SHW,Materials
+SPG,Real Estate
+SWKS,Information Technology
+SJM,Consumer Staples
+SW,Materials
+SNA,Industrials
+SOLV,Health Care
+SO,Utilities
+LUV,Industrials
+SWK,Industrials
+SBUX,Consumer Discretionary
+STT,Financials
+STLD,Materials
+STE,Health Care
+SYK,Health Care
+SMCI,Information Technology
+SYF,Financials
+SNPS,Information Technology
+SYY,Consumer Staples
+TMUS,Communication Services
+TROW,Financials
+TTWO,Communication Services
+TPR,Consumer Discretionary
+TRGP,Energy
+TGT,Consumer Staples
+TEL,Information Technology
+TDY,Information Technology
+TER,Information Technology
+TSLA,Consumer Discretionary
+TXN,Information Technology
+TPL,Energy
+TXT,Industrials
+TMO,Health Care
+TJX,Consumer Discretionary
+TKO,Communication Services
+TTD,Communication Services
+TSCO,Consumer Discretionary
+TT,Industrials
+TDG,Industrials
+TRV,Financials
+TRMB,Information Technology
+TFC,Financials
+TYL,Information Technology
+TSN,Consumer Staples
+USB,Financials
+UBER,Industrials
+UDR,Real Estate
+ULTA,Consumer Discretionary
+UNP,Industrials
+UAL,Industrials
+UPS,Industrials
+URI,Industrials
+UNH,Health Care
+UHS,Health Care
+VLO,Energy
+VTR,Real Estate
+VLTO,Industrials
+VRSN,Information Technology
+VRSK,Industrials
+VZ,Communication Services
+VRTX,Health Care
+VTRS,Health Care
+VICI,Real Estate
+V,Financials
+VST,Utilities
+VMC,Materials
+WRB,Financials
+GWW,Industrials
+WAB,Industrials
+WMT,Consumer Staples
+DIS,Communication Services
+WBD,Communication Services
+WM,Industrials
+WAT,Health Care
+WEC,Utilities
+WFC,Financials
+WELL,Real Estate
+WST,Health Care
+WDC,Information Technology
+WY,Real Estate
+WSM,Consumer Discretionary
+WMB,Energy
+WTW,Financials
+WDAY,Information Technology
+WYNN,Consumer Discretionary
+XEL,Utilities
+XYL,Industrials
+YUM,Consumer Discretionary
+ZBRA,Information Technology
+ZBH,Health Care
+ZTS,Health Care
+BTC-USD,Cryptocurrency
+ETH-USD,Cryptocurrency
+SOL-USD,Cryptocurrency
+XRP-USD,Cryptocurrency
+ADA-USD,Cryptocurrency
+AVAX-USD,Cryptocurrency
+DOGE-USD,Cryptocurrency
+DOT-USD,Cryptocurrency
+LINK-USD,Cryptocurrency
+MATIC-USD,Cryptocurrency
+IAU,Precious Metals
+SLV,Precious Metals
+PPLT,Precious Metals
+PALL,Precious Metals
+CPER,Precious Metals