Forecast Analytics Architecture

Status: ✅ Production Ready Namespace: src/ai/forecast Service: forecast-sidecar (Python/Prophet)

Overview

The Forecast Analytics module enables Jorvis to answer predictive questions like "What will sales look like next month?". It uses a dedicated Python microservice running Facebook Prophet, a robust additive regression model optimized for business time-series data.

Architecture

graph LR
    User["User Query"] --> Orchestrator["Graph Orchestrator"]
    Orchestrator --> ForecastNode["ForecastNode (NestJS)"]
    ForecastNode -- POST /forecast --> Sidecar["Forecast Sidecar (Python)"]
    Sidecar -- Prediction + Intervals --> ForecastNode
    ForecastNode --> Viz["VisualizationNode"]

Components

1. ForecastNode (src/ai/graph/nodes/forecast.node.ts):

   • Detects forecast intent.
   • Validates data suitability (minimum 10 points).
   • Calls the sidecar API.

2. Forecast Sidecar (deploy/forecast-sidecar/):

   • FastAPI service.
   • Prophet model engine.
   • Handles seasonality (daily, weekly, yearly) automatically.

API Contract

Generate Forecast

POST http://forecast-sidecar:8001/forecast

Request:

{
  "timestamps": ["2024-01-01", "2024-01-02", "2024-01-03"],
  "values": [150.5, 155.0, 152.3],
  "periods": 30,
  "confidence_interval": 0.95
}

Response:

{
  "success": true,
  "forecast": {
    "timestamps": ["2024-01-04", ...],
    "values": [160.2, ...],
    "lower": [155.0, ...],
    "upper": [165.5, ...]
  },
  "metrics": {
    "mape": 4.5,
    "rmse": 12.1
  }
}

Configuration

Usage Examples

User: "Predict revenue for the next 3 months based on 2024 data."

1. SQL Generation: Fetches daily revenue for 2024.
2. ForecastNode: Sends 365 data points to Sidecar.
3. Sidecar: Fits Prophet model, predicts 90 days.
4. Visualization: Line chart showing history (solid) + forecast (dashed) + confidence area.

Future Roadmap

1. Multi-Variate: Include external regressors (e.g., marketing spend).
2. Anomaly Detection: Flag historical points outside the confidence interval.
3. DB-Native ML: Support BigQuery ML for massive datasets.