isaacOluwafemiOg/sa_cpi_forecaster

production-grade project to forecast south african cpi # South Africa CPI Nowcasting: Production-Grade ML System ## 📌 Executive Summary This project is an end-to-end Machine Learning system (accessible via web link) that provides Nowcasts for South Africa’s Consumer Price Index (CPI) across 11 economic categories. Originally a 3rd Place winning solution for the RMB CPI Nowcasting Challenge on Zindi, it has been evolved into a production-grade, decoupled application. The system autonomously ingests monthly data from Statistics South Africa, executes a feature engineering pipeline, retrains optimized CatBoost models, and serves forecasts via a FastAPI backend and Streamlit dashboard. ## 🏗 System Architecture The project follows a Decoupled Service Architecture and a Medallion Data Design, ensuring scalability and high availability. ```mermaid graph TD subgraph "External Data" StatsSA[Stats SA Excel Portal] end subgraph "MLOps Orchestration (GitHub Actions)" Ingest[Ingestion Script] --> Clean[Cleaning: Bronze to Silver] Clean --> FE[Feature Engineering: Silver to Gold] FE --> Train[Model Training: Optuna + CatBoost] Train --> Infer[Recursive Inference] end subgraph "Cloud Infrastructure (GCP)" Registry[Artifact Registry] --> CloudRunAPI[FastAPI Service: Cloud Run] CloudRunUI[Streamlit Dashboard: Cloud Run] --> CloudRunAPI end StatsSA -.-> Ingest Infer --> Registry ``` ## 🛠 Tech Stack - **Languages** : Python 3.11 - **Modeling**: CatBoost Regressor, Optuna (Hyperparameter Tuning), Scikit-Learn - **API**: FastAPI, Uvicorn, Pydantic - **Dashboard**: Streamlit, Plotly Express - **DevOps**: Docker, GitHub Actions (CI/CD) - **Cloud**: Google Cloud Platform (Artifact Registry, Cloud Run, Secret Manager) ## 🔬 The Science: Modeling Strategy 1. **Feature Engineering (Gold Layer)** **Auto-Regressive Lags**: 15 months of historical values. **Vectorized Trend Analysis**: Efficiently calculating slope and momentum features over sliding windows. **Cyclical Encoding**: Sine/Cosine transformations of months to ca …