Deploy from GitHub Actions

Dockerfile

@@ -0,0 +1,27 @@
+# Use Python 3.10 slim image based on Linux Debian Bookworm distribution (suitable for ML workloads)
+FROM python:3.10-slim-bookworm
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Install curl (to download GeoLite2), tar (to unzip it) & dos2unix (to fix Windows line endings)
+RUN apt-get update && apt-get install -y --no-install-recommends curl tar dos2unix && rm -rf /var/lib/apt/lists/*
+
+# Copy the requirements file and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application source code
+COPY ./src ./src
+COPY ./backend ./backend
+COPY ./frontend ./frontend
+COPY ./start.sh .
+
+# Fix start script line endings and make it executable
+RUN dos2unix ./start.sh && chmod +x ./start.sh
+
+# Expose Gradio port
+EXPOSE 7860  
+
+# Command to run the application
+CMD ["./start.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jens Bender
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+- The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

README.md

@@ -0,0 +1,140 @@
+---
+title: Loan Default Prediction
+subtitle: Submit customer application data to predict loan default
+emoji: 💰
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+models:
+  - JensBender/loan-default-prediction-pipeline
+tags:
+  - finance
+  - credit-risk
+  - loan-default
+  - tabular-data
+  - scikit-learn
+  - random-forest
+  - gradio
+  - fastapi
+  - docker
+---
+
+## 🏦 Loan Default Prediction App
+A web application that predicts loan default based on customer application data, helping financial institutions make data-driven lending decisions.  
+Built with `Gradio`, `FastAPI`, and a `scikit-learn` Random Forest model trained on over 250,000 loan applications.
+
+### How to Use 
+1.  **Fill in Form**: Enter applicant details such as age, income, and experience.
+2.  **Click Predict**: The app will process your input and return a "Default" or "No Default" prediction along with probabilities.
+3.  **Interpret Responsibly**: Use the prediction to support decision making, do **not** use for fully automated decisions without human oversight.  
+
+### Use via API
+You can also send requests directly to the FastAPI backend for programmatic access. This is useful for integrating the model into other applications or systems.
+
+Example API usage with Python's `requests` library:
+```python
+import requests 
+
+# Create example applicant data (JSON payload)
+applicant_data = {
+    "income": 300000,
+    "age": 30,
+    "experience": 3,
+    "married": "single",
+    "house_ownership": "rented",
+    "car_ownership": "no",
+    "profession": "artist",
+    "city": "sikar",
+    "state": "rajasthan",
+    "current_job_yrs": 3,
+    "current_house_yrs": 11,
+}
+
+# API request to FastAPI predict endpoint on Hugging Face Spaces
+prediction_api_url = "https://jensbender-loan-default-prediction-app.hf.space/api/predict"
+response = requests.post(prediction_api_url, json=applicant_data)
+
+# Check if request was successful
+response.raise_for_status()
+
+# Extract prediction and probability of default
+prediction_response = response.json()
+prediction_result = prediction_response["results"][0]
+prediction = prediction_result["prediction"]
+default_probability = prediction_result["probabilities"]["Default"]
+
+# Show results
+print(f"Probability of default: {default_probability * 100:.1f}% (threshold: 29.0%)")
+print(f"Prediction: {prediction}")
+```
+
+### How It Works
+1. **Gradio Frontend (UI Layer)**  
+    - Provides a clean and simple form for data entry.  
+    - Sends form data as JSON to the backend API.  
+    - Displays prediction results and probabilities in real time.
+2. **FastAPI Backend (API Layer)**  
+    - Receives requests from the `Gradio` frontend or direct API requests.  
+    - Loads the pre-trained pipeline from the [Hugging Face Hub](https://huggingface.co/JensBender/loan-default-prediction-pipeline).  
+    - Validates and passes data through the pipeline, and applies the decision threshold.  
+    - Returns JSON responses containing predictions and probabilities.
+3. **ML Pipeline (Model Layer)**  
+   - Implements a `scikit-learn` pipeline with a Random Forest Classifier model and preprocessing.  
+   - Performs feature engineering, scaling, and encoding.  
+   - Outputs predicted probabilities for both classes ("Default" and "No Default").
+4. **Deployment Environment**
+    - Packaged as a single `Docker` container.  
+    - Runs seamlessly on Hugging Face Spaces using the Docker SDK.  
+
+### Model Performance
+The Random Forest model achieved an **AUC-PR of 0.59** on the test set. The most influential features are income, age, and state default rate (derived via feature engineering).
+
+**Classification Report (Test)**
+|                        | Precision | Recall | F1-Score | Samples |
+|:-----------------------|:----------|:-------|:---------|:--------|
+| Class 0: Non-Defaulter | 0.97      | 0.90   | 0.93     | 22,122  |
+| Class 1: Defaulter     | 0.51      | 0.79   | 0.62     | 3,078   |
+| Accuracy               |           |        | 0.88     | 25,200  |
+| Macro Avg              | 0.74      | 0.84   | 0.78     | 25,200  |
+| Weighted Avg           | 0.91      | 0.88   | 0.89     | 25,200  |
+
+### Resources
+| Component | Description | Link |
+|------------|--------------|------|
+| **Source Code** | Full project repository with training, evaluation, and deployment scripts | [GitHub](https://github.com/JensBender/loan-default-prediction) |
+| **Model Pipeline** | Pre-trained `scikit-learn` pipeline with Random Forest Classifier and preprocessing | [Hugging Face Hub](https://huggingface.co/JensBender/loan-default-prediction-pipeline) |
+| **Web App** | Live, interactive demo with Gradio frontend and FastAPI backend | [Hugging Face Spaces](https://huggingface.co/spaces/JensBender/loan-default-prediction-app) |
+
+### Responsible Use
+The model and by extension this web app and API are intended to be used as a tool to support credit risk assessment. They can be integrated into decision-making workflows to provide a quantitative measure of default risk for loan applicants.
+
+This model is **not** intended for:
+- Fully automated lending decisions without human oversight. The model's predictions should not be the sole factor in any financial decision.
+- Evaluating applicants from demographic, geographic, or socioeconomic backgrounds not represented in the training data.
+- Use in a production environment without rigorous, ongoing validation and fairness audits. 
+
+### Bias, Risks, and Limitations  
+The model was trained on historical data that may carry biases related to socioeconomic status, geography, or other demographic factors, potentially leading to unfair predictions for certain groups. The model can be overconfident on misclassified edge cases, assigning high probabilities to incorrect predictions. Confidence scores should not be relied upon without additional scrutiny.
+
+**Recommendations**  
+- **Human in the Loop:** Always use this model as part of a broader decision-making framework that includes human oversight.
+- **Fairness and Bias Audits:** Before deploying this model in a production environment, conduct thorough fairness and bias analyses to ensure it performs equally across different demographic groups.
+- **Model Monitoring:** Continuously monitor the model's performance and predictions to detect and mitigate any performance degradation or emerging biases.
+
+### License
+The source code for this web app on Hugging Face Spaces and the source code of the overall project on [GitHub](https://github.com/JensBender/loan-default-prediction) is licensed under the [MIT License](LICENSE). The model pipeline is licensed under [Apache-2.0](https://huggingface.co/JensBender/loan-default-prediction-pipeline/resolve/main/LICENSE).
+
+### Citation
+If you use this model or app in your work, please cite it as follows:
+```bibtex
+@misc{bender_loan_default_prediction_2025,
+  author       = {Bender, Jens},
+  title        = {Loan Default Prediction Pipeline},
+  year         = {2025},
+  publisher    = {Hugging Face},
+  url          = {https://huggingface.co/JensBender/loan-default-prediction-pipeline},
+  note         = {Version 1.0. A scikit-learn Random Forest pipeline for predicting loan defaults. Trained on 252,000 loan applications. Source code available at \url{https://github.com/JensBender/loan-default-prediction}. Licensed under Apache-2.0.}
+}
+```

backend/__init__.py

@@ -0,0 +1 @@
+# This file marks the directory as a Python package.

backend/app.py

@@ -0,0 +1,349 @@
+# --- Imports ---
+# Standard library imports
+from pathlib import Path
+from typing import Any
+import logging
+import logging.config
+import json
+import uuid
+import time
+from datetime import datetime, timezone
+
+# Third-party library imports
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import RedirectResponse
+from sklearn.pipeline import Pipeline
+import gradio as gr
+import pandas as pd
+import numpy as np
+import joblib
+from huggingface_hub import hf_hub_download
+import geoip2.database
+from geoip2.errors import AddressNotFoundError
+
+# Local imports
+from backend.schemas import (
+    PipelineInput,
+    PredictionEnum,
+    PredictedProbabilities,
+    PredictionResult,
+    PredictionResponse    
+)
+from frontend.app import gradio_app
+from src.custom_transformers import (
+    MissingValueChecker, 
+    MissingValueStandardizer, 
+    RobustSimpleImputer,
+    SnakeCaseFormatter, 
+    BooleanColumnTransformer, 
+    JobStabilityTransformer, 
+    CityTierTransformer, 
+    StateDefaultRateTargetEncoder,
+    RobustStandardScaler,
+    RobustOneHotEncoder,
+    RobustOrdinalEncoder,
+    FeatureSelector
+)
+from src.utils import get_root_directory
+
+# --- Logging ---
+# Create logs directory if it doesn't exist
+log_dir = Path("logs")
+log_dir.mkdir(exist_ok=True)
+
+# Define logging configuration
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        },
+        "monitoring": {
+            "format": "%(message)s",
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+            "stream": "ext://sys.stdout",  # write to Python standard output stream, which goes to Docker container's standard output, which goes to Hugging Face host server, which goes to Hugging Face Space Logs tab
+        },
+        "monitoring_file": {
+            "class": "logging.handlers.RotatingFileHandler",
+            "formatter": "monitoring",
+            "filename": str(log_dir / "prediction_logs.jsonl"),  # JSON Lines format: one JSON object per line
+            "maxBytes": 10485760,  # 10 MB
+            "backupCount": 3,  # will create prediction_logs.jsonl.1, .2, and .3 for max 4 log files (40 MB), then overwrite
+        },
+    },
+    "loggers": {
+        "": {  # root logger for general logs
+            "handlers": ["console"],
+            "level": "INFO",
+        },
+        "monitoring": {  # prediction records logger for model monitoring 
+            "handlers": ["monitoring_file"],
+            "level": "INFO",
+            "propagate": False,
+        },
+    },
+}
+
+# Apply logging configuration
+logging.config.dictConfig(LOGGING_CONFIG)
+
+# Get loggers
+logger = logging.getLogger(__name__)
+monitoring_logger = logging.getLogger("monitoring")
+
+
+# --- Helper Functions ---
+# Function to get batch-level metadata for logging
+def get_batch_metadata(
+    pipeline_input_dict_ls: list[dict[str, Any]], 
+    request: Request, 
+    geoip_reader: geoip2.database.Reader | None
+) -> dict[str, Any]:    
+    # Get user agent and IP from frontend
+    user_agent = pipeline_input_dict_ls[0].get("user_agent", None)  # use first input in list of inputs
+    if user_agent is None:  # fall back for direct API request to backend
+        user_agent = request.headers.get("user-agent", "unknown")  # get from request headers of FastAPI backend
+    client_ip = pipeline_input_dict_ls[0].get("client_ip", None)  
+    if client_ip is None:
+        x_forwarded_for = request.headers.get("x-forwarded-for")  # single str with one or more comma-separated IP addresses
+        client_ip = x_forwarded_for.split(",")[0].strip() if x_forwarded_for else request.client.host  # first IP is client IP address
+    
+    # Get client country from IP address
+    client_country = "unknown"
+    if geoip_reader and client_ip:
+        try:
+            response = geoip_reader.country(client_ip)
+            client_country = response.country.name
+        except AddressNotFoundError:  # this occurs for unknown or private or reserved IPs (e.g., 127.0.0.1)
+            logger.debug("IP address not found in GeoLite2 country database. Likely a private or local address.")
+
+    # Create dictionary with batch-level metadata
+    metadata = {
+        "batch_id": str(uuid.uuid4()),
+        "batch_size": len(pipeline_input_dict_ls),
+        "batch_timestamp": datetime.now(timezone.utc).isoformat(),
+        "pipeline_version": PIPELINE_VERSION_TAG,
+        "client_country": client_country,
+        "user_agent": user_agent,
+    } 
+
+    return metadata
+
+
+# Function to load a scikit-learn pipeline from the local machine
+def load_pipeline_from_local(path: str | Path) -> Pipeline:
+    # Input type validation
+    if not isinstance(path, (str, Path)):
+        raise TypeError(f"Error when loading pipeline: 'path' must be a string or Path object, got {type(path).__name__}")
+
+    # Get path as both string and Path object
+    if isinstance(path, Path):
+        path_str = str(path)
+    else:  # isinstance(path, str)
+        path_str = path 
+        path = Path(path)
+
+    # Ensure file exists
+    if not path.exists():
+        raise FileNotFoundError(f"Error when loading pipeline: File not found at '{path_str}'")
+    
+    # Load pipeline 
+    try:
+        logger.info(f"Loading pipeline from '{path_str}'...")
+        pipeline = joblib.load(path_str)
+        logger.info("Successfully loaded pipeline.")
+    except Exception as e:
+        raise RuntimeError(f"Error when loading pipeline from '{path_str}'") from e
+    
+    # Ensure loaded object is a scikit-learn Pipeline
+    if not isinstance(pipeline, Pipeline):
+        raise TypeError("Error when loading pipeline: Loaded object is not a scikit-learn Pipeline")
+
+    # Ensure pipeline has .predict_proba() method
+    if not hasattr(pipeline, "predict_proba"):
+        raise TypeError("Error when loading pipeline: Loaded pipeline does not have a .predict_proba() method")
+
+    return pipeline
+
+
+# Function to download and load a scikit-learn pipeline from a Hugging Face Hub repository
+def load_pipeline_from_huggingface(repo_id: str, filename: str, revision: str) -> Pipeline:
+    try:
+        # .hf_hub_download() downloads the pipeline file and returns its local file path (inside the Docker container)
+        # if the pipeline file was already downloaded, it will use the cached pipeline that is already stored inside the Docker container 
+        logger.info(
+            f"Downloading pipeline '{filename}' with tag '{revision}' from Hugging Face Hub repo '{repo_id}'. "
+            "If already cached, will use local copy."
+        )
+        pipeline_path = hf_hub_download(repo_id=repo_id, filename=filename, revision=revision)
+
+        # Load pipeline from file inside the Docker container
+        pipeline = load_pipeline_from_local(pipeline_path)
+
+        return pipeline
+
+    except Exception as e:
+        raise RuntimeError(f"Error loading pipeline '{filename}' from Hugging Face Hub repository '{repo_id}': {e}") from e 
+
+
+# --- Geolocation Database ---
+# Load the GeoLite2 country database to log client country for model monitoring (download database from https://www.maxmind.com to the "geoip_db/" directory)
+GEO_DB_PATH = Path("geoip_db/GeoLite2-Country.mmdb")
+try:
+    geoip_reader = geoip2.database.Reader(GEO_DB_PATH)
+    logger.info(f"Successfully loaded GeoLite2 country database from '{GEO_DB_PATH}'")
+except FileNotFoundError:
+    logger.error(f"GeoLite2 country database not found at '{GEO_DB_PATH}'. Client country will not be logged. Download the database from https://www.maxmind.com.")
+    geoip_reader = None
+
+# --- ML Pipeline ---
+# Load loan default prediction pipeline (including data preprocessing and Random Forest Classifier model) from Hugging Face Hub
+PIPELINE_VERSION_TAG = "v1.0"
+pipeline = load_pipeline_from_huggingface(
+    repo_id="JensBender/loan-default-prediction-pipeline", 
+    filename="loan_default_rf_pipeline.joblib",
+    revision=PIPELINE_VERSION_TAG  
+)
+
+# Load pipeline from local machine (use for local setup without Hugging Face Hub)
+# root_dir = get_root_directory()  # get path to root directory
+# pipeline_path = root_dir / "models" / "loan_default_rf_pipeline.joblib"  # get path to pipeline file
+# pipeline = load_pipeline_from_local(pipeline_path)
+
+# --- API ---
+# Create FastAPI app
+fastapi_app = FastAPI(title="Loan Default Prediction API")
+
+# Prediction endpoint 
+@fastapi_app.post("/api/predict", response_model=PredictionResponse)
+def predict(pipeline_input: PipelineInput | list[PipelineInput], request: Request) -> PredictionResponse:  # JSON object -> PipelineInput | JSON array -> list[PipelineInput]
+    batch_metadata = None   
+    pipeline_input_dict_ls = None
+    try:
+        # Standardize input
+        if isinstance(pipeline_input, list):
+            if pipeline_input == []:  # handle empty batch input
+                return PredictionResponse(results=[])
+            pipeline_input_dict_ls = [input.model_dump() for input in pipeline_input]
+        else:  # isinstance(pipeline_input, PipelineInput)
+            pipeline_input_dict_ls = [pipeline_input.model_dump()]
+        
+        # Get batch metadata for logging
+        batch_metadata = get_batch_metadata(pipeline_input_dict_ls, request, geoip_reader)
+
+        # Remove "client_ip" and "user_agent" from pipeline input
+        pipeline_input_cleaned = [
+            {k: v for k, v in d.items() if k not in {"client_ip", "user_agent"}} 
+            for d in pipeline_input_dict_ls
+        ]
+
+        # Create DataFrame
+        pipeline_input_df: pd.DataFrame = pd.DataFrame(pipeline_input_cleaned)
+
+        # Use pipeline to batch predict probabilities (and measure latency)
+        start_time = time.perf_counter()  # use .perf_counter() for latency measurement and .time() for timestamps
+        predicted_probabilities: np.ndarray = pipeline.predict_proba(pipeline_input_df)  
+        pipeline_prediction_latency_ms = round((time.perf_counter() - start_time) * 1000)  # rounded to milliseconds
+
+        # Apply optimized threshold to convert probabilities to binary predictions
+        optimized_threshold: float = 0.29  # see threshold optimization in training script "loan_default_prediction.ipynb"
+        predictions: np.ndarray = (predicted_probabilities[:, 1] >= optimized_threshold)  # bool 1d-array based on class 1 "Default"
+
+        # Add latency to batch metadata for logging
+        batch_metadata.update({
+            "batch_latency_ms": pipeline_prediction_latency_ms,
+            "avg_prediction_latency_ms": round(pipeline_prediction_latency_ms / len(pipeline_input_dict_ls)),
+        })
+
+        # --- Create prediction response --- 
+        results: list[PredictionResult] = []
+        # Iterate over each prediction
+        for i, (pred, pred_proba) in enumerate(zip(predictions, predicted_probabilities)):
+            # Create prediction result
+            prediction_enum = PredictionEnum.DEFAULT if pred else PredictionEnum.NO_DEFAULT       
+            prediction_result = PredictionResult(
+                prediction=prediction_enum,
+                probabilities=PredictedProbabilities(
+                    default=float(pred_proba[1]),
+                    no_default=float(pred_proba[0])
+                )
+            )
+            results.append(prediction_result)
+
+            # Log single prediction record for model monitoring (including batch metadata)
+            prediction_monitoring_record = {
+                **batch_metadata,
+                "prediction_id": str(uuid.uuid4()),
+                "inputs": pipeline_input_cleaned[i],
+                "prediction": prediction_enum.value,
+                "probabilities": {
+                    "default": float(pred_proba[1]),
+                    "no_default": float(pred_proba[0])
+                },
+            }
+            monitoring_logger.info(json.dumps(prediction_monitoring_record))  # converts record to JSON string for log
+
+        return PredictionResponse(results=results)
+
+    except Exception as e:
+        # Log error to console
+        logger.error("Error during predict: %s", e, exc_info=True)
+
+        # Log prediction error record to file for model monitoring (including batch metadata)
+        if pipeline_input_dict_ls:  
+            if batch_metadata is None:  # error before .get_batch_metadata()
+                batch_metadata = {
+                    "batch_id": str(uuid.uuid4()),
+                    "batch_size": len(pipeline_input_dict_ls),
+                    "batch_timestamp": datetime.now(timezone.utc).isoformat(),
+                    "pipeline_version": PIPELINE_VERSION_TAG,
+                    "client_country": None,
+                    "user_agent": None
+                } 
+            # Iterate over each input in batch
+            for input in pipeline_input_dict_ls:
+                prediction_monitoring_record = {
+                    **batch_metadata,
+                    "prediction_id": str(uuid.uuid4()),
+                    "inputs": input,
+                    "prediction": None,
+                    "probabilities": None,
+                    "error_message": str(e)
+                }
+                monitoring_logger.error(json.dumps(prediction_monitoring_record))
+        else:
+            prediction_monitoring_record = {
+                "batch_id": str(uuid.uuid4()),
+                "batch_size": None,
+                "batch_timestamp": datetime.now(timezone.utc).isoformat(),
+                "pipeline_version": PIPELINE_VERSION_TAG,
+                "client_country": None,
+                "user_agent": None,
+                "prediction_id": str(uuid.uuid4()),
+                "inputs": None,
+                "prediction": None,
+                "probabilities": None,
+                "error_message": str(e)
+            }
+            monitoring_logger.error(json.dumps(prediction_monitoring_record))
+
+        raise HTTPException(status_code=500, detail="Internal server error during loan default prediction")
+
+# Mount Gradio frontend onto FastAPI backend
+app = gr.mount_gradio_app(
+    fastapi_app, 
+    gradio_app, 
+    path="/gradio",  # at "/gradio" not "/" due to known Gradio bug (redirect loop)  
+    show_api=False  # disable Gradio's auto-generated API
+)  
+
+# Home route redirects to Gradio UI 
+@app.get("/")
+def root():
+    return RedirectResponse(url="/gradio/")

backend/schemas.py

@@ -0,0 +1,104 @@
+# --- Imports ---
+# Standard library imports
+from enum import Enum
+from typing import List, Annotated
+import math
+
+# Third-party library imports
+from pydantic import BaseModel, Field, field_validator, model_validator, computed_field
+
+# Local imports
+from src.global_constants import (
+    MARRIED_LABELS,
+    HOUSE_OWNERSHIP_LABELS,
+    CAR_OWNERSHIP_LABELS,
+    PROFESSION_LABELS,
+    CITY_LABELS,
+    STATE_LABELS
+)
+
+# --- Constants ---
+# Input constraints (for Pydantic data model)
+INCOME_CONSTRAINTS = Field(strict=True, ge=0)
+AGE_CONSTRAINTS = Field(strict=True, ge=21, le=79)
+EXPERIENCE_CONSTRAINTS = Field(strict=True, ge=0, le=20)
+CURRENT_JOB_YRS_CONSTRAINTS = Field(strict=True, ge=0, le=14)
+CURRENT_HOUSE_YRS_CONSTRAINTS = Field(strict=True, ge=10, le=14)
+
+# --- Custom Data Types ---
+# Annotate and combine existing types with custom constraints (for Pydantic data model)
+Income = Annotated[int, INCOME_CONSTRAINTS] | Annotated[float, INCOME_CONSTRAINTS]
+Age = Annotated[int, AGE_CONSTRAINTS] | Annotated[float, AGE_CONSTRAINTS]
+Experience = Annotated[int, EXPERIENCE_CONSTRAINTS] | Annotated[float, EXPERIENCE_CONSTRAINTS]
+CurrentJobYrs =  Annotated[int, CURRENT_JOB_YRS_CONSTRAINTS] | Annotated[float, CURRENT_JOB_YRS_CONSTRAINTS]
+CurrentHouseYrs = Annotated[int, CURRENT_HOUSE_YRS_CONSTRAINTS] | Annotated[float, CURRENT_HOUSE_YRS_CONSTRAINTS]
+
+# --- Enums ---
+# Custom Enum classes for string inputs based on global constants (for Pydantic data model)
+MarriedEnum = Enum("MarriedEnum", {label.upper(): label for label in MARRIED_LABELS}, type=str)
+HouseOwnershipEnum = Enum("HouseOwnershipEnum", {label.upper(): label for label in HOUSE_OWNERSHIP_LABELS}, type=str)
+CarOwnershipEnum = Enum("CarOwnershipEnum", {label.upper(): label for label in CAR_OWNERSHIP_LABELS}, type=str)
+ProfessionEnum = Enum("ProfessionEnum", {label.upper(): label for label in PROFESSION_LABELS}, type=str)
+CityEnum = Enum("CityEnum", {label.upper(): label for label in CITY_LABELS}, type=str)
+StateEnum = Enum("StateEnum", {label.upper(): label for label in STATE_LABELS}, type=str)
+
+
+# Enum for possible prediction strings
+class PredictionEnum(str, Enum):
+    DEFAULT = "Default"
+    NO_DEFAULT = "No Default"
+  
+    
+# --- Pydantic Data Models ---
+# Pipeline input model
+class PipelineInput(BaseModel):
+    income: Income
+    age: Age
+    experience: Experience
+    married: MarriedEnum | None = None 
+    house_ownership: HouseOwnershipEnum | None = None 
+    car_ownership: CarOwnershipEnum | None = None 
+    profession: ProfessionEnum  
+    city: CityEnum 
+    state: StateEnum 
+    current_job_yrs: CurrentJobYrs
+    current_house_yrs: CurrentHouseYrs
+    client_ip: str | None = None
+    user_agent: str | None = None
+
+    @field_validator("income", "age", "experience", "current_job_yrs", "current_house_yrs")
+    def convert_float_to_int(cls, value: float | int) -> int:
+        if isinstance(value, float):
+            return int(round(value))
+        return value
+
+
+# Predicted probabilities model
+class PredictedProbabilities(BaseModel):
+    default: float = Field(..., ge=0.0, le=1.0, serialization_alias="Default")
+    no_default: float = Field(..., ge=0.0, le=1.0, serialization_alias="No Default")
+
+    @field_validator("default", "no_default")
+    def round_to_3_decimals(cls, value: float) -> float:
+        return round(value, 3)
+
+    @model_validator(mode="after")  # happens after rounding
+    def check_probabilities_sum_to_one(self) -> "PredictedProbabilities":
+        if not math.isclose(self.default + self.no_default, 1.0, abs_tol=0.002):
+            raise ValueError("Probabilities must sum to 1.0")
+        return self
+
+
+# Prediction result model
+class PredictionResult(BaseModel):
+    prediction: PredictionEnum 
+    probabilities: PredictedProbabilities
+
+
+# Prediction response model
+class PredictionResponse(BaseModel):
+    results: List[PredictionResult] = Field(strict=True)
+
+    @computed_field
+    def n_predictions(self) -> int:
+        return len(self.results)

frontend/__init__.py

@@ -0,0 +1 @@
+# This file marks the "app" directory as a Python package.

frontend/app.py

@@ -0,0 +1,269 @@
+# --- Imports ---
+# Standard library imports
+import re
+import logging
+from typing import Any
+
+# Third-party library imports
+import gradio as gr
+import requests
+from requests.exceptions import ConnectionError, Timeout, RequestException
+
+# Local imports
+from src.global_constants import (
+    MARRIED_LABELS,
+    CAR_OWNERSHIP_LABELS,
+    HOUSE_OWNERSHIP_LABELS,
+    PROFESSION_LABELS,
+    CITY_LABELS,
+    STATE_LABELS
+)
+
+# --- Logger ---
+# Setup a structured logger for the frontend
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# --- Constants ---
+# Format categorical string labels (snake_case) for display in UI
+MARRIED_DISPLAY_LABELS = [label.title() for label in MARRIED_LABELS]
+CAR_OWNERSHIP_DISPLAY_LABELS = [label.title() for label in CAR_OWNERSHIP_LABELS]
+HOUSE_OWNERSHIP_DISPLAY_LABELS = [label.replace("norent_noown", "Neither Rented Nor Owned").title() for label in HOUSE_OWNERSHIP_LABELS]
+PROFESSION_DISPLAY_LABELS = [label.replace("_", " ").title() for label in PROFESSION_LABELS]
+CITY_DISPLAY_LABELS = [label.replace("_", " ").title() for label in CITY_LABELS]
+STATE_DISPLAY_LABELS = [label.replace("_", " ").title() for label in STATE_LABELS]
+
+
+# --- Input Preprocessing Functions ---
+# Format a string in snake_case (return non-string unchanged)
+def format_snake_case(value: Any) -> Any:
+    if isinstance(value, str):
+        # Remove leading/trailing whitespace, convert to lowercase, and replace single or multiple hyphens, forward slashes, and inner whitespaces with a single underscore
+        return re.sub(r"[-/\s]+", "_", value.strip().lower())
+    return value  # return non-string unchanged
+
+
+# Format all string values in a dictionary in snake_case
+def format_snake_case_in_dict(inputs: dict[str, Any]) -> dict[str, Any]:
+    return {key: format_snake_case(value) for key, value in inputs.items()}
+
+
+# Format "house_ownership" label as expected by API backend
+def format_house_ownership(display_label: Any) -> Any:
+    if isinstance(display_label, str):
+        return display_label.replace("neither_rented_nor_owned", "norent_noown")
+    return display_label  # return non-string unchanged
+
+
+# --- Error Handling ---
+# Map internal input field names (snake_case) to user-friendly error messages
+field_to_error_map = {
+    "age": "Age: Enter a number between 21 and 79.",
+    "married": "Married/Single: Select 'Married' or 'Single'",
+    "income": "Income: Enter a number that is 0 or greater.",
+    "car_ownership": "Car Ownership: Select 'Yes' or 'No'.",
+    "house_ownership": "House Ownership: Select 'Rented', 'Owned', or 'Neither Rented Nor Owned'.",
+    "current_house_yrs": "Current House Years: Enter a number between 10 and 14.",
+    "city": "City: Select a city from the list.",
+    "state": "State: Select a state from the list.",
+    "profession": "Profession: Select a profession from the list.",
+    "experience": "Experience: Enter a number between 0 and 20.",
+    "current_job_yrs": "Current Job Years: Enter a number between 0 and 14.",
+}
+
+
+# Function to format Pydantic validation error from FastAPI backend into a user-friendly message for Gradio frontend 
+def _format_validation_error(error_detail: dict) -> str:
+    error_msg = "Input Error! Please check your inputs and try again.\n"
+    try:
+        # Parse the Pydantic error format to create an error message with information about each invalid field
+        all_errors = error_detail["detail"]
+        for field in field_to_error_map:
+            if any(field in error["loc"] for error in all_errors):
+                error_msg += f"{field_to_error_map.get(field)}\n"
+        return error_msg
+    except Exception as e:
+        # Fallback to generic error message without details if Pydantic validation error has unexpected format 
+        logger.warning("Failed to parse validation error from backend: %s", e, exc_info=True)
+        return error_msg
+
+
+# --- Function to Predict Loan Default for Gradio UI ---
+def predict_loan_default(
+    age: int | float, 
+    married: str, 
+    income: int | float, 
+    car_ownership: str, 
+    house_ownership: str, 
+    current_house_yrs: int | float, 
+    city: str, 
+    state: str, 
+    profession: str, 
+    experience: int | float, 
+    current_job_yrs: int | float,
+    gr_request: gr.Request 
+) -> tuple[str, dict[str, float]] | tuple[str, str]:
+    try:
+        # Get the end-user's IP address, prioritizing the x-forwarded-for header with fallback
+        x_forwarded_for = gr_request.headers.get("x-forwarded-for")
+        client_ip = x_forwarded_for.split(",")[0].strip() if x_forwarded_for else gr_request.client.host
+
+        # --- Input preprocessing ---
+        # Create inputs dictionary 
+        inputs = {
+            "income": income, 
+            "age": age,
+            "experience": experience,
+            "married": married,
+            "house_ownership": house_ownership,
+            "car_ownership": car_ownership,
+            "profession": profession,
+            "city": city,
+            "state": state,
+            "current_job_yrs": current_job_yrs,
+            "current_house_yrs": current_house_yrs,
+            "client_ip": client_ip,
+            "user_agent": gr_request.headers.get("user-agent", "unknown")
+        }
+
+        # Format string values in snake_case
+        inputs = format_snake_case_in_dict(inputs)
+
+        # Format "house_ownership" label as expected by API backend 
+        inputs["house_ownership"] = format_house_ownership(inputs["house_ownership"])
+        
+        # --- Post request ---  
+        # Predict loan default via post request to FastAPI backend 
+        response = requests.post(
+            "http://127.0.0.1:7860/api/predict", 
+            json=inputs, 
+            timeout=(3, 60)  # 3s connect timeout, 60s read timeout (receive first byte of response)
+        ) 
+
+        # --- Error handling ---
+        # Handle HTTP errors
+        if response.status_code == 422:
+            error_detail = response.json()
+            logger.warning("Received 422 validation error from backend: %s", error_detail) 
+            error_message = _format_validation_error(error_detail)
+            return error_message, "" 
+
+        # Raise error for other bad status codes (4xx or 5xx)
+        response.raise_for_status()
+
+        # --- Response parsing ---
+        # Get prediction and probabilities from HTTP response for Gradio output
+        try:
+            prediction_response = response.json()
+            prediction_result = prediction_response["results"][0]
+            prediction = prediction_result["prediction"]
+            probabilities = prediction_result["probabilities"]
+
+            # Data validation for Gradio rendering
+            if not isinstance(prediction, str):
+                raise TypeError(f"'prediction' used in gr.Textbox expects str, got {type(prediction).__name__}.")
+            if not isinstance(probabilities, dict):
+                raise TypeError(f"'probabilities' used in gr.Label expects dict, got {type(probabilities).__name__}.")
+            if not probabilities:
+                raise ValueError("'probabilities' dict cannot be empty.")
+            if not all(isinstance(key, str) for key in probabilities.keys()):
+                raise TypeError("'probabilities' dict keys must be strings.")
+            if not all(isinstance(value, (int, float)) and 0 <= value <= 1 for value in probabilities.values()):
+                raise TypeError("'probabilities' dict values must be numbers between 0 and 1.")
+
+            return prediction, probabilities
+        # Handle response parsing errors
+        except (KeyError, IndexError, TypeError, ValueError):
+            logger.error("Failed to parse prediction response from backend.", exc_info=True)
+            return "Prediction Response Error", "The prediction service returned an invalid prediction format."
+
+    except ConnectionError:
+        logger.error("Connection to backend failed.", exc_info=True)
+        return "Connection Error", "Could not connect to the prediction service. Please ensure the backend is running and try again."
+    except Timeout:
+        logger.error("Request to backend timed out.", exc_info=True)
+        return "Timeout Error", "The request to the prediction service timed out. The service may be busy or slow. Please try again later."
+    except RequestException:  # catches other frontend-to-backend communication errors
+        logger.error("HTTP error while trying to communicate with backend.", exc_info=True)
+        return "Communication Error", "There was a problem communicating with the prediction service. Please try again later."
+    except Exception:
+        logger.exception("Unexpected error in the frontend.")
+        return "Error", f"An unexpected error has occurred. Please verify your inputs or try again later."
+
+
+# --- Gradio App UI ---
+# Custom CSS 
+custom_css = """
+.narrow-centered-column {
+    max-width: 700px; 
+    width: 100%; 
+    margin: 0 auto; 
+}
+#predict-button-wrapper {
+    max-width: 250px;
+    margin: 0 auto;
+}
+#prediction-text textarea {font-size: 1.8em; font-weight: bold; text-align: center;}
+#pred-proba-label {margin-top: -15px;}
+#markdown-note {margin-top: -13px;}
+"""
+
+# Create Gradio app UI using Blocks
+with gr.Blocks(css=custom_css) as gradio_app:
+    # Title and description
+    gr.Markdown(
+        """
+        <h1 style='text-align:center'>Loan Default Prediction</h1>
+        <p style='text-align:center'>Submit the customer application data to receive an automated loan default prediction powered by machine learning.</p>
+        """
+    )
+
+    # Inputs
+    with gr.Group():
+        with gr.Row():
+            age = gr.Number(label="Age", value="")
+            married = gr.Dropdown(label="Married/Single", choices=MARRIED_DISPLAY_LABELS, value=None)
+            income = gr.Number(label="Income", value="")
+        with gr.Row():
+            car_ownership = gr.Dropdown(label="Car Ownership", choices=CAR_OWNERSHIP_DISPLAY_LABELS, value=None)
+            house_ownership = gr.Dropdown(label="House Ownership", choices=HOUSE_OWNERSHIP_DISPLAY_LABELS, value=None)
+            current_house_yrs = gr.Slider(label="Current House Years", minimum=10, maximum=14, step=1)
+        with gr.Row():
+            city = gr.Dropdown(label="City", choices=CITY_DISPLAY_LABELS, value=None)
+            state = gr.Dropdown(label="State", choices=STATE_DISPLAY_LABELS, value=None)
+            profession = gr.Dropdown(label="Profession", choices=PROFESSION_DISPLAY_LABELS, value=None)
+        with gr.Row():
+            experience = gr.Slider(label="Experience", minimum=0, maximum=20, step=1)
+            current_job_yrs = gr.Slider(label="Current Job Years", minimum=0, maximum=14, step=1)
+            gr.Markdown("")  # empty space for layout
+
+    # Predict button 
+    with gr.Column(elem_id="predict-button-wrapper"):
+        predict = gr.Button("Predict", elem_id="predict-button")
+    
+    # Outputs
+    with gr.Column(elem_classes="narrow-centered-column"):
+        prediction_text = gr.Textbox(placeholder="Prediction Result", show_label=False, container=False, elem_id="prediction-text")   
+        pred_proba = gr.Label(show_label=False, show_heading=False, elem_id="pred-proba-label")
+        gr.Markdown(
+            "<small>Note: Prediction uses an optimized decision threshold of 0.29 "
+            "(predicts 'Default' if probability ≥ 29%, otherwise 'No Default').</small>",
+            elem_id="markdown-note"
+        )
+
+    # Predict button click event
+    predict.click(
+        predict_loan_default,
+        inputs=[
+            age, married, income, car_ownership, house_ownership, current_house_yrs, 
+            city, state, profession, experience, current_job_yrs
+        ],
+        outputs=[prediction_text, pred_proba]
+    )
+
+# Launch Gradio app
+if __name__ == "__main__":
+    gradio_app.launch()

requirements.txt

@@ -0,0 +1,17 @@
+# Backend
+fastapi==0.115.12
+pydantic==2.11.9
+uvicorn==0.34.2
+joblib==1.4.2 
+huggingface-hub==0.35.0
+geoip2==5.1.0
+
+# Frontend
+gradio==5.29.0
+httpx==0.28.1
+requests==2.32.5
+
+# Shared
+numpy==2.2.1
+pandas==2.2.3
+scikit-learn==1.6.0

src/__init__.py

@@ -0,0 +1 @@
+# This file marks the directory as a Python package.

src/custom_transformers.py

@@ -0,0 +1,596 @@
+# Imports
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.impute import SimpleImputer
+from sklearn.preprocessing import StandardScaler, OneHotEncoder, OrdinalEncoder
+from sklearn.utils.validation import check_is_fitted
+import pandas as pd
+import numpy as np
+
+
+# --- Custom error classes --- 
+# For missing values in critical columns of the X input DataFrame (in MissingValueChecker)
+class MissingValueError(ValueError):
+    pass
+
+# For mistmatch between expected and actual columns in X input DataFrame because of missing columns, unexpected columns, or wrong column order 
+class ColumnMismatchError(ValueError):
+    pass
+
+# For invalid categorical labels (in BooleanColumnTransformer)
+class CategoricalLabelError(ValueError):
+    pass
+
+
+# --- Custom transformer classes for data preprocessing pipeline ---
+# Check missing values 
+class MissingValueChecker(BaseEstimator, TransformerMixin):
+    def __init__(self, critical_features, non_critical_features):
+        # Validate input data type
+        if not isinstance(critical_features, list):
+            raise TypeError("'critical_features' must be a list of column names.")
+        if not isinstance(non_critical_features, list):
+            raise TypeError("'non_critical_features' must be a list of column names.")
+
+        # Validate input value
+        if not critical_features:
+            raise ValueError("'critical_features' cannot be an empty list. It must specify the names of the critical features.")
+        if not non_critical_features:
+            raise ValueError("'non_critical_features' cannot be an empty list. It must specify the names of the non-critical features.")
+
+        self.critical_features = critical_features
+        self.non_critical_features = non_critical_features
+    
+    def _validate_input(self, X):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")          
+        
+        # Ensure input DataFrame contains all required columns
+        input_columns = set(X.columns)
+        required_columns = set(self.critical_features + self.non_critical_features)
+        missing_columns = required_columns - input_columns 
+        if missing_columns:
+            raise ColumnMismatchError(f"Input X is missing the following columns: {', '.join(missing_columns)}.")
+
+        # Ensure input DataFrame doesn't contain any unexpected columns
+        unexpected_columns = input_columns - required_columns
+        if unexpected_columns:
+            raise ColumnMismatchError(f"Input X contains the following columns that are neither defined in 'critical_features' nor 'non_critical_features: {', '.join(unexpected_columns)}.")
+
+    def _check_missing_values(self, X):
+        # --- Critical features ---
+        # Calculate total number of missing values  
+        n_missing_total_critical = X[self.critical_features].isnull().sum().sum()
+        # Calculate number of rows with missing values  
+        n_missing_rows_critical = X[self.critical_features].isnull().any(axis=1).sum()
+        # Create dictionary with number of missing values by column 
+        n_missing_by_column_critical = X[self.critical_features].isnull().sum().to_dict()
+        # Raise error  
+        if n_missing_total_critical > 0:
+            values = "value" if n_missing_total_critical == 1 else "values"
+            rows = "row" if n_missing_rows_critical == 1 else "rows"
+            raise MissingValueError(
+                f"{n_missing_total_critical} missing {values} found in critical features "
+                f"across {n_missing_rows_critical} {rows}. Please provide missing {values}.\n"
+                f"Missing values by column: {n_missing_by_column_critical}"
+            )
+
+        # --- Non-critical features ---
+        # Calculate total number of missing values 
+        n_missing_total_noncritical = X[self.non_critical_features].isnull().sum().sum()        
+        # Calculate number of rows with missing values 
+        n_missing_rows_noncritical = X[self.non_critical_features].isnull().any(axis=1).sum()
+        # Create dictionary with number of missing values by column 
+        n_missing_by_column_noncritical = X[self.non_critical_features].isnull().sum().to_dict()
+        # Display warning message
+        if n_missing_total_noncritical > 0:
+            values = "value" if n_missing_total_noncritical == 1 else "values"
+            rows = "row" if n_missing_rows_noncritical == 1 else "rows"
+            print(
+                f"Warning: {n_missing_total_noncritical} missing {values} found in non-critical features "
+                f"across {n_missing_rows_noncritical} {rows}. Missing {values} will be imputed.\n"
+                f"Missing values by column: {n_missing_by_column_noncritical}"
+            )
+            
+    def fit(self, X, y=None):
+        # Validate input 
+        self._validate_input(X)  
+
+        # Check missing values
+        self._check_missing_values(X)
+
+        # Raise MissingValueError if a non-critical feature has only missing values
+        for non_critical_feature in self.non_critical_features:
+            if X[non_critical_feature].isnull().all():
+                raise MissingValueError(f"'{non_critical_feature}' cannot be only missing values. Please ensure at least one non-missing value.")
+
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+
+        return self 
+
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input 
+        self._validate_input(X)    
+        
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+        
+        # Check missing values
+        self._check_missing_values(X)
+
+        return X
+
+
+# Standardize missing values
+class MissingValueStandardizer(BaseEstimator, TransformerMixin):
+    def fit(self, X, y=None):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+               
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+
+        return self
+    
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+            
+        # Convert all missing value types (None, np.nan, pd.NA, etc.) to np.nan
+        return X.fillna(value=np.nan)
+
+
+# A wrapper for SimpleImputer to passthrough empty DataFrames during .transform() instead of raising a ValueError (SimpleImputer default behavior)
+class RobustSimpleImputer(SimpleImputer):
+    def transform(self, X):
+        if X.empty:
+            return X
+        else:
+            return super().transform(X)
+
+
+# Format categorical labels in snake_case
+class SnakeCaseFormatter(BaseEstimator, TransformerMixin):
+    def __init__(self, columns=None):
+        if not isinstance(columns, list) and columns is not None:
+            raise TypeError("'columns' must be a list of column names or None. If None, all columns will be used.")
+
+        # Validate input value
+        if columns == []:
+            raise ValueError("'columns' cannot be an empty list. It must specify the column names for snake case formatting.")
+
+        self.columns = columns
+    
+    def fit(self, X, y=None):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+
+        # Determine columns to be transformed (all if none provided)
+        if self.columns is None:
+            self.columns_ = X.columns.tolist()
+        else:
+            self.columns_ = self.columns
+            # Ensure input DataFrame contains all required columns
+            missing_columns = set(self.columns_) - set(X.columns)
+            if missing_columns:
+                raise ColumnMismatchError(f"Input X is missing the following columns: {', '.join(missing_columns)}.")
+        
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+                    
+        return self  
+
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+
+        # Ensure input DataFrame contains all required columns
+        missing_columns = set(self.columns_) - set(X.columns)
+        if missing_columns:
+            raise ColumnMismatchError(f"Input X is missing the following columns: {', '.join(missing_columns)}.")
+
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+
+        X_transformed = X.copy()
+        
+        for column in self.columns_:
+            X_transformed[column] = X_transformed[column].apply(
+                lambda categorical_label: (
+                    categorical_label
+                    .strip()  # Remove leading/trailing spaces
+                    .lower()  # Convert to lowercase
+                    .replace("-", "_")  # Replace hyphens with "_"
+                    .replace("/", "_")  # Replace slashes with "_"
+                    .replace(" ", "_")  # Replace spaces with "_"
+                    if isinstance(categorical_label, str) else categorical_label
+                )
+            )
+
+        return X_transformed
+
+
+# Convert binary categorical columns to boolean columns 
+class BooleanColumnTransformer(BaseEstimator, TransformerMixin):  
+    def __init__(self, boolean_column_mappings):
+        # Validate input data type
+        if not isinstance(boolean_column_mappings, dict):
+            raise TypeError("'boolean_column_mappings' must be a dictionary specifying the mappings.")
+
+        # Validate input value
+        if not boolean_column_mappings:
+            raise ValueError("'boolean_column_mappings' cannot be an empty dictionary. It must specify the the mappings.")
+
+        # Iterate all columns in "boolean_column_mappings"
+        for column, mapping in boolean_column_mappings.items():
+            # Ensure the mapping of the current column is also a dictionary
+            if not isinstance(mapping, dict):
+                raise TypeError(f"The mapping for '{column}' must be a dictionary.")
+            
+            # Ensure the values of the current mapping are boolean
+            if not all(isinstance(value, bool) for value in mapping.values()):
+                raise ValueError(f"All values in the mapping for '{column}' must be boolean (True or False).")
+
+        self.boolean_column_mappings = boolean_column_mappings 
+            
+    def _validate_input(self, X):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+        
+        # Ensure input DataFrame contains all required binary columns (from "boolean_column_mappings")
+        input_columns = set(X.columns)
+        required_columns = set(self.boolean_column_mappings.keys())
+        missing_columns = required_columns - input_columns 
+        if missing_columns:
+            raise ColumnMismatchError(f"Input X is missing the following columns: {', '.join(missing_columns)}.")
+
+        # Ensure all binary columns have no missing values
+        for column in required_columns:
+            if X[column].isna().any():
+                raise MissingValueError(f"'{column}' column cannot contain missing values.")
+
+        # Ensure all binary columns have valid data types (str, int, float, bool)
+        for column in required_columns:
+            if X[column].apply(lambda x: not isinstance(x, (str, int, float, bool))).any():
+                raise TypeError(f"All values in '{column}' column must be str, int, float or bool.")
+
+        # Ensure all binary columns contains only known labels (from "boolean_column_mappings")
+        for column, mapping in self.boolean_column_mappings.items():            
+            known_labels = set(mapping.keys())
+            input_labels = set(X[column].unique())
+            unknown_labels = input_labels- known_labels
+            if unknown_labels:
+                raise CategoricalLabelError(f"'{column}' column contains unknown labels that are not in 'boolean_column_mappings': {', '.join(unknown_labels)}.")
+
+    def fit(self, X, y=None):  
+        # Validate input
+        self._validate_input(X)
+        
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+        
+        return self  
+
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input
+        self._validate_input(X)
+                    
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+
+        X_transformed = X.copy()
+        for column, mapping in self.boolean_column_mappings.items():
+            X_transformed[column] = X_transformed[column].map(mapping)
+
+        return X_transformed
+
+
+# Derive job stability from profession 
+class JobStabilityTransformer(BaseEstimator, TransformerMixin):
+    def __init__(self, job_stability_map):
+        # Validate input data type
+        if not isinstance(job_stability_map, dict):
+            raise TypeError("'job_stability_map' must be a dictionary specifying the mappings from 'profession' to 'job_stability'.")
+        
+        # Validate input value
+        if not job_stability_map:
+            raise ValueError("'job_stability_map' cannot be an empty dictionary. It must specify the mappings from 'profession' to 'job_stability'.")
+
+        self.job_stability_map = job_stability_map 
+
+    def _validate_input(self, X):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+
+        # Ensure input DataFrame contains the required "profession" column
+        if "profession" not in X.columns:
+            raise ColumnMismatchError("Input X is missing the following columns: profession.")
+
+        # Ensure "profession" column has no missing values
+        if X["profession"].isna().any():
+            raise MissingValueError("'profession' column cannot contain missing values.")
+
+        # Ensure all values in "profession" column are strings
+        if X["profession"].apply(lambda x: not isinstance(x, str)).any():
+            raise TypeError("All values in 'profession' column must be strings.")
+
+        # Ensure "profession" column contains only known professions (from "job_stability_map")
+        known_professions = set(self.job_stability_map.keys())
+        input_professions = set(X["profession"].unique())
+        unknown_professions = input_professions - known_professions
+        if unknown_professions:
+            raise CategoricalLabelError(f"'profession' column contains unknown professions: {', '.join(unknown_professions)}.")
+
+    def fit(self, X, y=None):
+        # Validate input
+        self._validate_input(X)
+
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+        
+        return self  
+
+    def transform(self, X):  
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input
+        self._validate_input(X)
+        
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+       
+        # Create job stability column by mapping professions to job stability tiers (default to "moderate" for unknown professions)
+        X_transformed = X.copy()
+        X_transformed["job_stability"] = X_transformed["profession"].map(self.job_stability_map)
+
+        return X_transformed
+
+
+# Derive city tier from city
+class CityTierTransformer(BaseEstimator, TransformerMixin):
+    def __init__(self, city_tier_map):
+        if not isinstance(city_tier_map, dict):
+            raise TypeError("'city_tier_map' must be a dictionary specifying the mappings from 'city' to 'city_tier'.")
+
+        # Validate input value
+        if not city_tier_map:
+            raise ValueError("'city_tier_map' cannot be an empty dictionary. It must specify the mappings from 'city' to 'city_tier'.")
+
+        self.city_tier_map = city_tier_map 
+
+    def _validate_input(self, X):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")           
+
+        # Ensure input DataFrame contains the required "city" column
+        if "city" not in X.columns:
+            raise ColumnMismatchError("Input X is missing the following columns: city.")
+        
+        # Ensure "city" column has no missing values
+        if X["city"].isna().any():
+            raise MissingValueError("'city' column cannot contain missing values.")
+
+        # Ensure all values in "city" column are strings
+        if X["city"].apply(lambda x: not isinstance(x, str)).any():
+            raise TypeError("All values in 'city' column must be strings.")
+
+        # Ensure "city" column contains only known cities (from "city_tier_map")
+        known_cities = set(self.city_tier_map.keys())
+        input_cities = set(X["city"].unique())
+        unknown_cities = input_cities - known_cities
+        if unknown_cities:
+            raise CategoricalLabelError(f"'city' column contains unknown cities: {', '.join(unknown_cities)}.")
+    
+    def fit(self, X, y=None):
+        # Validate input
+        self._validate_input(X) 
+            
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+        
+        return self  
+
+    def transform(self, X):        
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+        
+        # Validate input
+        self._validate_input(X)   
+        
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+
+        # Create city tier column by mapping cities to city tiers
+        X_transformed = X.copy()
+        X_transformed["city_tier"] = X_transformed["city"].map(self.city_tier_map)
+        
+        return X_transformed
+
+
+# Target encoding of state default rate 
+class StateDefaultRateTargetEncoder(BaseEstimator, TransformerMixin):
+    def _validate_X_input(self, X):
+        # Ensure X input is a DataFrame
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+        
+        # Ensure DataFrame contains the required "state" column
+        if "state" not in X.columns:
+            raise ColumnMismatchError("Input X is missing the following columns: state.")
+        
+        # Ensure "state" column has no missing values
+        if X["state"].isna().any():
+            raise MissingValueError("'state' column cannot contain missing values.")
+        
+        # Ensure all values in "state" column are strings
+        if X["state"].apply(lambda x: not isinstance(x, str)).any():
+            raise TypeError("All values in 'state' column must be strings.")
+                
+    def fit(self, X, y):
+        # Validate X input
+        self._validate_X_input(X)
+
+        # Ensure y input is a pandas Series
+        if not isinstance(y, pd.Series):
+            raise TypeError("Input y must be a pandas Series.")   
+        
+        # Ensure y has no missing values
+        if y.isna().any():
+            raise MissingValueError("Input y cannot contain missing values.")
+
+        # Ensure y is integer type
+        if not pd.api.types.is_integer_dtype(y):
+            raise TypeError("Input y must be integer type.")
+
+        # Ensure all y values are 0 or 1 
+        if not y.isin([0, 1]).all():
+            raise ValueError("All y values must be 0 (no default) or 1 (default).")
+                
+        # Ensure X and y have the same index
+        if not X.index.equals(y.index):
+            raise ValueError("Input X and y must have the same index.")
+
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+       
+        # Calculate default rate by state
+        df = X.copy()
+        df["default"] = y
+        self.default_rate_by_state_ = df.groupby("state")["default"].mean()
+        
+        return self  
+
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+
+        # Validate X input
+        self._validate_X_input(X)
+
+        # Ensure "state" column contains only known states seen during .fit()
+        known_states = set(self.default_rate_by_state_.index)
+        input_states = set(X["state"].unique())
+        unknown_states = input_states - known_states
+        if unknown_states:
+            raise CategoricalLabelError(f"'state' column contains unknown states: {', '.join(unknown_states)}.")
+      
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+
+        # Create state default rate column by mapping the state to its corresponding default rate
+        X_transformed = X.copy()
+        X_transformed["state_default_rate"] = X_transformed["state"].map(self.default_rate_by_state_)
+        
+        return X_transformed
+
+
+# A wrapper for StandardScaler to passthrough empty DataFrames during .transform() instead of raising a ValueError
+class RobustStandardScaler(StandardScaler):
+    def transform(self, X):
+        if X.empty:
+            feature_names_out = self.get_feature_names_out(X.columns)
+            return pd.DataFrame(columns=feature_names_out, dtype=float)
+        else:
+            return super().transform(X)
+
+
+# A wrapper for StandardScaler to passthrough empty DataFrames during .transform() instead of raising a ValueError
+class RobustOneHotEncoder(OneHotEncoder):
+    def transform(self, X):
+        check_is_fitted(self)
+        if X.empty:
+            feature_names_out = self.get_feature_names_out(X.columns)
+            return pd.DataFrame(columns=feature_names_out, dtype=float)
+        else:
+            return super().transform(X)
+
+
+# A wrapper for StandardScaler to passthrough empty DataFrames during .transform() instead of raising a ValueError
+class RobustOrdinalEncoder(OrdinalEncoder):
+    def transform(self, X):
+        if X.empty:
+            feature_names_out = self.get_feature_names_out(X.columns)
+            return pd.DataFrame(columns=feature_names_out, dtype=float)
+        else:
+            return super().transform(X)
+
+
+# Feature selection for downstream model training and inference 
+class FeatureSelector(BaseEstimator, TransformerMixin):
+    def __init__(self, columns_to_keep):
+        # Validate input data type
+        if not isinstance(columns_to_keep, list):
+            raise TypeError("'columns_to_keep' must be a list of column names.")
+
+        # Validate input value
+        if not columns_to_keep:
+            raise ValueError("'columns_to_keep' cannot be an empty list. It must specify the column names.")
+
+        self.columns_to_keep = columns_to_keep
+
+    def fit(self, X, y=None):
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")   
+        
+        # Ensure input DataFrame contains all columns_to_keep
+        missing_columns = set(self.columns_to_keep) - set(X.columns)
+        if missing_columns:
+            raise ColumnMismatchError(f"Input X is missing the following columns: {', '.join(missing_columns)}.")
+            
+        # Store input feature number and names as learned attributes
+        self.n_features_in_ = X.shape[1]
+        self.feature_names_in_ = X.columns.tolist()
+
+        return self  
+
+    def transform(self, X):
+        # Ensure .fit() happened before
+        check_is_fitted(self)
+
+        # Validate input data type
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("Input X must be a pandas DataFrame.")
+
+        # Ensure input feature names and feature order is the same as during .fit()
+        if X.columns.tolist() != self.feature_names_in_:
+            raise ColumnMismatchError("Feature names and feature order of input X must be the same as during .fit().")      
+        
+        # Create transformed DataFrame with only the selected features
+        X_transformed = X[self.columns_to_keep].copy()
+        
+        return X_transformed 

src/global_constants.py

@@ -0,0 +1,502 @@
+# Imports
+import numpy as np
+
+# --- Constants for Pipeline ---
+# Define critical vs. non-critical features (for custom MissingValueChecker)
+CRITICAL_FEATURES = ["income", "age", "experience", "profession", "city", "state", "current_job_yrs", "current_house_yrs"]
+NON_CRITICAL_FEATURES = ["married", "car_ownership", "house_ownership"]
+
+# Define columns to format categorical labels as snake case (for custom SnakeCaseFormatter)
+COLUMNS_FOR_SNAKE_CASING = ["profession", "city", "state"]
+
+# Map binary categorical columns to boolean (for custom BooleanColumnTransformer)
+BOOLEAN_COLUMN_MAPPINGS = {
+    "married": {"married": True, "single": False},
+    "car_ownership": {"yes": True, "no": False}
+}
+
+# Map profession to job stability tier (for custom JobStabilityTransformer)
+JOB_STABILITY_MAP = {
+    # Government and highly regulated roles with exceptional job security
+    "civil_servant": "very_stable",
+    "army_officer": "very_stable",
+    "police_officer": "very_stable",
+    "magistrate": "very_stable",
+    "official": "very_stable",
+    "air_traffic_controller": "very_stable",
+    "firefighter": "very_stable",
+    "librarian": "very_stable",
+    
+    # Licensed/regulated professionals with strong job security
+    "physician": "stable",
+    "surgeon": "stable",
+    "dentist": "stable",
+    "chartered_accountant": "stable",
+    "civil_engineer": "stable",
+    "mechanical_engineer": "stable",
+    "chemical_engineer": "stable",
+    "petroleum_engineer": "stable",
+    "biomedical_engineer": "stable",
+    "engineer": "stable",
+    
+    # Corporate roles with steady demand
+    "software_developer": "moderate",
+    "computer_hardware_engineer": "moderate",
+    "financial_analyst": "moderate",
+    "industrial_engineer": "moderate",
+    "statistician": "moderate",
+    "microbiologist": "moderate",
+    "scientist": "moderate",
+    "geologist": "moderate",
+    "economist": "moderate",
+    "technology_specialist": "moderate",
+    "design_engineer": "moderate",
+    "architect": "moderate",
+    "surveyor": "moderate",
+    "secretary": "moderate",
+    "flight_attendant": "moderate",
+    "hotel_manager": "moderate",
+    "computer_operator": "moderate",
+    "technician": "moderate",
+    
+    # Project-based or variable demand roles
+    "web_designer": "variable",
+    "fashion_designer": "variable",
+    "graphic_designer": "variable",
+    "designer": "variable",
+    "consultant": "variable",
+    "technical_writer": "variable",
+    "artist": "variable",
+    "comedian": "variable",
+    "chef": "variable",
+    "analyst": "variable",
+    "psychologist": "variable",
+    "drafter": "variable",
+    "aviator": "variable",
+    "politician": "variable",
+    "lawyer": "variable"
+}
+
+# Map city to city tier (for custom CityTierTransformer)
+CITY_TIER_MAP = {
+    # Tier 1 cities
+    "new_delhi": "tier_1",
+    "navi_mumbai": "tier_1",
+    "kolkata": "tier_1",
+    "bangalore": "tier_1",
+    "chennai": "tier_1",
+    "hyderabad": "tier_1",
+    "mumbai": "tier_1",
+    "pune": "tier_1",
+    "ahmedabad": "tier_1",
+    "jaipur": "tier_1",
+    "lucknow": "tier_1",
+    "noida": "tier_1",
+    "coimbatore": "tier_1",
+    "surat": "tier_1",
+    "nagpur": "tier_1",
+    "kochi": "tier_1",
+    "thiruvananthapuram": "tier_1",
+    "kanpur": "tier_1",
+    "patna": "tier_1",
+
+    # Tier 2 cities
+    "bhopal": "tier_2",
+    "vijayawada": "tier_2",
+    "indore": "tier_2",
+    "jodhpur": "tier_2",
+    "vadodara": "tier_2",
+    "ludhiana": "tier_2",
+    "madurai": "tier_2",
+    "agra": "tier_2",
+    "mysore[7][8][9]": "tier_2",
+    "rajkot": "tier_2",
+    "nashik": "tier_2",
+    "amritsar": "tier_2",
+    "ranchi": "tier_2",
+    "chandigarh_city": "tier_2",
+    "allahabad": "tier_2",
+    "bhubaneswar": "tier_2",
+    "varanasi": "tier_2",
+    "jabalpur": "tier_2",
+    "guwahati": "tier_2",
+    "tiruppur": "tier_2",
+    "raipur": "tier_2",
+    "udaipur": "tier_2",
+    "gwalior": "tier_2",
+
+    # Tier 3 cities
+    "vijayanagaram": "tier_3",
+    "bulandshahr": "tier_3",
+    "saharsa[29]": "tier_3",
+    "hajipur[31]": "tier_3",
+    "satara": "tier_3",
+    "ongole": "tier_3",
+    "bellary": "tier_3",
+    "giridih": "tier_3",
+    "hospet": "tier_3",
+    "khammam": "tier_3",
+    "danapur": "tier_3",
+    "bareilly": "tier_3",
+    "satna": "tier_3",
+    "howrah": "tier_3",
+    "thanjavur": "tier_3",
+    "farrukhabad": "tier_3",
+    "buxar[37]": "tier_3",
+    "arrah": "tier_3",
+    "thrissur": "tier_3",
+    "proddatur": "tier_3",
+    "bahraich": "tier_3",
+    "nandyal": "tier_3",
+    "siwan[32]": "tier_3",
+    "barasat": "tier_3",
+    "dhule": "tier_3",
+    "begusarai": "tier_3",
+    "khandwa": "tier_3",
+    "guntakal": "tier_3",
+    "latur": "tier_3",
+    "karaikudi": "tier_3",
+
+    # Unknown tier cities
+    "rewa": "unknown",
+    "parbhani": "unknown",
+    "alappuzha": "unknown",
+    "tiruchirappalli[10]": "unknown",
+    "jalgaon": "unknown",
+    "jamnagar": "unknown",
+    "kota[6]": "unknown",
+    "karimnagar": "unknown",
+    "adoni": "unknown",
+    "erode[17]": "unknown",
+    "kollam": "unknown",
+    "anantapuram[24]": "unknown",
+    "kamarhati": "unknown",
+    "bhusawal": "unknown",
+    "sirsa": "unknown",
+    "amaravati": "unknown",
+    "secunderabad": "unknown",
+    "ajmer": "unknown",
+    "miryalaguda": "unknown",
+    "ambattur": "unknown",
+    "pondicherry": "unknown",
+    "shimoga": "unknown",
+    "gulbarga": "unknown",
+    "saharanpur": "unknown",
+    "gopalpur": "unknown",
+    "amravati": "unknown",
+    "udupi": "unknown",
+    "aurangabad[39]": "unknown",
+    "shimla": "unknown",
+    "bidhannagar": "unknown",
+    "purnia[26]": "unknown",
+    "bijapur": "unknown",
+    "patiala": "unknown",
+    "malda": "unknown",
+    "sagar": "unknown",
+    "durgapur": "unknown",
+    "junagadh": "unknown",
+    "singrauli": "unknown",
+    "agartala": "unknown",
+    "hindupur": "unknown",
+    "naihati": "unknown",
+    "north_dumdum": "unknown",
+    "panchkula": "unknown",
+    "anantapur": "unknown",
+    "serampore": "unknown",
+    "bathinda": "unknown",
+    "nadiad": "unknown",
+    "haridwar": "unknown",
+    "berhampur": "unknown",
+    "jamshedpur": "unknown",
+    "bidar": "unknown",
+    "kottayam": "unknown",
+    "solapur": "unknown",
+    "suryapet": "unknown",
+    "aizawl": "unknown",
+    "asansol": "unknown",
+    "deoghar": "unknown",
+    "eluru[25]": "unknown",
+    "ulhasnagar": "unknown",
+    "aligarh": "unknown",
+    "south_dumdum": "unknown",
+    "berhampore": "unknown",
+    "gandhinagar": "unknown",
+    "sonipat": "unknown",
+    "muzaffarpur": "unknown",
+    "raichur": "unknown",
+    "rajpur_sonarpur": "unknown",
+    "ambarnath": "unknown",
+    "katihar": "unknown",
+    "kozhikode": "unknown",
+    "vellore": "unknown",
+    "malegaon": "unknown",
+    "nagaon": "unknown",
+    "srinagar": "unknown",
+    "davanagere": "unknown",
+    "bhagalpur": "unknown",
+    "meerut": "unknown",
+    "dindigul": "unknown",
+    "bhatpara": "unknown",
+    "ghaziabad": "unknown",
+    "kulti": "unknown",
+    "chapra": "unknown",
+    "dibrugarh": "unknown",
+    "panihati": "unknown",
+    "bhiwandi": "unknown",
+    "morbi": "unknown",
+    "kalyan_dombivli": "unknown",
+    "gorakhpur": "unknown",
+    "panvel": "unknown",
+    "siliguri": "unknown",
+    "bongaigaon": "unknown",
+    "ramgarh": "unknown",
+    "ozhukarai": "unknown",
+    "mirzapur": "unknown",
+    "akola": "unknown",
+    "motihari[34]": "unknown",
+    "jalna": "unknown",
+    "jalandhar": "unknown",
+    "unnao": "unknown",
+    "karnal": "unknown",
+    "cuttack": "unknown",
+    "ichalkaranji": "unknown",
+    "warangal[11][12]": "unknown",
+    "jhansi": "unknown",
+    "narasaraopet": "unknown",
+    "chinsurah": "unknown",
+    "jehanabad[38]": "unknown",
+    "dhanbad": "unknown",
+    "gudivada": "unknown",
+    "gandhidham": "unknown",
+    "raiganj": "unknown",
+    "kishanganj[35]": "unknown",
+    "belgaum": "unknown",
+    "tirupati[21][22]": "unknown",
+    "tumkur": "unknown",
+    "kurnool[18]": "unknown",
+    "gurgaon": "unknown",
+    "muzaffarnagar": "unknown",
+    "aurangabad": "unknown",
+    "bhavnagar": "unknown",
+    "munger": "unknown",
+    "tirunelveli": "unknown",
+    "mango": "unknown",
+    "kadapa[23]": "unknown",
+    "khora,_ghaziabad": "unknown",
+    "ambala": "unknown",
+    "ratlam": "unknown",
+    "surendranagar_dudhrej": "unknown",
+    "delhi_city": "unknown",
+    "hapur": "unknown",
+    "rohtak": "unknown",
+    "durg": "unknown",
+    "korba": "unknown",
+    "shivpuri": "unknown",
+    "nangloi_jat": "unknown",
+    "madanapalle": "unknown",
+    "thoothukudi": "unknown",
+    "nagercoil": "unknown",
+    "gaya": "unknown",
+    "jammu[16]": "unknown",
+    "kakinada": "unknown",
+    "dewas": "unknown",
+    "bhalswa_jahangir_pur": "unknown",
+    "baranagar": "unknown",
+    "firozabad": "unknown",
+    "phusro": "unknown",
+    "guna": "unknown",
+    "thane": "unknown",
+    "etawah": "unknown",
+    "vasai_virar": "unknown",
+    "pallavaram": "unknown",
+    "morena": "unknown",
+    "ballia": "unknown",
+    "burhanpur": "unknown",
+    "phagwara": "unknown",
+    "mau": "unknown",
+    "mangalore": "unknown",
+    "alwar": "unknown",
+    "mahbubnagar": "unknown",
+    "maheshtala": "unknown",
+    "hazaribagh": "unknown",
+    "bihar_sharif": "unknown",
+    "faridabad": "unknown",
+    "tenali": "unknown",
+    "amroha": "unknown",
+    "medininagar": "unknown",
+    "rajahmundry[19][20]": "unknown",
+    "bhilai": "unknown",
+    "moradabad": "unknown",
+    "machilipatnam": "unknown",
+    "mira_bhayandar": "unknown",
+    "pali": "unknown",
+    "mehsana": "unknown",
+    "imphal": "unknown",
+    "sambalpur": "unknown",
+    "ujjain": "unknown",
+    "madhyamgram": "unknown",
+    "jamalpur[36]": "unknown",
+    "gangtok": "unknown",
+    "anand": "unknown",
+    "dehradun": "unknown",
+    "srikakulam": "unknown",
+    "darbhanga": "unknown",
+    "nizamabad": "unknown",
+    "dehri[30]": "unknown",
+    "jorhat": "unknown",
+    "kumbakonam": "unknown",
+    "haldia": "unknown",
+    "loni": "unknown",
+    "pimpri_chinchwad": "unknown",
+    "nanded": "unknown",
+    "kirari_suleman_nagar": "unknown",
+    "jaunpur": "unknown",
+    "bilaspur": "unknown",
+    "sambhal": "unknown",
+    "rourkela": "unknown",
+    "dharmavaram": "unknown",
+    "nellore[14][15]": "unknown",
+    "visakhapatnam[4]": "unknown",
+    "karawal_nagar": "unknown",
+    "avadi": "unknown",
+    "bhimavaram": "unknown",
+    "bardhaman": "unknown",
+    "silchar": "unknown",
+    "kavali": "unknown",
+    "tezpur": "unknown",
+    "ramagundam[27]": "unknown",
+    "yamunanagar": "unknown",
+    "sri_ganganagar": "unknown",
+    "sasaram[30]": "unknown",
+    "sikar": "unknown",
+    "bally": "unknown",
+    "bhiwani": "unknown",
+    "rampur": "unknown",
+    "uluberia": "unknown",
+    "sangli_miraj_&_kupwad": "unknown",
+    "hosur": "unknown",
+    "bikaner": "unknown",
+    "shahjahanpur": "unknown",
+    "sultan_pur_majra": "unknown",
+    "bharatpur": "unknown",
+    "tadepalligudem": "unknown",
+    "tinsukia": "unknown",
+    "salem": "unknown",
+    "mathura": "unknown",
+    "guntur[13]": "unknown",
+    "hubli_dharwad": "unknown",
+    "chittoor[28]": "unknown",
+    "tiruvottiyur": "unknown",
+    "ahmednagar": "unknown",
+    "fatehpur": "unknown",
+    "bhilwara": "unknown",
+    "kharagpur": "unknown",
+    "bettiah[33]": "unknown",
+    "bhind": "unknown",
+    "bokaro": "unknown",
+    "raebareli": "unknown",
+    "pudukkottai": "unknown",
+    "panipat": "unknown",
+    "tadipatri": "unknown",
+    "orai": "unknown",
+    "raurkela_industrial_township": "unknown",
+    "katni": "unknown",
+    "chandrapur": "unknown",
+    "kolhapur": "unknown"
+}
+
+# Define semantic column types (for ColumnTransformer to scale numerical and encode categorical columns)
+NUMERICAL_COLUMNS = ["income", "age", "experience", "current_job_yrs", "current_house_yrs", "state_default_rate"]
+CATEGORICAL_COLUMNS = ["house_ownership", "job_stability", "city_tier", "profession", "city", "state"]
+BOOLEAN_COLUMNS = ["risk_flag", "married", "car_ownership"]
+
+# Define the categories for the nominal column "house_ownership" (for OneHotEncoder)
+NOMINAL_COLUMN_CATEGORIES = [["norent_noown", "owned", "rented"]]  # OneHotEncoder requires list of lists even for single column
+
+# Define the explicit order of categories for all ordinal columns (for OrdinalEncoder)
+ORDINAL_COLUMN_ORDERS = [
+    ["variable", "moderate", "stable", "very_stable"],  # Order for job_stability
+    ["unknown", "tier_3", "tier_2", "tier_1"]  # Order for city_tier
+]
+
+# Define the columns to keep after preprocessing as model input (for custom FeatureSelector)
+COLUMNS_TO_KEEP = [
+    "income", "age", "experience", "current_job_yrs", "current_house_yrs", "state_default_rate", "house_ownership_owned", 
+    "house_ownership_rented", "job_stability", "city_tier", "married", "car_ownership"
+]
+
+# Store the best Random Forest hyperparameter values identified with random search (for RandomForestClassifier)
+RF_BEST_PARAMS = {
+  "n_estimators": 225,
+  "max_depth": 26,
+  "min_samples_split": 2,
+  "min_samples_leaf": 1,
+  "max_features": np.float64(0.12974565961049356),
+  "class_weight": "balanced"
+}
+
+# --- Constants for App ---
+# Lists of categorical string labels (in format expected by the pipeline)
+MARRIED_LABELS = ["single", "married"]
+CAR_OWNERSHIP_LABELS = ["yes", "no"]
+HOUSE_OWNERSHIP_LABELS = ["rented", "owned", "norent_noown"]  
+PROFESSION_LABELS = [
+    "air_traffic_controller", "analyst", "architect", "army_officer", "artist", "aviator",
+    "biomedical_engineer", "chartered_accountant", "chef", "chemical_engineer", "civil_engineer",
+    "civil_servant", "comedian", "computer_hardware_engineer", "computer_operator", "consultant",
+    "dentist", "design_engineer", "designer", "drafter", "economist", "engineer",
+    "fashion_designer", "financial_analyst", "firefighter", "flight_attendant", "geologist",
+    "graphic_designer", "hotel_manager", "industrial_engineer", "lawyer", "librarian",
+    "magistrate", "mechanical_engineer", "microbiologist", "official", "petroleum_engineer",
+    "physician", "police_officer", "politician", "psychologist", "scientist", "secretary",
+    "software_developer", "statistician", "surgeon", "surveyor", "technical_writer",
+    "technician", "technology_specialist", "web_designer"
+]
+CITY_LABELS = [
+    "adoni", "agartala", "agra", "ahmedabad", "ahmednagar", "aizawl", "ajmer", "akola", "alappuzha", "aligarh",
+    "allahabad", "alwar", "ambala", "ambarnath", "ambattur", "amravati", "amritsar", "amroha", "anand", "anantapur",
+    "anantapuram[24]", "arrah", "asansol", "aurangabad", "aurangabad[39]", "avadi", "bahraich", "ballia", "bally",
+    "bangalore", "baranagar", "barasat", "bardhaman", "bareilly", "bathinda", "begusarai", "belgaum", "bellary",
+    "berhampore", "berhampur", "bettiah[33]", "bhadravati", "bhagalpur", "bhalswa_jahangir_pur", "bharatpur",
+    "bhatpara", "bhavnagar", "bhilai", "bhilwara", "bhimavaram", "bhind", "bhiwandi", "bhiwani", "bhopal",
+    "bhubaneswar", "bhusawal", "bidar", "bidhannagar", "bihar_sharif", "bijapur", "bikaner", "bilaspur", "bokaro",
+    "bongaigaon", "bulandshahr", "burhanpur", "buxar[37]", "chandigarh_city", "chandrapur", "chapra", "chennai",
+    "chinsurah", "chittoor[28]", "coimbatore", "cuttack", "danapur", "darbhanga", "davanagere", "dehradun",
+    "dehri[30]", "delhi_city", "deoghar", "dewas", "dhanbad", "dharmavaram", "dhule", "dibrugarh", "dindigul",
+    "durg", "durgapur", "eluru[25]", "erode[17]", "etawah", "faridabad", "farrukhabad", "fatehpur", "firozabad",
+    "gandhidham", "gandhinagar", "gangtok", "gaya", "ghaziabad", "giridih", "gopalpur", "gorakhpur", "gudivada",
+    "gulbarga", "guna", "guntakal", "guntur[13]", "gurgaon", "guwahati", "gwalior", "hajipur[31]", "haldia",
+    "hapur", "haridwar", "hazaribagh", "hindupur", "hospet", "hosur", "howrah", "hubli_dharwad", "hyderabad",
+    "ichalkaranji", "imphal", "indore", "jabalpur", "jaipur", "jalandhar", "jalgaon", "jalna", "jamalpur[36]",
+    "jammu[16]", "jamnagar", "jamshedpur", "jaunpur", "jehanabad[38]", "jhansi", "jodhpur", "jorhat", "junagadh",
+    "kadapa[23]", "kakinada", "kalyan_dombivli", "kamarhati", "kanpur", "karawal_nagar", "karaikudi", "karimnagar",
+    "karnal", "katihar", "katni", "kavali", "khammam", "khandwa", "kharagpur", "khora,_ghaziabad",
+    "kirari_suleman_nagar", "kishanganj[35]", "kochi", "kolhapur", "kolkata", "kollam", "korba", "kota[6]",
+    "kottayam", "kozhikode", "kulti", "kumbakonam", "kurnool[18]", "latur", "loni", "lucknow", "ludhiana",
+    "machilipatnam", "madanapalle", "madhyamgram", "madurai", "mahbubnagar", "maheshtala", "malda", "malegaon",
+    "mango", "mangalore", "mathura", "mau", "medininagar", "meerut", "mehsana", "mira_bhayandar", "mirzapur",
+    "miryalaguda", "moradabad", "morbi", "morena", "motihari[34]", "mumbai", "munger", "muzaffarnagar",
+    "muzaffarpur", "mysore[7][8][9]", "nadiad", "nagaon", "nagercoil", "nagpur", "naihati", "nanded", "nandyal",
+    "nangloi_jat", "narasaraopet", "nashik", "navi_mumbai", "nellore[14][15]", "new_delhi", "nizamabad", "noida",
+    "north_dumdum", "ongole", "orai", "ozhukarai", "pali", "pallavaram", "panchkula", "panipat", "panihati",
+    "panvel", "parbhani", "patiala", "patna", "phagwara", "phusro", "pimpri_chinchwad", "pondicherry",
+    "proddatur", "pudukkottai", "pune", "purnia[26]", "raebareli", "raichur", "raiganj", "raipur",
+    "rajahmundry[19][20]", "rajkot", "rajpur_sonarpur", "ramagundam[27]", "ramgarh", "rampur", "ranchi", "ratlam",
+    "raurkela_industrial_township", "rewa", "rohtak", "rourkela", "sagar", "saharanpur", "saharsa[29]", "salem",
+    "sambalpur", "sambhal", "sangli_miraj_&_kupwad", "sasaram[30]", "satara", "satna", "secunderabad",
+    "serampore", "shahjahanpur", "shimla", "shimoga", "shivpuri", "sikar", "silchar", "siliguri", "singrauli",
+    "sirsa", "siwan[32]", "solapur", "sonipat", "south_dumdum", "sri_ganganagar", "srikakulam", "srinagar",
+    "sultan_pur_majra", "surat", "surendranagar_dudhrej", "suryapet", "tadipatri", "tadepalligudem", "tenali",
+    "tezpur", "thane", "thanjavur", "thiruvananthapuram", "thoothukudi", "thrissur", "tinsukia",
+    "tiruchirappalli[10]", "tirunelveli", "tirupati[21][22]", "tiruppur", "tiruvottiyur", "tumkur", "udaipur",
+    "udupi", "ujjain", "ulhasnagar", "uluberia", "unnao", "vadodara", "varanasi", "vasai_virar", "vellore",
+    "vijayawada", "vijayanagaram", "visakhapatnam[4]", "warangal[11][12]", "yamunanagar"
+]
+STATE_LABELS = [
+    "andhra_pradesh", "assam", "bihar", "chandigarh", "chhattisgarh",
+    "delhi", "gujarat", "haryana", "himachal_pradesh", "jammu_and_kashmir",
+    "jharkhand", "karnataka", "kerala", "madhya_pradesh", "maharashtra",
+    "manipur", "mizoram", "odisha", "puducherry", "punjab", "rajasthan",
+    "sikkim", "tamil_nadu", "telangana", "tripura", "uttar_pradesh",
+    "uttar_pradesh[5]", "uttarakhand", "west_bengal"
+]

src/pipeline.py

@@ -0,0 +1,122 @@
+# Third-party library imports
+from sklearn.pipeline import Pipeline
+from sklearn.compose import ColumnTransformer
+from sklearn.ensemble import RandomForestClassifier
+
+# Local imports
+from .custom_transformers import (
+    MissingValueChecker, 
+    MissingValueStandardizer, 
+    RobustSimpleImputer,
+    SnakeCaseFormatter, 
+    BooleanColumnTransformer, 
+    JobStabilityTransformer, 
+    CityTierTransformer, 
+    StateDefaultRateTargetEncoder,
+    RobustStandardScaler,
+    RobustOneHotEncoder,
+    RobustOrdinalEncoder,
+    FeatureSelector
+)
+from .global_constants import (
+    CRITICAL_FEATURES, 
+    NON_CRITICAL_FEATURES, 
+    COLUMNS_FOR_SNAKE_CASING,
+    BOOLEAN_COLUMN_MAPPINGS,
+    JOB_STABILITY_MAP,
+    CITY_TIER_MAP,
+    NUMERICAL_COLUMNS, 
+    NOMINAL_COLUMN_CATEGORIES, 
+    ORDINAL_COLUMN_ORDERS, 
+    COLUMNS_TO_KEEP,
+    RF_BEST_PARAMS
+)
+
+
+# --- Helper Functions to Create Full Pipeline and Pipeline Segments ---
+def create_data_preprocessing_and_model_pipeline(): 
+    return Pipeline([
+        ("missing_value_checker", MissingValueChecker(critical_features=CRITICAL_FEATURES, non_critical_features=NON_CRITICAL_FEATURES)),
+        ("missing_value_standardizer", MissingValueStandardizer()),
+        ("missing_value_handler", ColumnTransformer(
+            transformers=[("categorical_imputer", RobustSimpleImputer(strategy="most_frequent").set_output(transform="pandas"), NON_CRITICAL_FEATURES)],
+            remainder="passthrough",
+            verbose_feature_names_out=False  # preserve input column names instead of adding prefix 
+        ).set_output(transform="pandas")),  # output pd.DataFrame instead of np.array 
+        ("snake_case_formatter", SnakeCaseFormatter(columns=COLUMNS_FOR_SNAKE_CASING)),
+        ("boolean_column_transformer", BooleanColumnTransformer(boolean_column_mappings=BOOLEAN_COLUMN_MAPPINGS)),
+        ("job_stability_transformer", JobStabilityTransformer(job_stability_map=JOB_STABILITY_MAP)),
+        ("city_tier_transformer", CityTierTransformer(city_tier_map=CITY_TIER_MAP)),
+        ("state_default_rate_target_encoder", StateDefaultRateTargetEncoder()),
+        ("feature_scaler_encoder", ColumnTransformer(
+            transformers=[
+                ("scaler", RobustStandardScaler(), NUMERICAL_COLUMNS), 
+                ("nominal_encoder", RobustOneHotEncoder(categories=NOMINAL_COLUMN_CATEGORIES, drop="first", sparse_output=False), ["house_ownership"]),
+                ("ordinal_encoder", RobustOrdinalEncoder(categories=ORDINAL_COLUMN_ORDERS), ["job_stability", "city_tier"])  
+            ],
+            remainder="passthrough",
+            verbose_feature_names_out=False
+        ).set_output(transform="pandas")),
+        ("feature_selector", FeatureSelector(columns_to_keep=COLUMNS_TO_KEEP)),
+        ("rf_classifier", RandomForestClassifier(**RF_BEST_PARAMS, random_state=42)) 
+    ])
+
+def create_data_preprocessing_pipeline(): 
+    return Pipeline([
+    ("missing_value_checker", MissingValueChecker(critical_features=CRITICAL_FEATURES, non_critical_features=NON_CRITICAL_FEATURES)),
+    ("missing_value_standardizer", MissingValueStandardizer()),
+    ("missing_value_handler", ColumnTransformer(
+        transformers=[("categorical_imputer", RobustSimpleImputer(strategy="most_frequent").set_output(transform="pandas"), NON_CRITICAL_FEATURES)],
+        remainder="passthrough",
+        verbose_feature_names_out=False  # preserve input column names instead of adding prefix 
+    ).set_output(transform="pandas")),  # output pd.DataFrame instead of np.array 
+    ("snake_case_formatter", SnakeCaseFormatter(columns=COLUMNS_FOR_SNAKE_CASING)),
+    ("boolean_column_transformer", BooleanColumnTransformer(boolean_column_mappings=BOOLEAN_COLUMN_MAPPINGS)),
+    ("job_stability_transformer", JobStabilityTransformer(job_stability_map=JOB_STABILITY_MAP)),
+    ("city_tier_transformer", CityTierTransformer(city_tier_map=CITY_TIER_MAP)),
+    ("state_default_rate_target_encoder", StateDefaultRateTargetEncoder()),
+    ("feature_scaler_encoder", ColumnTransformer(
+        transformers=[
+            ("scaler", RobustStandardScaler(), NUMERICAL_COLUMNS), 
+            ("nominal_encoder", RobustOneHotEncoder(categories=NOMINAL_COLUMN_CATEGORIES, drop="first", sparse_output=False), ["house_ownership"]),
+            ("ordinal_encoder", RobustOrdinalEncoder(categories=ORDINAL_COLUMN_ORDERS), ["job_stability", "city_tier"])  
+        ],
+        remainder="passthrough",
+        verbose_feature_names_out=False
+    ).set_output(transform="pandas")),
+    ("feature_selector", FeatureSelector(columns_to_keep=COLUMNS_TO_KEEP))
+])
+
+def create_model_preprocessing_pipeline(): 
+    return Pipeline([
+        ("feature_scaler_encoder", ColumnTransformer(
+            transformers=[
+                ("scaler", RobustStandardScaler(), NUMERICAL_COLUMNS), 
+                ("nominal_encoder", RobustOneHotEncoder(categories=NOMINAL_COLUMN_CATEGORIES, drop="first", sparse_output=False), ["house_ownership"]),
+                ("ordinal_encoder", RobustOrdinalEncoder(categories=ORDINAL_COLUMN_ORDERS), ["job_stability", "city_tier"])  
+            ],
+            remainder="passthrough",
+            verbose_feature_names_out=False
+        ).set_output(transform="pandas")),
+        ("feature_selector", FeatureSelector(columns_to_keep=COLUMNS_TO_KEEP))
+    ])
+
+def create_feature_engineering_pipeline(): 
+    return Pipeline([
+        ("snake_case_formatter", SnakeCaseFormatter(columns=COLUMNS_FOR_SNAKE_CASING)),
+        ("boolean_column_transformer", BooleanColumnTransformer(boolean_column_mappings=BOOLEAN_COLUMN_MAPPINGS)),
+        ("job_stability_transformer", JobStabilityTransformer(job_stability_map=JOB_STABILITY_MAP)),
+        ("city_tier_transformer", CityTierTransformer(city_tier_map=CITY_TIER_MAP)),
+        ("state_default_rate_target_encoder", StateDefaultRateTargetEncoder()),
+    ])
+
+def create_missing_value_handling_pipeline(): 
+    return Pipeline([
+        ("missing_value_checker", MissingValueChecker(critical_features=CRITICAL_FEATURES, non_critical_features=NON_CRITICAL_FEATURES)),
+        ("missing_value_standardizer", MissingValueStandardizer()),
+        ("missing_value_handler", ColumnTransformer(
+            transformers=[("categorical_imputer", RobustSimpleImputer(strategy="most_frequent").set_output(transform="pandas"), NON_CRITICAL_FEATURES)],
+            remainder="passthrough",
+            verbose_feature_names_out=False  # preserve input column names instead of adding prefix 
+        ).set_output(transform="pandas")),  # output pd.DataFrame instead of np.array 
+    ])

src/utils.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+# Helper function to get path to root directory 
+def get_root_directory(anchor_files: str | list[str] = [".git", "Readme.md", "requirements.txt"]) -> Path:
+    # Standardize inputs to list[str]
+    if isinstance(anchor_files, str):
+        anchor_files = [anchor_files]
+
+    # Get absolute path to current file
+    file_path = Path(__file__).resolve()
+
+    # Iterate over each parent directory
+    for parent in file_path.parents:
+        # Iterate over each anchor file
+        for anchor_file in anchor_files:
+            # Check if anchor file exists in parent directory
+            if (parent / anchor_file).exists():
+                # Return the parent directory in which the anchor file was found, i.e. the root directory
+                return parent
+    raise FileNotFoundError(f"Root directory not found: None of the anchor files '{anchor_files}' were found in any parent directory.")

start.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e  # exit immediately if any command fails
+
+# Create geoip_db directory (if it doesn't exist already)
+mkdir -p /app/geoip_db
+
+# Download GeoLite2-Country.mmdb (if it doesn't exist already)
+if [ ! -f /app/geoip_db/GeoLite2-Country.mmdb ]; then
+  echo "Downloading GeoLite2-Country.mmdb..."
+  
+  # Create an account at https://www.maxmind.com/, create a license key and add it to your .env file and your Hugging Face Space secrets
+  # Sanitize the key: remove single/double quotes and whitespace (Docker --env-file includes quotes in the value, which breaks the URL)
+  MAXMIND_LICENSE_KEY=$(echo "$MAXMIND_LICENSE_KEY" | tr -d '"' | tr -d "'" | tr -d '[:space:]')
+
+  # Download the database using the sanitized key 
+  curl -L -o /app/geoip_db/GeoLite2-Country.tar.gz \
+    "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz"
+
+  # Extract the .mmdb file and remove archive
+  tar -xzf /app/geoip_db/GeoLite2-Country.tar.gz -C /app/geoip_db --strip-components=1
+  rm /app/geoip_db/GeoLite2-Country.tar.gz
+  echo "Successfully downloaded GeoLite2-Country.mmdb."
+fi
+
+# Start the combined FastAPI and Gradio app on a uvicorn server (Hugging Face Spaces expects port 7860 even though default is 8000)
+uvicorn backend.app:app --host 0.0.0.0 --port 7860