isaacOluwafemiOg/sa_cpi_forecaster
Domain:
socioeconomicRecord type:
model
Creator:
isa
Host:
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 …