Macro Intelligence Platform

An academically-validated, open-source quantitative business cycle forecasting engine and interactive macroeconomic intelligence dashboard. It traces economic phase shifts across 4 classical regimes (Expansion, Slowdown, Contraction, Recovery) and projects 3M/6M/9M forward trajectories using a 3-signal consensus framework.

---

📌 Table of Contents

• 🌟 Highlights
• 📊 Backtest & Empirical Validation
• 🏛️ System Architecture
• 🚀 Quick Start
• 🌐 Open Data Pipeline
• 📄 Automated Strategy Note Export
• 📚 Developer Documentation
• 🤝 Contributing & License

---

🌟 Highlights

• 4-Phase Business Cycle Tracing: Maps macro health ($X$) and momentum ($Y$) using rolling Z-score transformations of Composite Leading Indicators (OECD CLI) and economic drivers.
• Three-Signal Consensus Forecasting: Eliminates single-model bias by blending orthogonal signals calibrated via out-of-sample backtesting:
  1. CLI Momentum Extrapolation (40% weight — exponential decay pull toward long-term trend)
  2. Multivariate Historical Analogues (35% weight — Euclidean distance matching across past cycle footprints)
  3. Auxiliary Macro Driver Assessment (25% weight — walk-forward Ridge regression covering Real Policy Rate, Core Industries, CPI, and Yield Spreads)
• 100% Open Data & Provider Provenance: Fully automated pipeline using public sources (FRED, DPIIT, IMF SDMX, Yahoo Finance, RBI) with explicit ProviderMeta tracking (live, cache, bundled_fallback, schema_ok).
• Python API & Notebook Integration: Clean 3-step programmatic interface (from macro_intel import load_macro_data, compute_features, forecast_cycle) with typed DataBundle and ForecastResult containers.
• Documented JSON Output & Live Dashboard: Automated serialization to JSON Schema draft-07 contract (docs/latest_forecast.json), static site generation (docs/index.html), and append-only live track record ledger (docs/live_track_record.csv).
• Automated Institutional Strategy Notes: Exports publication-ready PDF research briefs featuring Markov transition matrices, scenario distributions (Bull/Base/Bear), and narrative synthesis.

---

📊 Backtest & Empirical Validation

Evaluated across a rolling 229-month out-of-sample historical window (Jan 2007 – Present). Note: 6M is used as the primary evaluation horizon for backtest validation; 3M and 9M trajectories are projected dynamically using the same underlying consensus framework.

Model / Baseline	Full Window 6M Quadrant Accuracy (2007–2026)	Held-Out 6M Quadrant Accuracy (2019–2026)	Health (X) MAE	Momentum (Y) MAE	Distance MAE
Persistence Baseline	47.6%	49.4%	0.943	0.963	1.471
CLI Momentum Only	67.7%	63.5%	0.674	0.802	1.133
Historical Analogues Only	63.3%	70.6% 🏆	0.598	0.753	1.053
Macro Drivers Only	65.9%	50.6%	0.664	0.661	1.013
Transition Matrix Only	47.2%	49.4%	N/A	N/A	N/A
Two-Signal Benchmark (55% Mom / 45% Ana) *	71.2% 🏆	68.2%	0.555 🏆	0.594 🏆	0.877 🏆

* The live production system uses a calibrated 3-signal consensus (40% Momentum / 35% Analogues / 25% Macro Drivers). The 2-signal benchmark row represents historical standalone out-of-sample evaluation.

📈 Statistical Significance & Conviction Calibration

• McNemar's Test (Classification Accuracy): $\chi^2 = 29.26, \quad p = 6.33 \times 10^{-8} \quad (p < 0.01)$ — Outperformance over Persistence is highly statistically significant.
• Diebold–Mariano Test (Continuous Error): $DM = 5.07, \quad p = 3.94 \times 10^{-7} \quad (p < 0.01)$ — Reduction in Distance MAE is highly statistically significant.
• High-Conviction Accuracy: Signals with $\ge 58%$ conviction score achieve 89.8% realized quadrant accuracy ($N=98$, 95% Wilson CI: $[82.2%, 94.4%]$).

---

🏛️ System Architecture

The platform follows a clean, decoupled 6-layer architecture:

flowchart TD
    A[Data Ingestion Engine] --> B[Feature Engine]
    B --> C[Macro Intelligence Engine]
    C --> D[Three-Signal Forecasting Engine]
    D --> E[Python API / DataBundle & ForecastResult]
    E --> F[Interactive Matplotlib Dashboard]
    E --> G[ReportLab PDF Strategy Note Generator]
    E --> H[Documented JSON Export & GitHub Pages Site]

Loading

Layer	Directory	Responsibilities
Data Engine	data/	Live provider fetching (FRED, DPIIT, IMF, Yahoo Finance, RBI) + ProviderMeta provenance tracking & local caching.
Feature Engine	features/	Vectorized Z-score transformations, velocity ($d^2/dt^2$), B-spline interpolation.
Analytics	analytics/	Quantitative models (MacroIntelligenceEngine, ForecastingEngine, Markov TransitionMatrix).
Integrations	integrations/	External analytics modules & visualization extensions (e.g. Relative Rotation Graphs / RRG).
API & Models	api.py, macro_intel.py, models.py	Typed DataBundle / ForecastResult dataclasses and macro_intel import interface.
Research	research/	Institutional strategy narrative synthesis and publication-ready ReportLab PDF report generator.
User Interface	ui/	Interactive Matplotlib desktop dashboard with playback controls, sparklines, and market context panels.
Web Server & UI	web/	FastAPI REST API backend (web/server.py) and modern React 18 SPA frontend (web/frontend/).

---

🚀 Quick Start

1. Prerequisites

• Python 3.10+
• Git

2. Installation

git clone https://github.com/VIJNESH200/macro_intelligence_platform.git
cd macro_intelligence_platform
pip install -e .

3. Python API Usage

from macro_intel import load_macro_data, compute_features, forecast_cycle

# 1. Load data bundle with provenance metadata
# Select either built-in market profile: "INDIA" or "US".
# Use offline=False on a first US run if no local cache exists yet.
bundle = load_macro_data(market="INDIA", offline=True)

# 2. Compute 2D cycle metrics (X Health, Y Momentum)
bundle = compute_features(bundle)

# 3. Project business cycle forward
result = forecast_cycle(bundle)
print(f"Current Regime: {result.current_regime}")
print(f"6M Projection: {result.forecasts['6m'].quadrant} (Conviction: {result.forecasts['6m'].conviction}%)")

See notebooks/quickstart.ipynb for an interactive walkthrough notebook.

4. India and US forecasts

The public API and GitHub Pages dashboard support both India and the United States:

us_bundle = load_macro_data(market="US", offline=False)
us_features = compute_features(us_bundle)
us_forecast = forecast_cycle(us_features)

The Pages dashboard publishes separate India and US JSON payloads and lets readers switch between the two markets in the browser.

5. Launching the GUI App

Windows Launcher: Double-click run_platform.bat or run:

run_platform.bat

Cross-Platform Command Line:

python main.py

5. Web Interface & React Frontend

Launch the modern Web UI and REST API server:

Windows Launcher:

run_web.bat

Cross-Platform Command Line:

./run_web.sh

Or start the server directly using Uvicorn:

uvicorn web.server:app --host 127.0.0.1 --port 8000

• Web App: Open http://127.0.0.1:8000/ in your browser.
• REST API Docs: Open http://127.0.0.1:8000/docs for interactive OpenAPI documentation.

6. Running Validation Benchmarks & Tests

To run the full out-of-sample backtest suite and unit tests:

pytest tests/
python tests/backtest_benchmarks.py

---

🌐 Open Data Pipeline

Unlike proprietary macro engines, this platform operates on 100% open public datasets:

• OECD India CLI: Sourced directly from FRED (INDLOLITOAASTSAM).
• Index of Eight Core Industries (ICI): Sourced live from the official DPIIT portal (eaindustry.nic.in), chain-linked across base years (2011-12 and 2022-23).
• Consumer Price Index (CPI): Sourced via IMF SDMX (IND.CPI._T.IX.M) & official government statistics.
• Yield Curve & Real Rates: 10Y India Government Bond Yield vs. 91D T-Bill Rate and RBI Policy Repo Rate.
• Market Context: Live Yahoo Finance indices (Nifty 50, Sensex, Nifty Bank, S&P 500, Nasdaq 100, Brent Crude, USD/INR, VIX).

Market Selector (India / US)

The India / US buttons in the lower-right corner switch the entire dashboard — primary indicator, macro drivers, and market context panel — between the two market profiles defined in config/markets.py. Each market has its own indicator ticker, macro-driver set, and market-context series (e.g. India tracks Sensex/Nifty, US tracks Dow Jones/Russell 2000), so switching markets reloads and recomputes the full pipeline rather than just relabeling the existing chart.

---

📄 Automated Strategy Note Export

Clicking the "Export PDF" button in the dashboard generates a publication-ready macroeconomic brief in exports/:

Page 1: Executive Summary & Thesis	Page 2: Cycle Position & Dashboard

• Executive Summary & Strategy Cards: Stance classification (Highly Constructive, Constructive, Cautious, Defensive, Highly Defensive).
• Markov Transition Probabilities: Empirical 4×4 regime transition probabilities and expected phase durations.
• Scenario Horizon Matrix: 3M/6M/9M Bull, Base, and Bear probabilistic paths with expected asset returns.
• Methodology Appendix: Formal mathematical definitions for Z-scores, Euclidean analogue matching, and conviction scoring.

---

📚 Developer Documentation

For deep architectural details, test infrastructure, and project execution context:

• 📖 Methodology & Specifications: Mathematical definitions for Z-scores, velocity, analogues, and conviction scoring.
• 🏗️ Developer Briefing & Architecture: Codebase layout, layer contracts, and module specs.
• 🧪 Test & Validation Infrastructure: Out-of-sample backtesting methodology and benchmark quality gates.
• 📋 Project Roadmap & History: Architectural phase progression and feature history.

---

🤝 Contributing & License

Contributions are welcome! Please submit Pull Requests or open an Issue for feature suggestions.

This project is open-source under the MIT License.

---

📄 Citation

If you use this platform in academic research or quantitative modeling, please cite it using:

@software{vijnesh_macro_intelligence_2026,
  author = {Vijnesh},
  title = {Macro Intelligence Platform: Quantitative Business Cycle Forecasting Engine},
  url = {https://github.com/VIJNESH200/macro_intelligence_platform},
  year = {2026}
}