Skip to content

About

End-to-End AI-powered Credit Risk Assessment Platform built with Machine Learning, FastAPI, Streamlit, MySQL, Docker, and RAG.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

πŸ›‘οΈ CreditGuard AI

Intelligent End-to-End Credit Risk Assessment Platform

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.


Python FastAPI Streamlit MySQL Docker scikit-learn


Developed by Fares Badran β€’ 26 August 2026


πŸ“Œ Overview

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.


✨ Core Features

🧠 Machine Learning Risk Engine

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

⚑ FastAPI REST Backend

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.


πŸ“Š Streamlit Dashboard

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

πŸ—„οΈ MySQL Persistence

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.


πŸ€– AI / RAG Knowledge Assistant

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.


🐳 Dockerized Architecture

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.


πŸ—οΈ System Architecture

                         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                         β”‚      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  β•‘
              β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•

🧠 Machine Learning Pipeline

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.


πŸ“ˆ Model Performance

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.


⚠️ Risk Classification

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.


πŸ“‚ Project Structure

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

.env files containing passwords or API keys must never be committed to a public repository.


πŸ”¬ Model Artifacts

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.


🌐 REST API

Health Check

GET /health

Used to inspect the status of the API and its dependencies.


Credit Risk Prediction

POST /predict

The endpoint:

  1. Receives customer features.
  2. Validates the request.
  3. Applies preprocessing.
  4. Runs model inference.
  5. Calculates default probability.
  6. Determines the risk level.
  7. Stores assessment information when applicable.
  8. Returns the prediction to the client.

Assessment History

GET /assessments

Retrieves previous credit-risk assessments stored in MySQL.


Model Information

GET /model-info

Provides information about the loaded machine learning components.


πŸš€ Quick Start

Prerequisites

For the Docker-based setup, install:

  • Git
  • Docker Desktop

Make sure Docker Desktop is running before starting the stack.


1. Clone the Repository

git clone <YOUR_REPOSITORY_URL>
cd credit_risk_api

2. Configure Environment Variables

Create 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_here

3. Start CreditGuard AI

docker compose up --build

Or start it in detached mode:

docker compose up -d

Docker Compose starts the application services required by the platform.


πŸ”— Local Services

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

🐳 Docker Services

Check running containers:

docker ps

Expected services:

creditguard_streamlit
creditguard_api
creditguard_mysql

Stop the complete stack:

docker compose down

Restart:

docker compose up -d

Rebuild after dependency or Docker configuration changes:

docker compose up --build

πŸ’Ύ Database Layer

CreditGuard 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.


πŸ€– RAG Architecture

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.


πŸ§ͺ API Testing

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.


πŸ” Security

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.


πŸ›‘οΈ Responsible AI

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.


πŸ—ΊοΈ Roadmap

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

πŸ’‘ What This Project Demonstrates

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.”


🧰 Technology Stack

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

πŸ“Έ Screenshots

Add screenshots of the running application here before publishing the repository.

Recommended screenshots:

CreditGuard AI Dashboard

Credit Risk Prediction

RAG Knowledge Assistant

FastAPI Swagger Documentation

Docker Services


βš™οΈ Development Notes

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 -d

Check status:

docker compose ps

View logs:

docker compose logs

βš–οΈ Disclaimer

CreditGuard 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.


πŸ‘¨β€πŸ’» Author

Fares Badran

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.


⭐ If you find CreditGuard AI interesting, consider starring the repository.

Built with Python β€’ FastAPI β€’ Streamlit β€’ MySQL β€’ Docker β€’ Machine Learning β€’ RAG

About

End-to-End AI-powered Credit Risk Assessment Platform built with Machine Learning, FastAPI, Streamlit, MySQL, Docker, and RAG.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages