Machine Learning β’ FastAPI β’ Streamlit β’ MySQL β’ Docker β’ RAG β’ Gemini AI
An end-to-end AI-powered credit risk platform that combines machine learning, real-time REST APIs, an interactive dashboard, persistent assessment history, document-based knowledge retrieval, and containerized deployment.
Developed by Fares Badran β’ 26 August 2026
CreditGuard AI is an end-to-end machine learning system designed to assess customer credit risk and estimate the probability of loan default.
The project goes beyond model training by integrating the complete ML application lifecycle:
- Data preprocessing
- Machine learning inference
- Credit risk scoring
- REST API serving
- Interactive web dashboard
- Customer assessment persistence
- Credit policy RAG assistant
- Dockerized multi-service deployment
The goal is to demonstrate how a machine learning model can evolve from an experimental notebook into a complete application architecture.
CreditGuard AI uses a trained Logistic Regression classification model to estimate a customer's probability of default.
The ML workflow includes:
- Missing-value imputation
- Numerical feature scaling
- Categorical feature encoding
- Class imbalance handling using SMOTE
- Hyperparameter tuning
- Probability-based risk assessment
- Persisted preprocessing and model artifacts
The trained model is exposed through a FastAPI backend that handles:
- Prediction requests
- Input validation
- Feature preprocessing
- Model inference
- Risk classification
- Database persistence
- Assessment history retrieval
- Model and service health information
Interactive API documentation is available through Swagger UI.
The project includes an interactive Streamlit interface for working with the complete system without manually sending API requests.
The dashboard provides an interface for:
- Customer information
- Credit information
- Risk assessment
- Prediction results
- Default probability
- Risk classification
- Previous assessment history
- AI-powered credit policy assistance
Credit assessments can be persisted in MySQL.
Stored assessment information includes fields such as:
- Customer name
- Date of birth
- Customer ID
- Nationality
- Default probability
- Prediction
- Risk level
- Assessment timestamp
This allows CreditGuard AI to behave like an application rather than a stateless prediction script.
CreditGuard AI also includes a Retrieval-Augmented Generation component backed by a credit-risk policy knowledge base.
The RAG layer is designed to answer policy-related questions by retrieving relevant information from the knowledge base before generating an answer.
Example questions include:
What factors are considered when assessing credit risk?
What is considered a high credit risk?
How should a high-risk loan application be handled?
What are the credit approval rules?
This separates two types of intelligence inside the platform:
Predictive AI β estimates credit/default risk.
Generative AI + RAG β answers questions about credit policy and procedures.
The application is containerized using Docker and orchestrated with Docker Compose.
The stack contains three main services:
| Service | Purpose | Port |
|---|---|---|
creditguard_streamlit |
Interactive frontend | 8501 |
creditguard_api |
FastAPI backend | 8000 |
creditguard_mysql |
MySQL database | 3307 β 3306 |
This provides an isolated and reproducible environment for the complete application stack.
ββββββββββββββββββββββββββββ
β CREDITGUARD AI β
β β
β Streamlit Dashboard β
ββββββββββββββ¬ββββββββββββββ
β
β HTTP / JSON
βΌ
ββββββββββββββββββββββββββββ
β FastAPI β
β REST Backend β
βββββββββ¬ββββββββββ¬βββββββββ
β β
Prediction β β Persistence
βΌ βΌ
ββββββββββββββββββ ββββββββββββββββββ
β ML ENGINE β β MySQL β
β β β β
β Logistic β β Assessment β
β Regression β β History β
βββββββββ¬βββββββββ ββββββββββββββββββ
β
βΌ
ββββββββββββββββββ
β Risk Decision β
β β
β LOW / MEDIUM / β
β HIGH β
ββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββ
β AI KNOWLEDGE LAYER β
β β
β Knowledge Base β Retrieval β Gemini β
β RAG Assistant β
βββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββ
β DOCKER COMPOSE β
β β
β Streamlit + FastAPI + MySQL Services β
βββββββββββββββββββββββββββββββββββββββββ
The prediction pipeline follows a structured preprocessing and inference workflow.
Raw Customer Data
β
βΌ
βββββββββββββββββββββββββ
β Input Validation β
ββββββββββββ¬βββββββββββββ
β
βΌ
βββββββββββββββββββββββββ
β Missing Value β
β Imputation β
ββββββββββββ¬βββββββββββββ
β
βββββββββββββββββββββββββββ
βΌ βΌ
βββββββββββββββββββββ βββββββββββββββββββββ
β Numerical Featuresβ βCategorical Featuresβ
βββββββββββ¬ββββββββββ βββββββββββ¬ββββββββββ
β β
βΌ βΌ
βββββββββββββββββββββ βββββββββββββββββββββ
β StandardScaler β β OneHotEncoder β
βββββββββββ¬ββββββββββ βββββββββββ¬ββββββββββ
β β
βββββββββββββββ¬ββββββββββββββ
βΌ
ββββββββββββββββββββ
β Prepared Feature β
β Vector β
ββββββββββ¬ββββββββββ
βΌ
ββββββββββββββββββββ
β Logistic β
β Regression β
ββββββββββ¬ββββββββββ
βΌ
ββββββββββββββββββββ
β Default β
β Probability β
ββββββββββ¬ββββββββββ
βΌ
ββββββββββββββββββββ
β Credit Risk β
β Classification β
ββββββββββββββββββββ
During training, SMOTE is used to help address class imbalance in the training data.
The Logistic Regression model achieved approximately:
| Metric | Score |
|---|---|
| Recall | 66.18% |
| F1 Score | 25.91% |
| ROC-AUC | 74.32% |
For credit-risk applications, evaluation should not rely only on accuracy because default datasets can be highly imbalanced.
Metrics such as Recall, F1 Score, ROC-AUC, and the Confusion Matrix provide more useful information about model behavior.
Important: This project is an educational/portfolio implementation and is not intended to make real-world lending decisions without further validation, governance, fairness testing, calibration, and regulatory review.
The application converts the predicted probability into a human-readable risk category.
| Default Probability | Risk Level |
|---|---|
< 40% |
π’ LOW |
40% β <70% |
π‘ MEDIUM |
β₯ 70% |
π΄ HIGH |
This makes the raw model probability easier to interpret inside the dashboard.
credit_risk_api/
β
βββ app.py
β βββ Streamlit application
β
βββ main.py
β βββ FastAPI backend
β
βββ logistic_regression_model.pkl
β βββ Trained Logistic Regression model
β
βββ numerical_features.pkl
βββ categorical_features.pkl
β βββ Feature definitions
β
βββ num_imputer.pkl
βββ cat_imputer.pkl
β βββ Missing-value preprocessing
β
βββ scaler.pkl
β βββ Numerical feature scaler
β
βββ encoder.pkl
β βββ Categorical feature encoder
β
βββ Dockerfile
β βββ Application container configuration
β
βββ docker-compose.yml
β βββ Multi-container orchestration
β
βββ requirements.txt
β βββ Python dependencies
β
βββ .dockerignore
β
βββ Screenshot 2026-07-08 025127.png
β
βββ CHAT/
β βββ CHAT.PY
β βββ credit_risk_loan_policy_knowledge_base.docx
β βββ .gitignore
β βββ .env
β
βββ README.md
.envfiles containing passwords or API keys must never be committed to a public repository.
Instead of performing model training every time the API starts, CreditGuard AI loads previously trained artifacts.
logistic_regression_model.pkl
β
βββ num_imputer.pkl
βββ cat_imputer.pkl
βββ scaler.pkl
βββ encoder.pkl
βββ numerical_features.pkl
βββ categorical_features.pkl
This keeps inference separate from training and allows the API to start with the trained model ready for prediction.
GET /healthUsed to inspect the status of the API and its dependencies.
POST /predictThe endpoint:
- Receives customer features.
- Validates the request.
- Applies preprocessing.
- Runs model inference.
- Calculates default probability.
- Determines the risk level.
- Stores assessment information when applicable.
- Returns the prediction to the client.
GET /assessmentsRetrieves previous credit-risk assessments stored in MySQL.
GET /model-infoProvides information about the loaded machine learning components.
For the Docker-based setup, install:
- Git
- Docker Desktop
Make sure Docker Desktop is running before starting the stack.
git clone <YOUR_REPOSITORY_URL>
cd credit_risk_apiCreate the required .env configuration locally.
Never publish real:
- Database passwords
- Gemini API keys
- Secret tokens
- Credentials
For a public repository, provide a safe template such as:
.env.example
Example structure:
DB_HOST=mysql
DB_PORT=3306
DB_NAME=credit_risk_db
DB_USER=root
DB_PASSWORD=your_password_here
GEMINI_API_KEY=your_api_key_heredocker compose up --buildOr start it in detached mode:
docker compose up -dDocker Compose starts the application services required by the platform.
Once the containers are running:
| Application | Address |
|---|---|
| π CreditGuard Dashboard | http://localhost:8501 |
| β‘ FastAPI | http://localhost:8000 |
| π Swagger API Docs | http://localhost:8000/docs |
| ποΈ MySQL Host Port | localhost:3307 |
Check running containers:
docker psExpected services:
creditguard_streamlit
creditguard_api
creditguard_mysql
Stop the complete stack:
docker compose downRestart:
docker compose up -dRebuild after dependency or Docker configuration changes:
docker compose up --buildCreditGuard AI uses MySQL to persist prediction results.
Conceptually, an assessment record contains:
Assessment
β
βββ Customer Information
β βββ Name
β βββ Date of Birth
β βββ Customer ID
β βββ Nationality
β
βββ ML Result
β βββ Default Probability
β βββ Prediction
β βββ Risk Level
β
βββ Timestamp
This enables historical assessment retrieval instead of losing predictions after each request.
The knowledge assistant follows a Retrieval-Augmented Generation workflow.
User Question
β
βΌ
βββββββββββββββββββββββ
β Credit Policy β
β Knowledge Base β
ββββββββββββ¬βββββββββββ
β
βΌ
βββββββββββββββββββββββ
β Semantic Retrieval β
ββββββββββββ¬βββββββββββ
β
βΌ
βββββββββββββββββββββββ
β Relevant Context β
ββββββββββββ¬βββββββββββ
β
βΌ
βββββββββββββββββββββββ
β Gemini β
β Generation Layer β
ββββββββββββ¬βββββββββββ
β
βΌ
Grounded Answer
The current knowledge assistant focuses on the supplied credit-policy knowledge base.
Questions about live customer assessment history belong to the database layer rather than the policy knowledge base.
FastAPI automatically exposes interactive Swagger documentation.
Start the project and visit:
http://localhost:8000/docs
From Swagger UI you can test endpoints such as:
GET /health
GET /model-info
POST /predict
GET /assessments
without requiring an external API testing application.
Sensitive configuration should never be committed to Git.
The repository should exclude:
.env
*.env
__pycache__/
*.pyc
.venv/
venv/If an API key or password is accidentally pushed to a public repository, it should be considered compromised and rotated.
Credit risk is a high-impact financial domain.
A production lending system requires significantly more controls than a portfolio ML application, including:
- Bias and fairness evaluation
- Explainability
- Probability calibration
- Data quality monitoring
- Model drift detection
- Audit trails
- Access control
- Model versioning
- Human review
- Security controls
- Regulatory and legal review
CreditGuard AI should therefore be treated as an educational and portfolio project, not a production lending decision engine.
Potential future improvements include:
- Cloud deployment
- CI/CD pipeline
- Automated model testing
- Model registry and versioning
- SHAP-based explainability
- Authentication and authorization
- Role-based access control
- Advanced monitoring
- Data/model drift detection
- Automated retraining pipeline
- Database migrations
- Hybrid RAG + database assistant
- Production secrets management
- HTTPS and custom domain
CreditGuard AI demonstrates practical experience across multiple areas of machine learning engineering:
Machine Learning
+
Data Preprocessing
+
Model Evaluation
+
REST API Development
+
Frontend Development
+
SQL Database Integration
+
Generative AI / RAG
+
Containerization
+
End-to-End System Integration
The project demonstrates the transition from:
βI trained a machine learning model.β
to:
βI built an application around a machine learning model.β
| Layer | Technology |
|---|---|
| Programming | Python |
| Data Processing | Pandas / NumPy |
| Machine Learning | scikit-learn |
| Imbalanced Learning | SMOTE |
| Backend | FastAPI |
| Validation | Pydantic |
| Frontend | Streamlit |
| Database | MySQL |
| Generative AI | Gemini |
| Knowledge Assistant | RAG |
| API Server | Uvicorn |
| Containerization | Docker |
| Orchestration | Docker Compose |
| Version Control | Git / GitHub |
Add screenshots of the running application here before publishing the repository.
Recommended screenshots:
If running individual components outside Docker, ensure their required dependencies and environment variables are configured correctly.
For the complete application, Docker Compose is the recommended local startup method:
docker compose up -dCheck status:
docker compose psView logs:
docker compose logsCreditGuard AI is developed for educational, demonstration, and portfolio purposes.
The model, risk thresholds, generated responses, and policy knowledge base should not be interpreted as financial advice or used as the sole basis for real lending, underwriting, or credit approval decisions.
Machine Learning & AI Developer
CreditGuard AI
End-to-End Machine Learning Project
Project Date: 26 August 2026
Built as a practical exploration of Machine Learning Engineering, APIs, databases, Generative AI, and containerized application development.