{"id":28923943,"url":"https://github.com/narendhiran-dev/predictive-analytics-for-repayment-predictions","last_synced_at":"2026-04-13T18:01:20.174Z","repository":{"id":299774605,"uuid":"1003618282","full_name":"narendhiran-dev/Predictive-Analytics-for-Repayment-Predictions","owner":"narendhiran-dev","description":"A machine learning API built with Python, FastAPI, and Scikit-learn to predict borrower repayment risk based on historical payment data. A FinTech risk assessment system that uses a Random Forest model to predict a borrower's future repayment behavior and serves the prediction via a REST API.","archived":false,"fork":false,"pushed_at":"2025-06-18T07:38:05.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-23T23:37:54.700Z","etag":null,"topics":["data-science","fastapi","fintech","loan-prediction","loan-prediction-analysis","machine-learning","machine-learning-algorithms","predictive-modeling","python","random-forest","random-forest-classifier","random-forest-regression","rest-api","risk-assessment","scikit-learn","scikit-learn-api","scikit-learn-python"],"latest_commit_sha":null,"homepage":"http://127.0.0.1:8000/docs","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/narendhiran-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-17T12:18:15.000Z","updated_at":"2025-06-18T07:38:08.000Z","dependencies_parsed_at":"2025-06-18T08:45:16.969Z","dependency_job_id":null,"html_url":"https://github.com/narendhiran-dev/Predictive-Analytics-for-Repayment-Predictions","commit_stats":null,"previous_names":["narendhiran-dev/predictive-analytics-for-repayment-predictions"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/narendhiran-dev/Predictive-Analytics-for-Repayment-Predictions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendhiran-dev%2FPredictive-Analytics-for-Repayment-Predictions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendhiran-dev%2FPredictive-Analytics-for-Repayment-Predictions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendhiran-dev%2FPredictive-Analytics-for-Repayment-Predictions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendhiran-dev%2FPredictive-Analytics-for-Repayment-Predictions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narendhiran-dev","download_url":"https://codeload.github.com/narendhiran-dev/Predictive-Analytics-for-Repayment-Predictions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendhiran-dev%2FPredictive-Analytics-for-Repayment-Predictions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31764317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","fastapi","fintech","loan-prediction","loan-prediction-analysis","machine-learning","machine-learning-algorithms","predictive-modeling","python","random-forest","random-forest-classifier","random-forest-regression","rest-api","risk-assessment","scikit-learn","scikit-learn-api","scikit-learn-python"],"created_at":"2025-06-22T10:02:22.551Z","updated_at":"2026-04-13T18:01:20.158Z","avatar_url":"https://github.com/narendhiran-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"This file summarizes the project's purpose, technologies, and—most importantly—provides a clear, step-by-step guide with the exact commands needed to set up and run everything, incorporating all the lessons we learned from our debugging.\r\n\r\nHere is the complete `README.md` file. You can copy and paste this entire block into the `README.md` file in your project folder.\r\n\r\n---\r\n\r\n# Borrower Repayment Prediction System\r\n\r\nThis project is a machine learning system that predicts a borrower's future repayment behavior based on their past payment history. It uses a `RandomForestRegressor` model served via a FastAPI REST API.\r\n\r\n## Overview\r\n\r\nThe system analyzes a borrower's history of on-time, missed, and due payments to predict a \"repayment percentage.\" Based on this percentage, it assigns a risk level (Low, Medium, or High). This provides valuable insights for investors or lenders about a borrower's reliability.\r\n\r\n### Key Features\r\n- **Predictive Model:** Utilizes a Scikit-learn `RandomForestRegressor` to predict future repayment performance.\r\n- **Rich Feature Engineering:** Extracts features like payment ratios, delay statistics, and recent behavior trends.\r\n- **Risk Classification:** Categorizes borrowers into Low, Medium, and High-risk tiers based on the model's prediction.\r\n- **REST API:** Exposes the model's functionality through a clean, simple FastAPI endpoint.\r\n\r\n## Technology Stack\r\n- **Backend:** Python 3.11+\r\n- **API Framework:** FastAPI\r\n- **ML/Data Science:** Scikit-learn, Pandas, NumPy\r\n- **Server:** Uvicorn\r\n\r\n## Project Structure\r\n```\r\nrepayment_prediction_system/\r\n├── data/\r\n│   ├── raw/\r\n│   │   ├── payment_history.csv\r\n│   │   └── investor_borrower.csv\r\n│   └── processed/\r\n├── repayment_predictor/\r\n│   ├── api/\r\n│   │   ├── main.py\r\n│   │   └── schemas.py\r\n│   ├── core/\r\n│   │   └── config.py\r\n│   ├── data_processing/\r\n│   │   └── loader.py\r\n│   ├── features/\r\n│   │   └── build_features.py\r\n│   └── models/\r\n│       ├── predict_model.py\r\n│       ├── risk_classifier.py\r\n│       └── train_model.py\r\n├── saved_models/\r\n│   ├── random_forest_regressor.joblib\r\n│   └── scaler.joblib\r\n├── .gitignore\r\n├── README.md\r\n└── requirements.txt\r\n```\r\n\r\n---\r\n\r\n## Setup and Installation\r\n\r\nFollow these steps to set up the project environment.\r\n\r\n### 1. Prerequisites\r\n- Python 3.11 or newer\r\n- `pip` package manager\r\n\r\n### 2. Clone the Repository\r\nDownload or clone this project to your local machine.\r\n```bash\r\n# Navigate to your desired directory\r\ncd C:\\path\\to\\your\\projects\r\n\r\n# Clone the repository (if it's in git)\r\n# git clone ...\r\n```\r\n\r\n### 3. Create a Virtual Environment (Recommended)\r\nFrom the project's root directory (`repayment_prediction_system`), create and activate a virtual environment.\r\n```bash\r\n# Create the virtual environment\r\npython -m venv venv\r\n\r\n# Activate it\r\n.\\venv\\Scripts\\activate\r\n```\r\n\r\n### 4. Install Dependencies\r\nInstall all the required Python libraries.\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\n### 5. Populate Data Files\r\nThe system requires sample data to run. Ensure the following files in `data/raw/` are not empty.\r\n\r\n**`data/raw/payment_history.csv`**\r\n```csv\r\npayment_id,borrower_id,due_date,payment_date,status\r\n1,1,2023-01-15,2023-01-14,on_time\r\n2,1,2023-02-15,2023-02-18,missed\r\n3,1,2023-03-15,2023-03-15,on_time\r\n4,1,2023-04-15,2023-04-25,missed\r\n5,1,2023-05-15,2023-05-28,missed\r\n6,1,2023-06-15,2023-06-15,on_time\r\n7,2,2023-01-10,2023-01-10,on_time\r\n8,2,2023-02-10,2023-02-10,on_time\r\n9,2,2023-03-10,2023-03-09,on_time\r\n10,2,2023-04-10,2023-04-10,on_time\r\n11,2,2023-05-10,2023-05-11,missed\r\n12,3,2023-03-20,2023-05-20,missed\r\n13,3,2023-04-20,2023-06-25,missed\r\n14,3,2023-05-20,2023-08-01,missed\r\n15,3,2023-06-20,,due\r\n16,3,2023-07-20,,due\r\n```\r\n\r\n**`data/raw/investor_borrower.csv`**\r\n```csv\r\ninvestor_id,borrower_id\r\nINV1,1\r\nINV1,2\r\nINV2,3\r\nINV3,4\r\n```\r\n\r\n---\r\n\r\n## Usage\r\n\r\nFollow these steps in order to train the model and run the API.\r\n\r\n### Step 1: Train the Model\r\nRun the training script from the **project root directory**. This will process the data, train the model, and save the model artifacts (`.joblib` files) into the `saved_models/` directory.\r\n```bash\r\npython repayment_predictor\\models\\train_model.py\r\n```\r\nYou should see output indicating the training process is complete and the model has been saved.\r\n\r\n### Step 2: Run the API Server\r\nStart the FastAPI server using Uvicorn.\r\n```bash\r\nuvicorn repayment_predictor.api.main:app --reload\r\n```\r\nThe server will start and be available at `http://127.0.0.1:8000`. Keep this terminal window open.\r\n\r\n### Step 3: Make a Prediction\r\nOpen a **new, second** terminal window to send a request to the running server.\r\n\r\nTo avoid command-line quoting issues on Windows, the most reliable method is to use a JSON file for the request body.\r\n\r\n**A. Create a `request.json` file** in the project's root directory with the following content:\r\n```json\r\n{\r\n  \"investor_id\": \"INV2\",\r\n  \"borrower_id\": 3\r\n}\r\n```\r\n\r\n**B. Send the request using `curl`**:\r\n```powershell\r\ncurl.exe -X POST \"http://127.0.0.1:8000/predict-repayment\" -H \"Content-Type: application/json\" -d @request.json\r\n```\r\n\r\n**Expected Successful Response:**\r\nYou will receive a JSON response with the prediction and summary for the requested borrower.\r\n```json\r\n{\r\n  \"borrower_repayment_summary\": {\r\n    \"total_payments\": 5,\r\n    \"on_time\": 0,\r\n    \"missed\": 3,\r\n    \"due\": 2,\r\n    \"average_delay_days\": 66.67,\r\n    \"max_delay_days\": 73\r\n  },\r\n  \"predicted_repayment_percentage\": 11.96,\r\n  \"risk_level\": \"High Risk\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## API Endpoint Details\r\n\r\n### POST `/predict-repayment`\r\nThis endpoint is used to predict the repayment behaviour of a borrower.\r\n\r\n**Request Body:**\r\n```json\r\n{\r\n  \"investor_id\": \"string\",\r\n  \"borrower_id\": \"integer\"\r\n}\r\n```\r\n- `investor_id` (string): The ID of the investor associated with the borrower.\r\n- `borrower_id` (integer): The ID of the borrower whose repayment prediction is needed.\r\n\r\n**Success Response (200 OK):**\r\n```json\r\n{\r\n  \"borrower_repayment_summary\": {\r\n    \"total_payments\": \"integer\",\r\n    \"on_time\": \"integer\",\r\n    \"missed\": \"integer\",\r\n    \"due\": \"integer\",\r\n    \"average_delay_days\": \"float\",\r\n    \"max_delay_days\": \"integer\"\r\n  },\r\n  \"predicted_repayment_percentage\": \"float\",\r\n  \"risk_level\": \"string\"\r\n}\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarendhiran-dev%2Fpredictive-analytics-for-repayment-predictions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarendhiran-dev%2Fpredictive-analytics-for-repayment-predictions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarendhiran-dev%2Fpredictive-analytics-for-repayment-predictions/lists"}