investment-sandbox/QUANT_ROADMAP.md

QuantSandbox System Architecture & Quantitative Roadmap

This document serves as the permanent, centralized system architecture design and master context for all future quantitative feature deployments.

---

1. Repository Status & Milestone Log

Completed Phases & Integrated Silos

• Phase 1.0: Portfolio Sandbox
  • Features: Real-time volatility estimators, portfolio optimization mechanics, and Swamy-Arora random effects panel regression solvers.
  • Status: Fully Operational (Production Lock).
• Phase 2.0: Live GJR-GARCH Scanners
  • Features: Real-time rolling volatility forecasting engine that detects asymmetric leverage effects in equity volatility.
  • Status: Fully Operational (Production Lock).
• Phase 3.0: Real FRED Macro Ingestion
  • Features: Real-time server-side API integration with Federal Reserve Economic Data (FRED). Ingests Personal Savings Rates, Credit Card Delinquencies, Housing Starts, and Case-Shiller indices.
  • Status: Fully Operational (Production Lock).
• Phase 4.7: AI & Tech Hyper-Leverage Silo
  • Features: Track the AI CapEx-Overinvestment Cycle for NVDA, MSFT, GOOGL, META, and AMD. Calculates ROI-to-CapEx (Monetization Gap), Nvidia Supply-Chain Velocity Index, and Tech Infrastructure Leverage with a 60-minute caching layer.
  • Status: Fully Operational (Production Lock).

---

2. Master Backlog Architecture: The 6-Level Cockpit Matrix

The system tracks and synthesizes ~50 quantitative metrics divided into 6 distinct analytical levels to form a unified Market Regime Classifier.

Level 1: Macro & Credit Layer (21 Metrics)

• Inflation Vectors: CPI YoY, Core CPI, PPI.
• Sovereign Yields & Term Structure: US 10Y Yield, US 2Y Yield, 2S10S Yield Spread, High-Yield Credit Spreads.
• Central Bank Liquidity: Fed Balance Sheet Assets, ECB Refinancing Rate, Fed Funds Rate, M2 Money Supply, Reverse Repo (RRP) Volumes, Treasury General Account (TGA) levels.
• Macro Capacity: S&P 500-to-GDP Ratio (Buffett Indicator Proxy).
• Labor Market Dynamics: Non-Farm Payrolls (NFP), Unemployment Rate, Initial Jobless Claims.
• Housing & Credit Velocity: Housing Starts, Mortgage Applications Index Proxy, S&P Case-Shiller Home Price Index.
• Consumer Stress Indexes: Credit Card Delinquency Rates, Personal Savings Rate.

Level 2: Market Breadth Layer (8 Metrics)

• Moving Average Spreads: Percentage of S&P 500 constituents trading above their 50-day and 200-day Simple Moving Averages.
• Volume Accumulation: Cumulative Advance-Decline Line (A/D Line) scaled by volume.
• McClellan Oscillator: Index tracking short-term momentum shifts in net advances.
• High-Low Index: Ratio of stocks making new 52-week highs to total new highs/lows.
• Sector Rotational Momentum: Relative strength vectors of Defensive (XLU, XLP, XLV) vs. Cyclical/Growth (XLK, XLY, XLI) sectors.
• Beta Distribution spreads: Dispersion of individual constituent betas relative to index beta.

Level 3: Sentiment & Positioning Flow Layer (7 Metrics)

• Implied Volatility Structures: VIX, VIX/VVIX term structure spreads.
• Option Flows: CBOE Equity Put/Call Volume Ratio (10-day moving average).
• Retail Positioning: AAII Bulls-Bears Spread, margin debt levels in retail brokerage accounts.
• Institutional Positioning: NAAIM Exposure Index, CFTC Commitments of Traders (COT) net non-commercial positioning in S&P 500 futures.

Level 4: Corporate Fundamental & Accruals Layer (6 Metrics)

• Accrual Integrity: Sloan Ratio tracking earnings quality.
• Bankruptcy Probability: Altman Z-Score for manufacturing and non-manufacturing firms.
• Earnings Manipulation: Beneish M-Score tracking probability of financial statement manipulation.
• Financial Strength: Piotroski F-Score (9-point fundamental health checklist).
• Margin Compression Dynamics: Operating Margin YoY changes, Gross Margin trends.

Level 5: Technical Momentum & Volatility Layer (5 Metrics)

• Vol Forecasts: Rolling GJR-GARCH downside volatility forecast vectors.
• Relative Strength: 14-day Relative Strength Index (RSI).
• Trend Vectors: MACD Signal Line Spreads.
• Range Expansion: Average True Range (ATR) normalized by price.
• Beta Expansion Multipliers: Realized beta shifts in high-beta tech components.

Level 6: Alternative Data Layer (3 Metrics)

• Supply Chain Disruption: Supply-Chain Velocity Index (Aggregate buyer purchase obligations vs. hardware supplier inventories).
• Employment Demand: Tech sector job postings scraped from aggregators.
• Credit Card Transactions: Real-time consumer retail spending proxies.

---

3. Whale Reconnaissance Layer

Designed to track the equity holdings of institutional boutique Value and Small-Cap asset managers via SEC Form 13F filings.

graph TD
    A[SEC 13F Filings Ingestion] --> B{Filter Boutique Managers}
    B -- AUM < $5B & High Active Share --> C[Extract High-Conviction Long Positions]
    B -- Large Index Funds --> D[Discard]
    C --> E[Compute Quarterly Position Shifts]
    E --> F[Generate Whale Satellite-Screener Score]

Screener Specifications

• Target Universe: Boutique managers with Asset Under Management (AUM) between $100M and $5B, exhibiting an Active Share > 80\%.
• Quant Filters:
  1. Concentration Index: Top 10 holdings must exceed 50\% of the total reported portfolio value.
  2. Position Size Changes: Track quarterly additions (\Delta W_{i} > 2\%) where the manager is actively building a stake.
  3. Co-ownership Clusters: Identify stocks bought by 3 or more selected boutique managers simultaneously.

---

4. Deep-Dive Corporate Terminal Specifications

When evaluating an individual equity ticker, the terminal computes three quantitative risk markers:

I. The Sloan Ratio (Earnings Quality Indicator)

Measures the proportion of earnings backed by non-cash accruals. A high ratio indicates that earnings are driven by accounting accruals rather than real operating cash flows.

Mathematical Formulation:

\text{Sloan Ratio} = \frac{\text{Net Income} - \text{Operating Cash Flow} - \text{Investing Cash Flow}}{\text{Total Assets}}

Alert Thresholds:

• Stable Accruals: \le 5\% (Green)
• Elevated Accruals: 5\% < \text{Sloan Ratio} \le 10\% (Amber)
• Toxic Accruals (Manipulative Risk): > 10\% (Flashing Neon Rose-Red)

---

II. Analyst Revision Impulse (ARI)

Tracks the momentum of consensus earnings estimates over a rolling 14-day window to identify positive or negative structural inflections before earnings reports.

Mathematical Formulation:

\text{ARI}_{t} = \sum_{h=1}^{H} \frac{E_{t}(\text{EPS}_{h}) - E_{t-14}(\text{EPS}_{h})}{E_{t-14}(\text{EPS}_{h})}

Where:

• E_{t}(\text{EPS}_{h}) is the consensus EPS estimate at day t for fiscal period h.
• H represents the number of forward fiscal quarters modeled (standard H=4).

---

III. GJR-GARCH Downside Buffer

Calculates the conditional Value-at-Risk (VaR) and Expected Shortfall (ES) at a 99\% confidence level over a 10-day forward horizon using volatility projections from Module 1.

Mathematical Formulation:

\sigma_{t}^2 = \omega + \left(\alpha + \gamma I_{t-1}\right) \epsilon_{t-1}^2 + \beta \sigma_{t-1}^2 \text{VaR}_{99\%, 10D} = P_{t} \times \left(1 - e^{z_{0.01} \times \sqrt{10} \times \sigma_{t}}\right)

Where:

• I_{t-1} = 1 if \epsilon_{t-1} < 0, and 0 otherwise (asymmetric shock multiplier).
• z_{0.01} is the 1\% quantile of the standardized residual distribution (Student-t or Normal).

---

5. Multi-Regime Transition Classifier

The core cognitive brain of the sandbox dynamically adjusts allocation weights across our portfolio modules based on estimated macroeconomic and market states.

graph LR
    A[Level 1-6 Inputs] --> B[Dynamic Z-Score Solver]
    B --> C[Markov-Switching Model]
    C --> D{Regime Output}
    D -->|Regime 0: Risk-On| E[Overweight Equities/Growth]
    D -->|Regime 1: Transition| F[Neutral / Hedge overlay]
    D -->|Regime 2: Risk-Off| G[Overweight Bonds/Cash/Short Vol]

Model Specifications

1. Regime Estimation: A 3-state Markov-Switching Vector Autoregressive (MS-VAR) model classifying the market into:
   • Regime 0 (Expansion/Risk-On): Low volatility, positive macro surprise, expanding supply-chain velocity.
   • Regime 1 (Late-Cycle/Transition): Softening breadth, rising credit spreads, negative monetization gaps.
   • Regime 2 (Contraction/Risk-Off): High realized volatility, yield curve uninversion, consumer savings depletion.
2. Dynamic Weight Allocation: \mathbf{W}_{t} = s_t \mathbf{W}_{\text{Risk-On}} + (1 - s_t) \mathbf{W}_{\text{Risk-Off}} Where s_t \in [0, 1] represents the filtered probability of being in the expansionary regime at time t.