An end-to-end production-oriented MLOps platform for country risk prediction, combining macroeconomic data, machine learning, experiment tracking, model versioning, containerized inference, AWS SageMaker deployment, automated testing, and cloud observability.
- Project Overview
- Business Problem
- Project Objectives
- Solution Overview
- Architecture
- End-to-End ML Lifecycle
- Data Pipeline
- Feature Engineering
- Machine Learning Model
- Experiment Tracking with MLflow
- Model Serialization and Versioning
- Model Serving
- Docker and Containerization
- AWS Cloud Deployment
- SageMaker Endpoint
- Monitoring and Observability
- Testing and Quality Assurance
- CI/CD
- API Inference
- Feature Dictionary
- Project Structure
- Local Development
- Production Deployment Flow
- Current Production Status
- Roadmap
- Key MLOps Practices Demonstrated
- Author
MLOps Country Risk Prediction is an end-to-end machine learning engineering project designed to demonstrate how a data science model can be transformed into a reproducible, versioned, tested, containerized, deployed, and monitored production service.
The project goes beyond model development.
It implements the complete lifecycle:
Data
↓
Data Ingestion
↓
Data Validation
↓
Data Cleaning
↓
Feature Engineering
↓
Model Training
↓
Experiment Tracking
↓
Model Versioning
↓
Artifact Storage
↓
Containerization
↓
Cloud Deployment
↓
Real-Time Inference
↓
Monitoring
The system uses macroeconomic and governance-related indicators to estimate a country-level risk score.
The primary objective is not only predictive performance, but also reproducibility, reliability, traceability, deployment automation, and operational observability.
Country risk assessment is relevant to organizations involved in:
- International investment
- Financial analysis
- Credit risk assessment
- Portfolio allocation
- International expansion
- Sovereign risk analysis
- Economic research
- Strategic decision-making
Traditional country risk analysis often combines multiple economic, demographic, institutional, and governance indicators.
This project explores how these heterogeneous indicators can be transformed into a machine learning pipeline capable of producing a standardized country risk prediction.
The machine learning problem is formulated as a supervised regression task.
The model receives a set of macroeconomic and risk-related features and produces a continuous numerical risk prediction.
The project was designed around five major objectives.
The same data processing and training workflow should be executable repeatedly with predictable results.
The project incorporates:
- Data versioning
- Model versioning
- Experiment tracking
- Automated testing
- Containerization
- Cloud deployment
- Monitoring
- Infrastructure integration
Model development occurs independently from model serving.
The final model artifact is packaged and deployed through a dedicated inference environment.
The trained model is converted into a production artifact and exposed through an HTTP inference service.
The project intentionally covers the transition:
From notebook → reproducible pipeline → versioned model → container → cloud endpoint → monitored production service.
The architecture combines open economic data, Python-based machine learning, MLflow, DVC, Docker, and AWS.
┌─────────────────────┐
│ World Bank API │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Data Ingestion │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Data Validation │
│ & Data Cleaning │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Feature Engineering │
│ & Lag Generation │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Model Training │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ MLflow │
│ Experiment Tracking │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Model Artifact │
│ Versioning │
└──────────┬──────────┘
│
┌────────┴────────┐
▼ ▼
DVC + S3 MLflow
│
▼
┌───────────────┐
│ Docker Image │
└───────┬───────┘
│
▼
┌───────────────┐
│ AWS ECR │
└───────┬───────┘
│
▼
┌───────────────┐
│ AWS SageMaker │
│ Endpoint │
└───────┬───────┘
│
┌──────────┴──────────┐
▼ ▼
Single Inference Batch Inference
│ │
└──────────┬──────────┘
▼
┌───────────────┐
│ CloudWatch │
│ Monitoring │
└───────┬───────┘
│
▼
5XX Alarms
The project follows a structured ML lifecycle.
Macroeconomic indicators are retrieved from the World Bank API.
The ingestion layer is responsible for:
- API communication
- Data extraction
- Schema handling
- Country identification
- Time-period alignment
- Raw data persistence
Before entering the modeling pipeline, data is validated for:
- Expected columns
- Data types
- Missing values
- Numeric constraints
- Duplicate observations
- Structural consistency
This prevents malformed upstream data from silently propagating into the model.
The cleaning process handles:
- Missing observations
- Invalid values
- Data type normalization
- Temporal consistency
- Feature alignment
The objective is to create a stable dataset suitable for downstream feature engineering.
The pipeline generates model-ready features from the original economic indicators.
This includes temporal features such as lagged variables.
For example:
GDP(t)
│
└──► GDP(t-1)
Inflation(t)
│
└──► Inflation(t-1)
Lagged variables allow the model to incorporate historical information rather than relying exclusively on current-period observations.
The current model uses 12 numerical features.
| Feature | Description |
|---|---|
gdp_per_capita |
GDP per capita |
inflation |
Annual inflation rate |
life_expectancy |
Life expectancy at birth |
population |
Total population |
population_growth |
Annual population growth rate |
unemployment |
Unemployment rate |
exports |
Exports as a percentage of GDP |
gdp_lag1 |
Previous-period GDP per capita |
inflation_lag1 |
Previous-period inflation |
life_expectancy_lag1 |
Previous-period life expectancy |
economic_risk |
Composite economic risk indicator |
governance_risk |
Composite governance/institutional risk indicator |
All production inference inputs are numerical and validated before reaching the model.
The initial production pipeline uses a Random Forest regression model as the baseline estimator.
Random Forest was selected as a strong baseline because it:
- Handles nonlinear relationships
- Captures feature interactions
- Requires limited assumptions about functional form
- Works well with heterogeneous numerical features
- Provides a useful benchmark for future model comparison
The project is deliberately structured so that the model implementation can evolve without redesigning the surrounding MLOps infrastructure.
This allows future experimentation with:
- XGBoost
- LightGBM
- CatBoost
- Gradient Boosting
- Ensemble approaches
- Explainable ML techniques
The baseline Random Forest model achieved the following evaluation results:
| Metric | Score |
|---|---|
| MAE | 8.6462 |
| RMSE | 14.8474 |
| R² | 0.1907 |
The baseline provides a reproducible reference point for future modeling experiments.
The relatively modest R² also highlights an important aspect of the project:
The objective is not to present an artificially optimized model, but to establish a transparent and reproducible ML system where future models can be benchmarked against a known baseline.
This makes the repository suitable for continued experimentation and model improvement.
MLflow is used to track the machine learning lifecycle.
The project records model metadata including:
- Model version
- Parameters
- Evaluation metrics
- Model artifacts
- Python environment
- Dependency information
- Serialization format
The current production artifact metadata includes:
MLflow: 3.15.1
Python: 3.12.3
scikit-learn: 1.9.0
Serialization: skops
MLflow provides traceability between:
Experiment
↓
Training Run
↓
Model Artifact
↓
Model Version
↓
Deployment
This is critical for reproducibility and production governance.
Large model binaries are intentionally kept outside the Git repository.
The project uses:
- DVC for model/data versioning
- Amazon S3 for artifact storage
- MLflow for model metadata and lifecycle tracking
- skops for secure scikit-learn model serialization
The current production model artifact is approximately 100 MB.
The model is stored in S3 using a versioned structure:
s3://country-risk-prediction-mlops-models-2026/
└── models/
└── country-risk-prediction/
└── v7/
├── model.skops
├── MLmodel
└── environment metadata
This architecture keeps Git focused on source code while using dedicated storage systems for large ML artifacts.
The inference environment is containerized using Docker.
The SageMaker-specific image is defined through:
Dockerfile.sagemaker
The container includes:
- Python runtime
- Model artifact
- ML dependencies
- FastAPI
- Uvicorn
- Prediction logic
- Request validation
Containerization provides environment consistency across:
Development
↓
Testing
↓
Container Build
↓
AWS ECR
↓
SageMaker
This eliminates many environment-related inconsistencies between development and production.
The model is served through a custom FastAPI/Uvicorn inference server.
The application listens on:
Port 8080
The serving layer is responsible for:
- Receiving inference requests
- Validating payload structure
- Validating required features
- Converting input into the expected dataframe format
- Executing model inference
- Returning predictions
The service supports both:
- Single-record inference
- Batch inference
The inference endpoint accepts requests using a dataframe-records structure.
Example:
{
"dataframe_records": [
{
"gdp_per_capita": 15000.0,
"inflation": 3.0,
"life_expectancy": 75.0,
"population": 50000000.0,
"population_growth": 1.0,
"unemployment": 6.0,
"exports": 25.0,
"gdp_lag1": 14500.0,
"inflation_lag1": 3.2,
"life_expectancy_lag1": 74.8,
"economic_risk": 0.30,
"governance_risk": 0.25
}
]
}The same inference contract can be used locally and through the deployed SageMaker endpoint.
The production infrastructure is built around AWS managed services.
| Service | Purpose |
|---|---|
| Amazon S3 | ML artifact and model storage |
| AWS ECR | Docker image registry |
| Amazon SageMaker | Model hosting and inference |
| Amazon CloudWatch | Monitoring and operational observability |
| AWS IAM | Secure service permissions |
| AWS STS/OIDC | Secure CI/CD authentication |
The deployment process follows:
Source Code
↓
Docker Build
↓
Amazon ECR
↓
SageMaker Model
↓
Endpoint Configuration
↓
SageMaker Endpoint
↓
Inference Verification
↓
CloudWatch Monitoring
The current deployed model is:
country-risk-prediction-v7-v3
The SageMaker model uses a dedicated ECR container image and an IAM execution role.
The production deployment includes:
Model
↓
Container
↓
SageMaker Model
↓
Endpoint Configuration
↓
Real-Time Endpoint
This provides a production-style HTTPS inference interface suitable for real-time prediction requests.
Production observability is implemented through Amazon CloudWatch.
The endpoint exposes operational metrics including:
- Invocations
- Model latency
- Invocation latency
- 5XX errors
- Model errors
A dedicated alarm monitors endpoint failures.
Alarm:
country-risk-prediction-v7-v3-5xx
Metric:
Invocation5XXErrors
Statistic:
Sum
Threshold:
>= 1 error
Evaluation Period:
5 minutes
The current post-deployment status is:
Alarm State: OK
5XX Errors: 0
The monitoring layer demonstrates that deployment does not end when the endpoint becomes available.
The system must also be observable after deployment.
Testing is integrated throughout the project.
The test suite includes:
- Unit tests
- Functional tests
- Integration tests
- API validation tests
- Model inference tests
- AWS endpoint integration tests
Current test status:
65 tests passed
2 integration tests passed
Run the standard test suite:
pytest -qRun AWS integration tests:
pytest -m integration -qIntegration tests validate real communication with the deployed SageMaker endpoint.
This ensures that the system is tested not only at the function level, but also at the infrastructure integration level.
The repository is structured around a CI/CD-oriented development workflow.
The conceptual pipeline is:
Developer
│
▼
GitHub Pull Request
│
▼
Continuous Integration
│
├── Dependency validation
├── Import validation
├── DVC validation
├── Automated tests
└── Docker build
│
▼
Protected Main Branch
│
▼
Continuous Deployment
│
▼
GitHub OIDC
│
▼
AWS IAM Role
│
├───────────────┐
▼ ▼
S3 ECR
│ │
└───────┬───────┘
▼
SageMaker
│
▼
Verification
│
▼
CloudWatch
The architecture separates source control, testing, artifact management, container registry, deployment, and monitoring.
The project avoids embedding cloud credentials directly into application code.
AWS access is managed through IAM-based authentication and role-based permissions.
The production architecture therefore separates:
Application Code
+
Model Artifacts
+
Container Images
+
Cloud Permissions
This reduces the coupling between application logic and infrastructure credentials.
The use of versioned artifacts also improves reproducibility by allowing a deployed model to be traced back to a specific artifact version.
MLOps-Country-Risk-Prediction/
│
├── data/
│ ├── raw/
│ │ └── Raw World Bank API data
│ │
│ ├── processed/
│ │ └── Cleaned and engineered datasets
│ │
│ └── external/
│ └── Supplementary metadata
│
├── docker/
│ └── model/
│ ├── MLmodel
│ ├── serve.py
│ ├── requirements.txt
│ └── model.skops.dvc
│
├── notebooks/
│ └── Exploratory analysis and experiments
│
├── scripts/
│ ├── __init__.py
│ └── inference.py
│
├── src/
│ ├── api/
│ │ └── API utilities and validation
│ │
│ ├── data/
│ │ └── Data ingestion and validation
│ │
│ ├── features/
│ │ └── Feature engineering
│ │
│ ├── models/
│ │ └── Model training and promotion
│ │
│ ├── visualization/
│ │ └── Metrics and visualizations
│ │
│ ├── utils/
│ │ └── AWS and MLflow utilities
│ │
│ ├── config.py
│ └── main.py
│
├── tests/
│ ├── Unit tests
│ ├── Functional tests
│ └── Integration tests
│
├── Dockerfile.sagemaker
├── dvc.yaml
├── dvc.lock
├── pytest.ini
├── requirements.txt
└── README.md
git clone https://github.com/AnderCruz/MLOps-Country-Risk-Prediction.git
cd MLOps-Country-Risk-Predictionpython -m venv .venv
source .venv/bin/activatepython -m venv .venv
.venv\Scripts\activatepip install -r requirements.txtpython src/main.pypytest -qAWS credentials and access to the deployed endpoint are required.
pytest -m integration -qpython scripts/inference.pyThe project combines several mechanisms to improve reproducibility.
Git provides version control for:
- Python source code
- Configuration
- Tests
- Infrastructure definitions
- Pipeline definitions
DVC and Amazon S3 provide versioning for large ML artifacts.
MLflow tracks:
- Parameters
- Metrics
- Model versions
- Environment metadata
Docker provides a reproducible production runtime.
Together:
Git
+
DVC
+
MLflow
+
Docker
+
AWS
create a reproducible ML delivery workflow.
The complete deployment lifecycle can be summarized as:
1. Develop
│
▼
2. Validate
│
▼
3. Test
│
▼
4. Train
│
▼
5. Track with MLflow
│
▼
6. Version model with DVC
│
▼
7. Store artifact in S3
│
▼
8. Build Docker image
│
▼
9. Push image to ECR
│
▼
10. Register SageMaker model
│
▼
11. Deploy endpoint
│
▼
12. Execute inference tests
│
▼
13. Monitor with CloudWatch
This represents the central philosophy of the project:
A machine learning model is not finished when it achieves a good metric. It is finished when it can be reliably delivered, reproduced, served, monitored, and maintained.
| Component | Status |
|---|---|
| Data ingestion | ✅ Implemented |
| Data validation | ✅ Implemented |
| Feature engineering | ✅ Implemented |
| Model training | ✅ Implemented |
| MLflow tracking | ✅ Implemented |
| Model versioning | ✅ Implemented |
| DVC | ✅ Implemented |
| S3 artifact storage | ✅ Implemented |
| Docker containerization | ✅ Implemented |
| Amazon ECR | ✅ Implemented |
| SageMaker deployment | ✅ Implemented |
| Real-time inference | ✅ Operational |
| Batch inference support | ✅ Implemented |
| Automated testing | ✅ 65 tests passed |
| Integration testing | ✅ 2 tests passed |
| CloudWatch monitoring | ✅ Implemented |
| 5XX alarm | ✅ OK |
| Production endpoint | ✅ InService |
This project is intentionally broader than a traditional machine learning notebook.
It demonstrates practical experience across:
- Exploratory data analysis
- Feature engineering
- Regression modeling
- Model evaluation
- Time-dependent features
- Modular Python architecture
- Model serialization
- Inference services
- API validation
- Testing
- Reproducibility
- MLflow
- DVC
- Model versioning
- Artifact management
- Experiment tracking
- CI/CD
- Production deployment
- Monitoring
- Amazon S3
- Amazon ECR
- Amazon SageMaker
- Amazon CloudWatch
- AWS IAM
- OIDC-based authentication
- Git-based development
- Automated testing
- Docker
- Modular architecture
- Separation of concerns
- Production-oriented project structure
The project is designed to evolve beyond the baseline implementation.
- Benchmark XGBoost
- Benchmark LightGBM
- Benchmark CatBoost
- Hyperparameter optimization
- Cross-validation strategy
- Model selection framework
- SHAP integration
- Global feature importance
- Local prediction explanations
- Model interpretability reports
- Automated model promotion
- Model approval workflow
- Automated rollback
- Model registry governance
- Automated retraining
- Data drift detection
- Feature distribution monitoring
- Model performance monitoring
- Prediction drift monitoring
- Automated drift alerts
- Interactive Streamlit dashboard
- Country risk simulation interface
- Historical risk visualization
- Model explanation dashboard
- REST API documentation
The project demonstrates the following production-oriented principles:
The same pipeline can be executed repeatedly using versioned source code, data artifacts, model artifacts, and environments.
A production model can be traced through:
Model Version
↓
MLflow Metadata
↓
Artifact
↓
DVC
↓
S3
↓
Docker Image
↓
SageMaker Endpoint
The project separates:
- Data processing
- Feature engineering
- Model training
- Model serving
- Infrastructure
- Testing
- Monitoring
The model is not limited to experimentation.
It is exposed through a real cloud endpoint and monitored using AWS infrastructure.
The project contains a structured test suite covering both application logic and infrastructure integration.
The model is packaged as a Docker container and deployed through AWS managed services.
This project was developed to consolidate practical knowledge in:
- Machine Learning
- Data Science
- MLOps
- MLflow
- DVC
- Docker
- FastAPI
- AWS
- SageMaker
- ECR
- S3
- CloudWatch
- CI/CD
- Model serving
- Automated testing
- Production ML architecture
The central learning objective was to bridge the gap between:
"I trained a machine learning model."
and:
"I built and deployed a reproducible machine learning system."
Data Scientist | Machine Learning & Predictive Analytics | MLOps
Focused on building production-oriented machine learning systems combining:
- Data Science
- Machine Learning
- Deep Learning
- MLOps
- Cloud Computing
- Predictive Analytics
🐙 GitHub: https://github.com/AnderCruz
💼 LinkedIn: https://linkedin.com/in/anderjcruz
This repository is part of my Data Science and MLOps portfolio and represents a complete production-oriented machine learning workflow.
The project demonstrates that modern Data Science requires more than model development.
A successful ML solution must connect:
Business Problem
↓
Data
↓
Features
↓
Model
↓
Experimentation
↓
Versioning
↓
Testing
↓
Deployment
↓
Monitoring
↓
Continuous Improvement
This project implements that complete lifecycle.