{"id":51241012,"url":"https://github.com/celpha2svx/sentinel-fraud-detection","last_synced_at":"2026-06-29T00:03:24.011Z","repository":{"id":331095644,"uuid":"1125246997","full_name":"celpha2svx/sentinel-fraud-detection","owner":"celpha2svx","description":"Cloud-Native Fraud Detection systems(SentinelV3)","archived":false,"fork":false,"pushed_at":"2026-06-05T22:53:28.000Z","size":15633,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-06T00:19:48.568Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://alpha-7g3-sentinel-fraud-detection.hf.space/docs","language":"Jupyter Notebook","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/celpha2svx.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T11:43:59.000Z","updated_at":"2026-06-05T22:53:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/celpha2svx/sentinel-fraud-detection","commit_stats":null,"previous_names":["celpha2svx/sentinel-fraud-detection"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/celpha2svx/sentinel-fraud-detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsentinel-fraud-detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsentinel-fraud-detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsentinel-fraud-detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsentinel-fraud-detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/celpha2svx","download_url":"https://codeload.github.com/celpha2svx/sentinel-fraud-detection/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsentinel-fraud-detection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34907985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-29T00:03:23.372Z","updated_at":"2026-06-29T00:03:24.002Z","avatar_url":"https://github.com/celpha2svx.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ SENTINEL: NIGERIAN FRAUD DETECTION SYSTEM\n\n*AI-Powered Real-Time Fraud Prevention for Nigerian E-Commerce \u0026 Fintech*\n\n![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi\u0026logoColor=white)\n![scikit-learn](https://img.shields.io/badge/scikit--learn-F7931E?logo=scikit-learn\u0026logoColor=white)\n![XGBoost](https://img.shields.io/badge/XGBoost-2C2C2C?logo=xgboost\u0026logoColor=white)\n![Redis](https://img.shields.io/badge/Redis-DC382D?logo=redis\u0026logoColor=white)\n![Google Gemini](https://img.shields.io/badge/Gemini_AI-8E75B2?logo=googlegemini\u0026logoColor=white)\n\n---\n\n## 📘 Table of Contents\n- [The Sentinel Story](#-the-sentinel-story)\n- [Overview](#-overview)\n- [Model Performance](#-model-performance)\n- [Features](#-features)\n- [Technology Stack](#-technology-stack)\n- [Project Structure](#-project-structure)\n- [Getting Started](#-getting-started)\n- [Use Cases](#-use-cases)\n\n---\n\n## 📖 The Sentinel Story\n\nIn the Nigerian fintech landscape, fraud isn't just a \"data problem\"—it’s a sophisticated, evolving challenge that targets specific local behaviors. Traditional, generic fraud models often fail here because they don't understand the nuance of a **USSD transfer at 2:00 AM**, the surge of activity during **Salary Week**, or the high-velocity nature of **Opay/Moniepoint** transactions.\n\n**Sentinel** was built to bridge this gap. It doesn't just look at numbers; it looks at patterns. By combining \"Surgical\" feature engineering (like balance depletion ratios) with a high-performance ensemble of AI models, Sentinel protects both the bank's bottom line and the customer's peace of mind.\n\n\u003e \"We built Sentinel to ensure that a legitimate customer in Lagos can spend their money without friction, while a fraudster in a dark room is blocked before the 'Send' button is even cold.\"\n\n\n---\n\n## 🚀 Overview\n\nSentinel is a production-grade Fraud Detection API that processes transactions in real-time. It uses a **Voting Ensemble (Random Forest + XGBoost + LightGBM)** to predict the probability of fraud with surgical precision.\n\n### Why Sentinel is different:\n* **Locally Contextual:** Engineered specifically for Nigerian banking triggers (USSD, BVN-linkage, Location-based spending).\n* **Explainable AI:** Every \"BLOCK\" decision comes with a human-readable reason and a SHAP-based technical breakdown.\n* **Business First:** Includes a built-in ROI calculator that translates model accuracy into **Naira Saved**.\n\n---\n\n## 📈 Model Performance\n\nWe don't just chase high accuracy; we chase **Precision**. In fraud detection, a \"False Positive\" means a frustrated customer who can't pay for their dinner. Sentinel is tuned to avoid that.\n\n| Metric | Result | Meaning |\n| :--- | :--- | :--- |\n| **AUC-ROC** | **96.7%** | Excellent ability to distinguish between fraud and legit. |\n| **Precision** | **99.8%** | Only 4 \"False Alarms\" out of 12,000+ transactions. |\n| **Recall** | **87.9%** | We catch nearly 9 out of every 10 fraud attempts. |\n| **False Positive Rate** | **0.03%** | Virtually zero friction for legitimate customers. |\n\n**Net Business Impact (Test Set):**\n* **Total Fraud Prevented:** ₦36,165,467.60\n* **Customer Friction Cost:** -₦10,000.00\n* **Net Profit:** **₦36,155,467.60**\n\n---\n\n## ✨ Features\n\n* **⚡ Real-Time Scoring:** Sub-100ms inference using FastAPI and optimized model artifacts.\n* **🧠 Surgical Engineering:** 26+ features including \"Midnight High-Value Shock\" and \"Balance Depletion Ratio.\"\n* **🔗 Redis-Powered Idempotency:** Prevents duplicate processing of transactions during network retries.\n* **🚩 Automated Webhooks:** Sends instant POST alerts to your internal security systems for \"High Risk\" flags.\n* **✍️ AI Executive Summaries:** Integrates **Google Gemini 2.0 Flash** to write professional daily fraud reports for management.\n* **🔍 Explainability (SHAP):** Transparent AI that tells you *why* it flagged a transaction (e.g., \"Amount is 30x higher than typical for Abuja\").\n\n---\n\n## 🛠️ Technology Stack\n\n* **Core:** Python 3.10+, FastAPI\n* **ML/AI:** Scikit-Learn, XGBoost, LightGBM, SHAP, SMOTE (Imbalanced-learn)\n* **Data:** Pandas, NumPy, Parquet\n* **DevOps/Infra:** Redis (Caching), Uvicorn, Dotenv, Procfile (Heroku/Render ready)\n* **Intelligence:** Google Gemini 2.0 (Generative Reports)\n\n---\n\n## 📂 Project Structure\n\n```text\nsentinel-fraud-detection/\n├── data/\n│   ├── nigerian_fraud_sent   # Processed features (Parquet)\n│   └── nigerian_transactions # Raw transaction data\n├── models/\n│   ├── model_infos.json      # Metadata \u0026 Version tracking\n│   ├── sentinel_ensemble     # Trained ensemble model artifact\n│   └── sentinel_v2_Encoder   # Saved LabelEncoders\n├── notebooks/\n│   └── Experiments/\n│       ├── 01_eda_and_features.ipynb # Behavioral Analysis\n│       └── 02_model_training.ipynb   # Model calibration\n├── src/\n│   ├── generator.py          # Synthetic data generation logic\n│   ├── logger.py             # Custom logging utility\n│   └── predictor.py          # Inference wrapper logic\n└── main.py               # FastAPI production server\n├── core_function.py      # Decision logic \u0026 SHAP generators\n├── .env                      # API keys \u0026 Configuration\n├── Features.md               # Detailed feature documentation\n├── Procfile                  # Deployment configuration\n├── README.md                 # Main documentation\n├── requirements.txt          # Python dependencies\n├── sentinel_audit.log        # API transaction logs\n└── test_sentinel.py          # API integration test script\n---\n```\n## 🚀 Getting Started\n\n### Prerequisites\n* **Python 3.10+**: Core programming environment.\n* **Redis Server**: Required for real-time idempotency and transaction caching (defaults to in-memory if Redis is unavailable).\n* **Gemini API Key**: Required for generating the AI Fraud Summary reports.\n\n### Installation\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/celpha2svx/sentinel-fraud-detection.git\n   cd sentinel-fraud-detection\n   \n2. Set up the virtual environment:python -m venv venv\n ```bash\n    # Windows\n    venv\\Scripts\\activate\n    # Mac/Linux\n    source venv/bin/activate\n ```\n3. Install dependencies:\n```\n pip install -r requirements.txt\n```\n4. Configure Environment Variables:\nCreate a .env file in the root directory:\n```\n    GEMINI_API_KEY=your_key_here\n    REDIS_HOST=localhost\n    REDIS_PORT=6379\n ```\n## Usage:\n1. Start the Sentinel Service:\n```\n uvicorn api.main:app --reload\n```\n2. Access the Interactive Docs:\nOpen http://127.0.0.1:8000/docs in your browser to test endpoints via Swagger UI.\n### API Testing\n​Run the automated test script to simulate a high-risk transaction and verify the SHAP explanation engine:\n```\npython test_sentinel.py\n```\n # Use Cases\n* Fintech Wallets: Block \"Midnight Sweeper\" attacks where compromised accounts are drained via USSD while the owner sleeps.\n* E-Commerce Checkouts: Flag high-value orders that deviate significantly from a user's 30-day spending baseline.\n* Agency Banking: Monitor POS terminals for unusual transaction velocity or large withdrawals in high-risk geographical zones. License \n#### This project is licensed under the MIT License - see the LICENSE file for details.\n​Sentinel: Protecting the pulse of Nigerian Digital Finance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fsentinel-fraud-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelpha2svx%2Fsentinel-fraud-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fsentinel-fraud-detection/lists"}