MCP Zero Shot Agentic Forecaster

A production-grade, MCP-compliant neuro-symbolic forecasting tool. Designed for Agentic AI orchestrators to autonomously resolve inventory shortages, evaluate demand risk, and execute quantile-bounded supply-chain decisions—without requiring local fine-tuning.

---

Table of Contents

• Why This Is an MCP Tool / Agentic Skill
• Key Features
• The Problem & The Solution
• Benchmarks & Data Architecture
• System Architecture
• Quick Start
• Test Suite
• Project Structure
• Metrics Overview

---

Why This Is an MCP Tool / Agentic Skill

An autonomous agentic system acts, plans, and reasons. This repository does not independently make supply chain decisions; rather, it is exactly the type of high-fidelity, highly-structured mathematical backend that an Enterprise Agent would call.

Neuro-Symbolic Fit: In an Enterprise Neuro-symbolic Agentic AI System, a "Supply Chain Optimization Agent" (the neural/reasoning layer) evaluates an inventory shortage and decides to forecast future demand. It constructs the TimeSeriesInputPayload (the symbolic/structured layer), passes it to this tool, and receives the ForecastOutputPayload.

Because this codebase heavily utilizes Pydantic validation to enforce strict input boundaries (context bounds, horizon lengths) and output formats (quantiles, mean predictions, confidence scores), it is perfectly wrapped to be exposed as a Model Context Protocol (MCP) tool for an LLM-driven Agent.

A SOTA standard tool that a neural reasoning layer can confidently call to handle inventory shortages — verified.

---

Key Features

• Dual Foundation Models: Automatic routing — amazon/chronos-2 for univariate series, google/timesfm-2.5 (XReg) when price_index or promo_flag exogenous signals are present.
• 3D Tensor Pipeline: Strict (n_series, n_variates, history_length) input format with shape-agnostic output parser (handles 3D point forecasts and 4D sample/quantile tensors).
• Pydantic Symbolic Boundary: TimeSeriesInputPayload enforces context bounds [16, 16,000] timesteps, horizon [1, 1024], and exogenous array alignment; ForecastOutputPayload validates output dimensions, quantile bands, and model identity.
• Uncertainty Track: Pinball loss (p10/p90), CRPS, and confidence score (normalized spread) for risk-aware supply-chain decisions.
• OOD Generalization: Evaluates on M5 Walmart (3,049 products) and Corporación Favorita (Ecuadorian retail with real-world oil-price and holiday covariates).
• MCP-Ready: mcp_server.py exposes forecast_demand() as a strictly-typed tool — LLMs auto-discover the JSON schema and receive structured validation errors on hallucinated inputs.

---

The Problem & The Solution

Historically, enterprise supply chain forecasting required massive, heavily engineered ML pipelines. Competitions were completely dominated by complex LightGBM, XGBoost, and CatBoost models packed with thousands of rolling lag variables, rolling means, and cross-sectional target encodings. These traditional models require constant retraining and struggle to adapt to sudden market shocks without explicit historical mapping.

The Solution: By building this specific foundation model repository, we are taking a fundamentally different approach. Instead of training discrete models to learn specific store dynamics, we are testing if pre-trained attention heads can read the statistical signature of a history array in-context and accurately extrapolate it without any explicit backpropagation updates or local fine-tuning.

---

Benchmarks & Data Architecture

The architecture we initialized maps directly to the most rigorous supply chain forecasting benchmarks in data science history.

1. M5 Forecasting (Walmart)

Hosted by the Makridakis Open Forecasting Center (MOFC). Evaluates zero-shot capabilities on 3,049 retail products across 10 Walmart stores.

• Accuracy Track: Point performance evaluated via WAPE and RMSSE over a 28-day boundary.
• Uncertainty Track: Predicting 9 distinct quantile boundaries. Chronos-2 natively emits sample trajectories, fitting the uncertainty profile out-of-the-box.

Kaggle File	Payload Target	Purpose
sales_train_evaluation.csv	target_series	Context: Daily sales safely windowed for attention limits.
sell_prices.csv	price_index	Elasticity: Weekly average prices per product/store.
calendar.csv	promo_flag	Events: Structural shocks (SNAP allowances, holidays) mapped to 0/1.

2. Corporación Favorita (Ecuador)

Secondary validation for Out-of-Distribution (OOD) generalization. Introduces hyper-volatile local inflation markers (daily oil prices) and complex regional Ecuadorian holidays mapped to our price_index and promo_flag fields. Proves the model can generalize zero-shot across distinct international locales.

---

System Architecture

Input Payload (TimeSeriesInputPayload)
  │
  ├─ If price_index=None & promo_flag=None 
  │   └── Route to Chronos-2 (amazon/chronos-2) -> Univariate Tensor Engine
  │
  └─ If price_index≠None or promo_flag≠None 
      └── Route to TimesFM XReg (google/timesfm-2.5) -> Covariate Tensor Engine
  
Output Extraction (Shape-Agnostic Median/Quantile Parser)
  │
  └── ForecastOutputPayload
      ├─ mean_prediction (List[float])
      ├─ p10_quantile / p90_quantile (List[float])
      ├─ confidence_score (Float [0.0, 1.0])
      └─ model_identifier (String)

---

Quick Start

1. Installation

Requires Python 3.10+.

git clone https://github.com/aragit/zero-shot-demand-foundation.git
cd zero-shot-demand-foundation
pip install -r requirements.txt

2. Download Datasets

# Download M5 Walmart dataset
python scripts/download_m5.py

# Download Corporación Favorita dataset (Ecuador)
python scripts/download_favorita.py

3. Run Evaluation (CLI)

# M5 → auto-routes to Chronos-2 (univariate)
python main.py --dataset m5

# Favorita → auto-routes to TimesFM XReg (multivariate)
python main.py --dataset favorita

# Custom horizon / backtest window
python main.py --dataset m5 --horizon 48 --window 256

4. Run as an MCP Server (Agentic AI)

python mcp_server.py

Claude Desktop, LangChain, and other MCP hosts will auto-discover the forecast_demand tool and parse the exact Pydantic schema required to interact with the neural engine.

---

Test Suite

This repository includes a robust, mocked test suite to validate the symbolic boundaries, routing logic, and mathematical risk evaluations without requiring heavy GPU inference.

pip install pytest pytest-mock
pytest tests/ -v

Tests cover: Pydantic shape validation, routing dispatch logic (Chronos vs. TimesFM), and MetricEvaluator (WAPE, RMSSE, Pinball Loss, CRPS).

---

Project Structure

zero-shot-demand-foundation/
├── configs/model_config.yaml       # Model identifiers and device mapping
├── data/                           # Dataset storage (Git-ignored)
├── scripts/
│   ├── download_m5.py              # Kaggle M5 downloader
│   └── download_favorita.py        # Kaggle Favorita downloader
├── src/
│   ├── models/forecaster.py        # ZeroShotForecastingEngine with router
│   ├── schemas/payloads.py         # Pydantic input/output contracts
│   └── utils/
│       ├── data_loader.py          # DemandDataEngine + FavoritaDataLoader
│       └── metrics.py              # WAPE, RMSSE, Pinball Loss, CRPS
├── tests/                          # Pytest suite
├── main.py                         # CLI evaluation entry point
├── mcp_server.py                   # MCP tool server implementation
└── requirements.txt                # Pruned production dependencies

---

Metrics Overview

Metric	Track	Description
WAPE	Accuracy	Weighted Absolute Percentage Error
RMSSE	Accuracy	Root Mean Squared Scaled Error (M5 standard)
Pinball Loss	Uncertainty	Quantile loss evaluated specifically at the 10th and 90th percentiles
CRPS	Uncertainty	Continuous Ranked Probability Score (discrete approximation)
Confidence Score	Uncertainty	1 - (p90 - p10) / median normalized spread indicator (1.0 = tight, 0.0 = extreme spread)

---

License

Distributed under the MIT License. See LICENSE for more information.