Sync from GitHub: 564e0e9e7b5ba7ec7b40c0e05479a97951f38ffd

.gitattributes

@@ -1,35 +1,6 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
 *.gz filter=lfs diff=lfs merge=lfs -text
 *.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,419 @@
+# CloverShield ML API Deployment Guide
+
+Complete guide for deploying the ML Inference API to various platforms.
+
+## 📋 Prerequisites
+
+- Docker installed (for containerized deployment)
+- Model file: `Models/fraud_pipeline_final.pkl`
+- Environment variables configured
+- Platform account (Vercel/Render/Railway)
+
+## 🐳 Docker Deployment
+
+### Local Docker
+
+```bash
+# Build image
+docker build -t clovershield-ml-api .
+
+# Run container
+docker run -d \
+  --name clovershield-api \
+  -p 8000:8000 \
+  -v $(pwd)/Models:/app/Models \
+  -e GROQ_API_KEY=your-key \
+  clovershield-ml-api
+
+# Check logs
+docker logs clovershield-api
+
+# Test
+curl http://localhost:8000/health
+```
+
+### Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  ml-api:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./Models:/app/Models
+    environment:
+      - MODEL_PATH=Models/fraud_pipeline_final.pkl
+      - GROQ_API_KEY=${GROQ_API_KEY}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+Run:
+```bash
+docker-compose up -d
+```
+
+## ☁️ Platform-Specific Deployment
+
+### Option 1: Render.com (Recommended)
+
+**Pros:**
+- Easy setup
+- Good for ML workloads
+- Free tier available
+- Supports Docker
+
+**Steps:**
+
+1. **Create Account**: Sign up at [render.com](https://render.com)
+
+2. **Create New Web Service**:
+   - Connect GitHub repository
+   - Select "Docker" as environment
+   - Use `render.yaml` configuration
+
+3. **Configure Environment Variables**:
+   ```
+   MODEL_PATH=Models/fraud_pipeline_final.pkl
+   MODEL_THRESHOLD=0.00754482
+   GROQ_API_KEY=your-key-here
+   ```
+
+4. **Deploy**:
+   - Render will auto-detect `render.yaml`
+   - Build and deploy automatically
+   - Get public URL: `https://clovershield-ml-api.onrender.com`
+
+5. **Update Model File**:
+   - Upload model to cloud storage (S3, etc.)
+   - Modify Dockerfile to download on startup
+   - Or use Render's persistent disk
+
+**Model File Options:**
+- **Option A**: Include in Docker image (not recommended - large)
+- **Option B**: Download from S3/GCS on startup
+- **Option C**: Use Render persistent disk
+
+### Option 2: Railway.app
+
+**Pros:**
+- Simple deployment
+- Good developer experience
+- Automatic HTTPS
+
+**Steps:**
+
+1. **Create Account**: Sign up at [railway.app](https://railway.app)
+
+2. **Create New Project**:
+   - Connect GitHub repository
+   - Railway auto-detects `railway.json`
+
+3. **Configure Environment Variables**:
+   - Go to Variables tab
+   - Add required variables
+
+4. **Deploy**:
+   - Railway builds and deploys automatically
+   - Get public URL: `https://clovershield-ml-api.up.railway.app`
+
+### Option 3: Vercel (Limited)
+
+**Pros:**
+- Fast deployment
+- Great for frontend
+
+**Cons:**
+- Limited for ML workloads
+- Serverless function timeout limits
+- Model size restrictions
+
+**Steps:**
+
+1. **Install Vercel CLI**: `npm i -g vercel`
+
+2. **Deploy**:
+   ```bash
+   vercel
+   ```
+
+3. **Configure**:
+   - Set environment variables in dashboard
+   - Note: Model file must be < 50MB
+
+**Note**: Vercel is not ideal for ML APIs. Use Render or Railway instead.
+
+### Option 4: AWS/GCP/Azure
+
+For production deployments, consider:
+
+- **AWS**: ECS, EKS, or Lambda (with container support)
+- **GCP**: Cloud Run or GKE
+- **Azure**: Container Instances or AKS
+
+## 🔧 Model File Management
+
+### Option 1: Include in Docker Image
+
+**Pros**: Simple  
+**Cons**: Large image size, slower builds
+
+```dockerfile
+COPY Models/fraud_pipeline_final.pkl Models/
+```
+
+### Option 2: Download from Cloud Storage
+
+**Pros**: Smaller image, flexible  
+**Cons**: Requires cloud storage setup
+
+Modify `main.py` startup:
+
+```python
+import boto3
+import os
+
+def download_model():
+    s3 = boto3.client('s3')
+    s3.download_file('your-bucket', 'fraud_pipeline_final.pkl', 'Models/fraud_pipeline_final.pkl')
+```
+
+### Option 3: Environment Variable Path
+
+**Pros**: Flexible  
+**Cons**: Requires manual setup
+
+Set `MODEL_PATH` to point to mounted volume or cloud path.
+
+## 🔒 Production Security
+
+### 1. API Authentication
+
+Add API key middleware:
+
+```python
+from fastapi import Header, HTTPException
+
+API_KEY = os.getenv("API_KEY")
+
+@app.middleware("http")
+async def verify_api_key(request: Request, call_next):
+    if request.url.path.startswith("/docs"):
+        return await call_next(request)
+    
+    api_key = request.headers.get("X-API-Key")
+    if api_key != API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    
+    return await call_next(request)
+```
+
+### 2. Rate Limiting
+
+Install: `pip install slowapi`
+
+```python
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+@app.post("/predict")
+@limiter.limit("10/minute")
+async def predict(...):
+    ...
+```
+
+### 3. HTTPS
+
+- Use platform's built-in HTTPS (Render, Railway)
+- Or configure reverse proxy (nginx, Traefik)
+
+### 4. Monitoring
+
+Add logging and monitoring:
+
+```python
+import logging
+from prometheus_client import Counter, Histogram
+
+request_count = Counter('requests_total', 'Total requests')
+request_duration = Histogram('request_duration_seconds', 'Request duration')
+
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    duration = time.time() - start_time
+    request_duration.observe(duration)
+    request_count.inc()
+    return response
+```
+
+## 📊 Health Checks
+
+All platforms support health checks:
+
+```bash
+# Test health endpoint
+curl https://your-api-url.com/health
+
+# Expected response
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "model_version": "1.0.0"
+}
+```
+
+## 🧪 Testing Deployment
+
+### 1. Health Check
+
+```bash
+curl https://your-api-url.com/health
+```
+
+### 2. Prediction Test
+
+```bash
+curl -X POST https://your-api-url.com/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transaction": {
+      "step": 1,
+      "type": "TRANSFER",
+      "amount": 5000.00,
+      "nameOrig": "C123456789",
+      "oldBalanceOrig": 50000.00,
+      "newBalanceOrig": 45000.00,
+      "nameDest": "C234567890",
+      "oldBalanceDest": 25000.00,
+      "newBalanceDest": 30000.00
+    }
+  }'
+```
+
+### 3. Load Testing
+
+Use `ab` (Apache Bench) or `wrk`:
+
+```bash
+# Install
+brew install wrk  # macOS
+# or
+apt-get install apache2-utils  # Linux
+
+# Test
+wrk -t4 -c100 -d30s --script=test.lua https://your-api-url.com/predict
+```
+
+## 🐛 Troubleshooting
+
+### Model Not Loading
+
+**Symptoms**: `503 Model not loaded` error
+
+**Solutions**:
+1. Check `MODEL_PATH` environment variable
+2. Verify model file exists in container
+3. Check file permissions
+4. Review container logs
+
+### Out of Memory
+
+**Symptoms**: Container crashes, OOM errors
+
+**Solutions**:
+1. Increase container memory limit
+2. Use model quantization
+3. Implement model caching
+4. Scale horizontally
+
+### Slow Response Times
+
+**Symptoms**: High latency
+
+**Solutions**:
+1. Optimize model (quantization, pruning)
+2. Use faster hardware (GPU if available)
+3. Implement caching
+4. Optimize feature engineering
+
+### CORS Errors
+
+**Symptoms**: Frontend can't call API
+
+**Solutions**:
+1. Configure CORS in `main.py`
+2. Add frontend domain to allowed origins
+3. Check platform CORS settings
+
+## 📈 Scaling
+
+### Horizontal Scaling
+
+- Use load balancer
+- Deploy multiple instances
+- Use platform auto-scaling
+
+### Vertical Scaling
+
+- Increase container resources
+- Use faster CPU/GPU
+- Optimize model
+
+## ✅ Deployment Checklist
+
+- [ ] Model file accessible
+- [ ] Environment variables set
+- [ ] Health check working
+- [ ] API endpoints responding
+- [ ] CORS configured
+- [ ] Authentication enabled (production)
+- [ ] Rate limiting configured
+- [ ] Monitoring set up
+- [ ] Logs accessible
+- [ ] HTTPS enabled
+- [ ] Backup strategy in place
+
+## 🚀 Quick Deploy Commands
+
+### Render
+
+```bash
+# Using Render CLI
+render deploy
+```
+
+### Railway
+
+```bash
+# Using Railway CLI
+railway up
+```
+
+### Docker Hub + Any Platform
+
+```bash
+# Build and push
+docker build -t your-username/clovershield-ml-api .
+docker push your-username/clovershield-ml-api
+
+# Deploy to platform using image
+```
+
+---
+
+**Status**: Ready for deployment! 🚀
+

Dockerfile

@@ -0,0 +1,55 @@
+# CloverShield ML Inference API Dockerfile
+# Optimized for Python 3.9 and Hugging Face Spaces
+
+FROM python:3.9-slim
+
+# Create a non-root user (user 1000) to comply with HF security context
+RUN useradd -m -u 1000 user
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (for better Docker layer caching)
+COPY requirements.txt .
+
+# Install Python dependencies as the non-root user
+RUN pip install --upgrade pip && \
+    pip install -r requirements.txt
+
+# Copy application code
+COPY --chown=user . .
+
+# Create directory for model (if not exists) and ensure permissions
+RUN mkdir -p Models && chown -R user:user /app
+
+# Copy and set up entrypoint script
+COPY --chown=user entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Switch to the non-root user
+USER user
+
+# Expose port 7860 (Hugging Face Spaces standard)
+EXPOSE 7860
+
+# Health check (uses PORT env var, defaults to 7860)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD python -c "import os, urllib.request; port=os.getenv('PORT', '7860'); urllib.request.urlopen(f'http://localhost:{port}/health')" || exit 1
+
+# Run the application using entrypoint script
+ENTRYPOINT ["/entrypoint.sh"]
+

HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,123 @@
+# Deploying CloverShield ML API to Hugging Face Spaces
+
+This guide outlines the steps to migrate the backend ML API from Render to Hugging Face Spaces using the Docker SDK.
+
+## Prerequisites
+
+- A [Hugging Face account](https://huggingface.co/join).
+- The `ml-api` folder ready with the updated `Dockerfile` and `README.md`.
+
+## Step 1: Create a New Space
+
+1. Log in to your Hugging Face account.
+2. Click on your profile picture in the top right and select **"New Space"**.
+3. Fill in the details:
+   - **Space Name:** `clovershield-ml-api` (or similar).
+   - **License:** MIT or Apache 2.0 (matches your project).
+   - **Space SDK:** Select **Docker**.
+   - **Space Hardware:** **CPU Basic (Free)** is usually sufficient for this model size (2MB). If performance is slow, you can upgrade later.
+   - **Visibility:** **Public** or **Private** (Private is safer for internal testing, but you might need a token to access it from the frontend). For the hackathon demo, **Public** is easiest but be careful with keys. **Private** is recommended if you can handle authentication headers in your frontend.
+
+4. Click **"Create Space"**.
+
+## Step 2: Upload Files
+
+You have two options to upload the code:
+
+### Option A: Web Interface (Easiest)
+
+1. Once the Space is created, you will see the instructions page. Click on the **"Files"** tab.
+2. Click **"Add file"** > **"Upload files"**.
+3. Drag and drop **ALL** files and folders from your local `ml-api` directory into the upload area.
+   - **Important:** Ensure you include:
+     - `Dockerfile`
+     - `requirements.txt`
+     - `main.py`
+     - `inference.py`
+     - `feature_engineering.py`
+     - `entrypoint.sh`
+     - `README.md`
+     - `Models/fraud_pipeline_final.pkl` (The folder structure `Models/` must be preserved).
+     - `dataset/test_dataset.csv` (If used).
+4. In the "Commit changes" box, type "Initial commit" and click **"Commit changes to main"**.
+
+### Option B: Git Command Line (Manual)
+
+1. Clone the Space repository locally.
+2. Copy files and push manually.
+
+### Option C: Automatic Sync with GitHub (Recommended)
+
+This method automatically updates your Space whenever you push code to GitHub.
+
+1.  **Get a Hugging Face Access Token:**
+    *   Go to [Hugging Face Settings > Access Tokens](https://huggingface.co/settings/tokens).
+    *   Click "New token".
+    *   Name it `GITHUB_ACTION` (or similar).
+    *   **Permissions:** Select **"Write"** access.
+    *   Copy the token (starts with `hf_...`).
+
+2.  **Add Token to GitHub Secrets:**
+    *   Go to your GitHub repository.
+    *   Navigate to **Settings** > **Secrets and variables** > **Actions**.
+    *   Click **"New repository secret"**.
+    *   **Name:** `HF_TOKEN`
+    *   **Value:** (Paste your Hugging Face token here).
+    *   Click "Add secret".
+
+3.  **Configure the Workflow:**
+    *   Open the file `.github/workflows/deploy-ml-api.yml` in your project.
+    *   Edit the `env` section to match your details:
+        ```yaml
+        HF_SPACE_USERNAME: "your-hf-username"
+        HF_SPACE_NAME: "clovershield-ml-api"
+        ```
+    *   Commit and push this change to GitHub.
+
+Now, whenever you push changes to the `ml-api` folder in GitHub, the Action will run and update your Hugging Face Space automatically.
+
+## Step 3: Configure Environment Variables (Secrets)
+
+Your API needs the `GROQ_API_KEY` to function if LLM explanations are enabled.
+
+1. Go to the **"Settings"** tab of your Space.
+2. Scroll down to the **"Variables and secrets"** section.
+3. Click **"New secret"**.
+   - **Name:** `GROQ_API_KEY`
+   - **Value:** (Paste your Groq API key here)
+4. (Optional) Add other variables if you changed defaults:
+   - `MODEL_THRESHOLD`
+   - `PAGERANK_LIMIT`
+
+**Note:** Hugging Face automatically sets `PORT` to `7860`. Our updated `Dockerfile` and `entrypoint.sh` are configured to respect this.
+
+## Step 4: Build and Verify
+
+1. Go to the **"App"** tab.
+2. You will see a "Building" status. Click "Logs" to watch the build process.
+3. Once "Running", you should see the Swagger UI or the JSON response from the root endpoint in the preview window.
+4. Your API URL will be: `https://<your-username>-clovershield-ml-api.hf.space`
+
+## Step 5: Update Frontend Connection (Vercel)
+
+Now that your backend is on HF Spaces, you need to update your Vercel deployment to point to the new URL.
+
+1.  **Go to Vercel Dashboard:**
+    *   Navigate to your project on [Vercel](https://vercel.com).
+    *   Go to **Settings** > **Environment Variables**.
+
+2.  **Update the Variable:**
+    *   Find the existing `NEXT_PUBLIC_ML_API_URL` or create a new one.
+    *   **Value:** `https://<your-username>-<your-space-name>.hf.space`
+    *   *Important:* Do NOT include a trailing slash (/) at the end.
+
+3.  **Redeploy:**
+    *   Go to the **Deployments** tab.
+    *   Click on the three dots (...) of your latest deployment and select **Redeploy**. This is necessary for Vercel to pick up the new environment variable value in the client-side code.
+
+## Troubleshooting
+
+- **Build Fails:** Check the "Logs". Common issues are missing dependencies in `requirements.txt` or file path errors.
+- **"403 Forbidden":** If your Space is **Private**, you cannot access it directly from a public frontend without passing an authorization header (Bearer token). For this hackathon/demo, switch the Space Visibility to **Public** in Settings > General.
+- **Model Load Error:** Ensure `Models/fraud_pipeline_final.pkl` was actually uploaded. Check the "Files" tab.
+

Models/fraud_pipeline_final.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:817193f2758c331d61f6749771a821ad1eb790c7aace69a3982b7282aa7f7e27
+size 2259837

QUICK_START.md

@@ -0,0 +1,92 @@
+# ML API Quick Start
+
+Quick reference for deploying CloverShield ML Inference API.
+
+## ✅ What's Included
+
+- ✅ FastAPI service with `/predict` endpoint
+- ✅ Docker containerization
+- ✅ Deployment configs for Render/Railway/Vercel
+- ✅ Complete documentation
+
+## 🚀 Deploy in 5 Minutes
+
+### Option 1: Render.com (Recommended)
+
+1. **Sign up** at [render.com](https://render.com)
+2. **Create Web Service** → Connect GitHub repo
+3. **Configure**:
+   - Environment: Docker
+   - Build Command: (auto-detected)
+   - Start Command: (auto-detected)
+4. **Set Environment Variables**:
+   ```
+   MODEL_PATH=Models/fraud_pipeline_final.pkl
+   GROQ_API_KEY=your-key (optional)
+   ```
+5. **Deploy** → Get URL: `https://your-app.onrender.com`
+
+### Option 2: Railway.app
+
+1. **Sign up** at [railway.app](https://railway.app)
+2. **New Project** → Connect GitHub
+3. **Railway auto-detects** `railway.json`
+4. **Set environment variables** in dashboard
+5. **Deploy** → Get URL automatically
+
+### Option 3: Local Docker
+
+```bash
+# Build
+docker build -t clovershield-ml-api .
+
+# Run
+docker run -p 8000:8000 \
+  -v $(pwd)/Models:/app/Models \
+  clovershield-ml-api
+
+# Test
+curl http://localhost:8000/health
+```
+
+## 📝 API Usage
+
+### Health Check
+```bash
+curl https://your-api-url.com/health
+```
+
+### Predict Fraud
+```bash
+curl -X POST https://your-api-url.com/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transaction": {
+      "step": 1,
+      "type": "TRANSFER",
+      "amount": 5000.00,
+      "nameOrig": "C123456789",
+      "oldBalanceOrig": 50000.00,
+      "newBalanceOrig": 45000.00,
+      "nameDest": "C234567890",
+      "oldBalanceDest": 25000.00,
+      "newBalanceDest": 30000.00
+    }
+  }'
+```
+
+## 📚 Full Documentation
+
+- [README.md](./README.md) - Complete API documentation
+- [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) - Detailed deployment guide
+
+## ✅ Checklist
+
+- [ ] Model file available (`Models/fraud_pipeline_final.pkl`)
+- [ ] Environment variables configured
+- [ ] API deployed and accessible
+- [ ] Health check passing
+- [ ] Test prediction working
+
+**Ready to deploy!** 🚀
+

README.md

@@ -1,11 +1,310 @@
 ---
-title: Clovershield Ml Api
-emoji: 🔥
-colorFrom: purple
-colorTo: yellow
+title: CloverShield ML API
+emoji: 🛡️
+colorFrom: green
+colorTo: blue
 sdk: docker
-pinned: false
-license: apache-2.0
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CloverShield ML Inference API
+
+FastAPI microservice for fraud detection predictions. This service replaces the local model loading mechanism in the Streamlit app.
+
+## 🚀 Quick Start
+
+### Local Development
+
+1. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Copy model file:**
+   ```bash
+   cp ../Models/fraud_pipeline_final.pkl Models/
+   ```
+
+3. **Set environment variables:**
+   ```bash
+   cp env.template .env
+   # Edit .env with your values
+   ```
+
+4. **Run the API:**
+   ```bash
+   python main.py
+   # Or
+   uvicorn main:app --reload
+   ```
+
+5. **Test the API:**
+   ```bash
+   curl http://localhost:8000/health
+   ```
+
+### Docker
+
+1. **Build the image:**
+   ```bash
+   docker build -t clovershield-ml-api . 
+   ```
+
+2. **Run the container:**
+   ```bash
+   docker run -p 8000:8000 \
+     -v $(pwd)/Models:/app/Models \
+     -e GROQ_API_KEY=your-key \
+     clovershield-ml-api
+   ```
+
+## 📚 API Endpoints
+
+### `GET /`
+Root endpoint - service information
+
+### `GET /health`
+Health check endpoint
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "model_version": "1.0.0",
+  "shap_available": true,
+  "llm_available": true
+}
+```
+
+### `GET /model/info`
+Get model metadata
+
+### `POST /predict`
+Predict fraud probability for a single transaction
+
+**Request:**
+```json
+{
+  "transaction": {
+    "step": 1,
+    "type": "CASH_OUT",
+    "amount": 5000.00,
+    "nameOrig": "C123456789",
+    "oldBalanceOrig": 50000.00,
+    "newBalanceOrig": 45000.00,
+    "nameDest": "C234567890",
+    "oldBalanceDest": 25000.00,
+    "newBalanceDest": 30000.00
+  },
+  "options": {
+    "include_shap": true,
+    "include_llm_explanation": false,
+    "language": "en",
+    "topk": 10
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
+  "prediction": {
+    "fraud_probability": 0.2345,
+    "decision": "pass",
+    "risk_level": "low",
+    "confidence": 0.85
+  },
+  "shap_explanations": [
+    {
+      "feature": "amount_over_oldBalanceOrig",
+      "value": 0.1,
+      "shap": 0.0234,
+      "shap_abs": 0.0234,
+      "rank": 1
+    }
+  ],
+  "llm_explanation": null,
+  "processing_time_ms": 145,
+  "model_version": "1.0.0",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### `POST /predict/batch`
+Predict fraud probability for multiple transactions
+
+## 🐳 Docker Deployment
+
+### Build and Push to Registry
+
+```bash
+# Build
+docker build -t clovershield-ml-api:latest . 
+
+# Tag for registry
+docker tag clovershield-ml-api:latest your-registry/clovershield-ml-api:latest
+
+# Push
+docker push your-registry/clovershield-ml-api:latest
+```
+
+## ☁️ Platform Deployment
+
+### Hugging Face Spaces (Recommended)
+
+1. Create a new Space on Hugging Face.
+2. Select "Docker" as the SDK.
+3. Upload the contents of this directory to the Space.
+4. Set the `GROQ_API_KEY` secret in the Space settings.
+
+
+### Vercel
+
+1. Install Vercel CLI: `npm i -g vercel`
+2. Deploy: `vercel`
+3. Set environment variables in Vercel dashboard
+
+**Note:** Vercel has limitations for ML models. Consider Render or Railway for better performance.
+
+### Render
+
+1. Connect your GitHub repository
+2. Create new Web Service
+3. Use `render.yaml` configuration
+4. Set environment variables in dashboard
+5. Deploy
+
+### Railway
+
+1. Connect your GitHub repository
+2. Create new project
+3. Railway will auto-detect `railway.json`
+4. Set environment variables
+5. Deploy
+
+## 🔧 Configuration
+
+### Environment Variables
+
+- `MODEL_PATH` - Path to model file (default: `Models/fraud_pipeline_final.pkl`)
+- `TEST_DATASET_PATH` - Path to test dataset CSV for feature engineering (optional, auto-detected if not provided)
+- `MODEL_THRESHOLD` - Decision threshold (default: `0.00754482` - optimized for 99% recall)
+- `PORT` - Server port (default: `8000`)
+- `HOST` - Server host (default: `0.0.0.0`)
+- `GROQ_API_KEY` - Optional Groq API key for LLM explanations
+- `PAGERANK_LIMIT` - Optional limit on nodes for PageRank computation (for memory optimization)
+- `MAX_FIT_ROWS` - Maximum rows to use for feature engineering fitting (default: `50000`)
+
+### Model File
+
+The model file (`fraud_pipeline_final.pkl`) must be available at runtime. Options:
+
+1. **Include in Docker image** (not recommended for large files)
+2. **Mount as volume** (Docker)
+3. **Download from cloud storage** (S3, GCS, etc.)
+4. **Use environment variable** to specify path
+
+## 📊 API Documentation
+
+Interactive API documentation available at:
+- Swagger UI: `http://localhost:8000/docs`
+- ReDoc: `http://localhost:8000/redoc`
+
+## 🧪 Testing
+
+### Test with curl
+
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# Prediction
+curl -X POST http://localhost:8000/predict \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transaction": {
+      "step": 1,
+      "type": "TRANSFER",
+      "amount": 5000.00,
+      "nameOrig": "C123456789",
+      "oldBalanceOrig": 50000.00,
+      "newBalanceOrig": 45000.00,
+      "nameDest": "C234567890",
+      "oldBalanceDest": 25000.00,
+      "newBalanceDest": 30000.00
+    }
+  }'
+```
+
+### Test with Python
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8000/predict",
+    json={
+        "transaction": {
+            "step": 1,
+            "type": "TRANSFER",
+            "amount": 5000.00,
+            "nameOrig": "C123456789",
+            "oldBalanceOrig": 50000.00,
+            "newBalanceOrig": 45000.00,
+            "nameDest": "C234567890",
+            "oldBalanceDest": 25000.00,
+            "newBalanceDest": 30000.00
+        }
+    }
+)
+
+print(response.json())
+```
+
+## 🔒 Security
+
+**Production Recommendations:**
+- Add API key authentication for production
+- Use HTTPS in production
+- Implement rate limiting
+- Validate all inputs
+- Monitor for abuse
+- Restrict CORS origins (currently set to `["*"` for development)
+- Use environment variables for sensitive data
+
+## 📈 Performance
+
+**Optimization Tips:**
+- Model loads once on startup (lazy loading supported for serverless)
+- Single worker recommended (ML models are not thread-safe)
+- Consider caching for frequently accessed data
+- Monitor memory usage (XGBoost models can be large)
+- Feature engineering uses sampled dataset (configurable via `MAX_FIT_ROWS`)
+- SHAP background uses minimal sample size (100 rows) for efficiency
+
+## 🐛 Troubleshooting
+
+### Model not loading
+
+- Check `MODEL_PATH` environment variable
+- Verify model file exists
+- Check file permissions
+- Review logs for error messages
+
+### SHAP not working
+
+- Ensure XGBoost is installed
+- Check model type compatibility
+- Review SHAP initialization logs
+
+### LLM explanations failing
+
+- Verify `GROQ_API_KEY` is set
+- Check API key validity
+- Review Groq API status
+
+## 📝 License
+
+See main project LICENSE file.

dataset/test_dataset.csv.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ce99ce839f2f1f427668dd8e4fd7d74b975395222082356e38c89c326bfba36
+size 4033802

entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Entrypoint script for CloverShield ML API
+# Reads PORT from environment variable (required by Render)
+
+PORT=${PORT:-8000}
+HOST=${HOST:-0.0.0.0}
+
+echo "🚀 Starting CloverShield ML API"
+echo "📋 Configuration: HOST=$HOST, PORT=$PORT"
+echo "⏳ Server will start, model will load on startup..."
+echo "💡 Note: First request may take longer if model is still loading"
+
+# Start uvicorn with the PORT from environment
+# Use --log-level info for better visibility
+exec uvicorn main:app --host "$HOST" --port "$PORT" --workers 1 --log-level info
+

env.template

@@ -0,0 +1,25 @@
+# CloverShield ML API Environment Variables
+# Copy this file to .env and fill in your values
+
+# Model Configuration
+MODEL_PATH=Models/fraud_pipeline_final.pkl
+MODEL_THRESHOLD=0.00754482
+
+# Server Configuration
+PORT=8000
+HOST=0.0.0.0
+
+# Memory Optimization (for limited RAM environments like Render free tier)
+# Maximum number of rows to use for fitting feature engineer (default: 50000)
+# Reduce this if you're running out of RAM (e.g., 20000 or 10000)
+MAX_FIT_ROWS=50000
+# Limit PageRank computation to top N nodes (default: 10000, set to 0 to disable limit)
+# Reduce this for very large graphs to save memory (e.g., 5000)
+PAGERANK_LIMIT=10000
+
+# LLM Explanations (Optional)
+GROQ_API_KEY=your-groq-api-key-here
+
+# API Authentication (Optional - add if implementing auth)
+# API_KEY=your-api-key-here
+

feature_engineering.py

@@ -0,0 +1,166 @@
+"""
+Feature Engineering Module for Fraud Detection
+Defines FraudFeatureEngineer class for model pipeline compatibility
+"""
+
+import pandas as pd
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+from typing import Optional
+import networkx as nx
+
+
+class FraudFeatureEngineer(BaseEstimator, TransformerMixin):
+    """
+    Vectorized, deterministic feature transformer.
+    - Builds weighted directed graph (aggregated by (origin,dest) counts)
+    - Creates frequency, ratio, log and graph features
+    """
+    
+    def __init__(self, pagerank_limit=None):
+        """
+        Initialize the feature engineer
+        
+        Args:
+            pagerank_limit: Optional limit on number of nodes for PageRank computation
+        """
+        self.pagerank_limit = pagerank_limit
+        self.stats = {}
+        self.graph_meta = {}
+        self.type_map = {'TRANSFER': 0, 'CASH_OUT': 1}
+        self.global_mean = 0.0
+        self.global_median = 0.0
+    
+    def fit(self, X, y=None):
+        """
+        Fit the feature engineer on training/test data (memory-optimized)
+        
+        Args:
+            X: Input DataFrame with raw transaction data
+            y: Optional target variable (not used)
+            
+        Returns:
+            self
+        """
+        # Memory optimization: work with views where possible, avoid unnecessary copies
+        # Only copy if we need to modify (sorting)
+        if 'step' in X.columns:
+            # Sort in-place if possible, or use a view
+            X_sorted = X.sort_values('step', kind='mergesort')  # Stable sort
+        else:
+            X_sorted = X
+
+        # Basic global stats (compute once, reuse)
+        self.global_mean = float(X_sorted['amount'].mean())
+        self.global_median = float(X_sorted['amount'].median())
+
+        # Frequency & mean - use memory-efficient operations
+        self.stats['orig_counts'] = X_sorted['nameOrig'].value_counts().to_dict()
+        self.stats['dest_counts'] = X_sorted['nameDest'].value_counts().to_dict()
+        
+        # Groupby operations - compute once, store as dicts
+        orig_groups = X_sorted.groupby('nameOrig')['amount']
+        self.stats['orig_mean_amt'] = orig_groups.mean().to_dict()
+        self.stats['orig_median_amt'] = orig_groups.median().to_dict()
+        self.stats['orig_log_median_amt'] = orig_groups.apply(lambda s: np.log1p(s).median()).to_dict()
+        
+        if 'step' in X_sorted.columns:
+            self.stats['last_step'] = X_sorted.groupby('nameOrig')['step'].last().to_dict()
+        else:
+            self.stats['last_step'] = {}
+
+        # Weighted graph: count transactions per (origin,dest) - memory efficient
+        # Use value_counts on tuples for edge weights (more memory efficient)
+        edge_counts = X_sorted.groupby(['nameOrig', 'nameDest']).size()
+        
+        # Build graph directly from edge counts (avoid intermediate DataFrame)
+        G = nx.DiGraph()
+        if len(edge_counts) > 0:
+            # Add edges directly from the Series (more memory efficient)
+            for (orig, dest), weight in edge_counts.items():
+                G.add_edge(orig, dest, weight=float(weight))
+
+        # Store degree dictionaries (memory efficient)
+        self.graph_meta['in_degree'] = dict(G.in_degree(weight='weight'))
+        self.graph_meta['out_degree'] = dict(G.out_degree(weight='weight'))
+
+        # Pagerank: limit nodes if requested to save time/memory
+        # Default to limiting if graph is large
+        default_pagerank_limit = 10000  # Limit to top 10k nodes by default
+        try:
+            if G.number_of_nodes() == 0:
+                self.graph_meta['pagerank'] = {}
+            else:
+                # Use pagerank_limit if set, otherwise use default limit for large graphs
+                effective_limit = self.pagerank_limit if self.pagerank_limit else default_pagerank_limit
+                
+                if effective_limit < G.number_of_nodes():
+                    # Only compute PageRank on top nodes by degree
+                    top_nodes = sorted(G.degree(weight='weight'), key=lambda x: x[1], reverse=True)[:effective_limit]
+                    keep = set(n for n, _ in top_nodes)
+                    sub = G.subgraph(keep).copy()
+                    self.graph_meta['pagerank'] = nx.pagerank(sub, alpha=0.85, weight='weight', tol=1e-4)
+                    print(f"📊 PageRank computed on {len(keep):,} top nodes (graph has {G.number_of_nodes():,} total nodes)")
+                else:
+                    self.graph_meta['pagerank'] = nx.pagerank(G, alpha=0.85, weight='weight', tol=1e-4)
+        except Exception as e:
+            # Pagerank failure should not break training
+            print(f"⚠️ PageRank computation failed: {str(e)}, using empty pagerank")
+            self.graph_meta['pagerank'] = {}
+
+        return self
+    
+    def transform(self, X):
+        """
+        Transform input data by engineering features
+        
+        Args:
+            X: Input DataFrame with raw transaction data
+            
+        Returns:
+            DataFrame with engineered features matching the training feature set
+        """
+        X = X.copy()
+
+        # Time features
+        X['hour'] = X['step'] % 24 if 'step' in X.columns else 0
+        
+        # Frequency mapping
+        X['orig_txn_count'] = X['nameOrig'].map(self.stats.get('orig_counts', {})).fillna(0).astype(int)
+        X['dest_txn_count'] = X['nameDest'].map(self.stats.get('dest_counts', {})).fillna(0).astype(int)
+
+        # Ratio features
+        user_mean = X['nameOrig'].map(self.stats.get('orig_mean_amt', {})).fillna(self.global_mean)
+        X['amt_ratio_to_user_mean'] = X['amount'] / (user_mean + 1.0)
+        X['amount_log1p'] = np.log1p(X['amount'])
+        X['amount_over_oldBalanceOrig'] = X['amount'] / (X['oldBalanceOrig'].replace(0, np.nan).fillna(1.0))
+        
+        user_median = X['nameOrig'].map(self.stats.get('orig_median_amt', {})).fillna(self.global_median)
+        # Apply fallback to global median for users with too few transactions
+        MIN_TXNS = 3
+        user_median = np.where(X['orig_txn_count'] >= MIN_TXNS, user_median, self.global_median)
+        X['amt_ratio_to_user_median'] = (X['amount'] / (user_median + 1.0))
+        
+        user_log_median = X['nameOrig'].map(self.stats.get('orig_log_median_amt', {})).fillna(np.log1p(self.global_median))
+        X['amt_log_ratio_to_user_median'] = (np.log1p(X['amount']) / (user_log_median + 1e-6))
+
+        # Graph features
+        X['in_degree'] = X['nameDest'].map(self.graph_meta.get('in_degree', {})).fillna(0).astype(float)
+        X['out_degree'] = X['nameOrig'].map(self.graph_meta.get('out_degree', {})).fillna(0).astype(float)
+        X['network_trust'] = X['nameOrig'].map(self.graph_meta.get('pagerank', {})).fillna(0.0).astype(float)
+
+        # New/novelty flags
+        X['is_new_origin'] = (X['orig_txn_count'] == 0).astype(int)
+        X['is_new_dest'] = (X['dest_txn_count'] == 0).astype(int)
+
+        # Type encoding (fast & vectorized)
+        X['type_encoded'] = X['type'].map(self.type_map).fillna(-1).astype(int)
+
+        # Drop identifiers and non-numeric columns
+        for c in ['nameOrig', 'nameDest', 'type', 'isFlaggedFraud']:
+            if c in X.columns:
+                X.drop(columns=c, inplace=True)
+
+        # Return numeric-only DataFrame expected by XGBoost & SHAP
+        return X.select_dtypes(include=[np.number])
+

inference.py

@@ -0,0 +1,590 @@
+"""
+Inference Module for Fraud Detection Pipeline
+Adapted for FastAPI microservice
+"""
+
+import os
+import gc
+import numpy as np
+import pandas as pd
+import joblib
+import warnings
+from typing import Dict, Optional, Tuple
+
+# Suppress warnings
+warnings.filterwarnings('ignore', message='.*is_sparse.*', category=FutureWarning)
+warnings.filterwarnings('ignore', message='is_sparse is deprecated')
+
+# Core imports
+try:
+    from feature_engineering import FraudFeatureEngineer
+except ImportError:
+    from sklearn.base import BaseEstimator, TransformerMixin
+    
+    class FraudFeatureEngineer(BaseEstimator, TransformerMixin):
+        """Fallback feature engineer if import fails"""
+        def fit(self, X, y=None):
+            return self
+        def transform(self, X):
+            return X
+
+# Optional imports
+try:
+    import shap
+    SHAP_AVAILABLE = True
+except ImportError:
+    SHAP_AVAILABLE = False
+
+try:
+    from groq import Groq
+    GROQ_AVAILABLE = True
+except ImportError:
+    GROQ_AVAILABLE = False
+
+try:
+    import xgboost as xgb
+    XGBOOST_AVAILABLE = True
+except ImportError:
+    XGBOOST_AVAILABLE = False
+
+# Load environment variables
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+
+class FraudInference:
+    """
+    Inference class for fraud detection pipeline with explainability
+    Uses fitted feature engineer and XGBoost model separately
+    """
+    
+    def __init__(
+        self, 
+        model_path: str, 
+        test_dataset_path: Optional[str] = None,
+        threshold: float = 0.0793, 
+        groq_api_key: Optional[str] = None,
+        pagerank_limit: Optional[int] = None
+    ):
+        """
+        Initialize inference engine
+        
+        Args:
+            model_path: Path to the saved XGBoost model pkl file
+            test_dataset_path: Path to test dataset CSV for fitting feature engineer
+            threshold: Decision threshold for fraud classification
+            groq_api_key: Optional Groq API key for LLM explanations
+            pagerank_limit: Optional limit on nodes for PageRank computation
+        """
+        self.model_path = model_path
+        self.test_dataset_path = test_dataset_path
+        self.threshold = threshold
+        self.groq_api_key = groq_api_key
+        self.pagerank_limit = pagerank_limit
+        self.model = None
+        self.feature_engineer = None
+        self.shap_background = None
+        self.shap_explainer = None
+        
+        # Load model and fit feature engineer
+        self.load_model()
+        self.fit_feature_engineer()
+    
+    def load_model(self):
+        """Load the trained XGBoost model"""
+        try:
+            if not os.path.exists(self.model_path):
+                raise FileNotFoundError(f"Model file not found: {self.model_path}")
+            
+            # Load model - could be XGBoost directly or pipeline with XGBoost
+            loaded_obj = joblib.load(self.model_path)
+            
+            # Check if it's a pipeline or just XGBoost
+            if hasattr(loaded_obj, 'named_steps') and 'clf' in loaded_obj.named_steps:
+                # It's a pipeline, extract the classifier
+                self.model = loaded_obj.named_steps['clf']
+                print(f"✅ Model loaded from pipeline at {self.model_path}")
+            elif XGBOOST_AVAILABLE and isinstance(loaded_obj, xgb.XGBClassifier):
+                # It's XGBoost directly
+                self.model = loaded_obj
+                print(f"✅ XGBoost model loaded successfully from {self.model_path}")
+            else:
+                # Try to use it as-is (might be XGBoost wrapped)
+                self.model = loaded_obj
+                print(f"✅ Model loaded from {self.model_path} (assuming XGBoost)")
+                
+        except Exception as e:
+            print(f"❌ Error loading model: {str(e)}")
+            raise
+    
+    def fit_feature_engineer(self):
+        """Load test dataset and fit feature engineer"""
+        try:
+            # Initialize feature engineer
+            from feature_engineering import FraudFeatureEngineer
+            self.feature_engineer = FraudFeatureEngineer(pagerank_limit=self.pagerank_limit)
+            
+            # Find test dataset path - use script directory as base
+            script_dir = os.path.dirname(os.path.abspath(__file__))
+            
+            # Find test dataset path
+            test_paths = []
+            if self.test_dataset_path:
+                test_paths.append(self.test_dataset_path)
+                # Also try as absolute path if relative
+                if not os.path.isabs(self.test_dataset_path):
+                    test_paths.append(os.path.join(script_dir, self.test_dataset_path))
+            
+            # Try common locations - prioritize dataset folder in ml-api
+            test_paths.extend([
+                # Compressed versions (preferred for size)
+                os.path.join(script_dir, "dataset", "test_dataset.csv.gz"),
+                "dataset/test_dataset.csv.gz",
+                "../dataset/test_dataset.csv.gz",
+                "/app/dataset/test_dataset.csv.gz",
+                # Uncompressed versions
+                os.path.join(script_dir, "dataset", "test_dataset.csv"),  # ml-api/dataset/test_dataset.csv
+                os.path.join(script_dir, "dataset", "test_dataset_woIDX.csv"),  # ml-api/dataset/test_dataset_woIDX.csv
+                "dataset/test_dataset.csv",  # Relative to current working directory
+                "dataset/test_dataset_woIDX.csv",
+                "../dataset/test_dataset.csv",  # Fallback
+                "../dataset/test_dataset_woIDX.csv",
+                "/app/dataset/test_dataset.csv",  # For Docker deployment
+                "/app/dataset/test_dataset_woIDX.csv",
+                # Legacy paths for backward compatibility
+                "assets/test_dataset.csv",
+                "../assets/test_dataset.csv",
+                "/app/assets/test_dataset.csv"
+            ])
+            
+            test_df = None
+            dataset_path = None
+            for path in test_paths:
+                if os.path.exists(path):
+                    dataset_path = path
+                    print(f"📊 Found test dataset at {path}")
+                    break
+            
+            if dataset_path is None:
+                raise FileNotFoundError(
+                    f"Test dataset not found. Tried: {test_paths}\n"
+                    "Please ensure test dataset CSV is available for fitting feature engineer."
+                )
+            
+            # Memory-efficient loading: sample dataset for fitting to reduce RAM usage
+            # Read a sample of the dataset instead of the full file
+            max_rows_for_fitting = int(os.getenv("MAX_FIT_ROWS", "50000"))  # Default 50k rows
+            print(f"💾 Loading sample of dataset (max {max_rows_for_fitting:,} rows) for memory efficiency...")
+            
+            try:
+                # Use chunked reading with sampling for memory efficiency
+                # Read in chunks and sample from each chunk
+                chunk_size = 10000
+                chunks = []
+                total_read = 0
+                
+                for chunk in pd.read_csv(dataset_path, chunksize=chunk_size):
+                    # Sample from chunk if we're getting close to limit
+                    if total_read + len(chunk) > max_rows_for_fitting:
+                        remaining = max_rows_for_fitting - total_read
+                        if remaining > 0:
+                            chunk = chunk.head(remaining)
+                        chunks.append(chunk)
+                        break
+                    chunks.append(chunk)
+                    total_read += len(chunk)
+                    if total_read >= max_rows_for_fitting:
+                        break
+                
+                # Combine chunks
+                if chunks:
+                    test_df = pd.concat(chunks, ignore_index=True)
+                    print(f"✅ Loaded {len(test_df):,} rows for feature engineering fitting (sampled from dataset)")
+                else:
+                    # Fallback: load with direct limit
+                    test_df = pd.read_csv(dataset_path, nrows=max_rows_for_fitting)
+                    print(f"✅ Loaded {len(test_df):,} rows (direct read with limit)")
+                    
+            except Exception as e:
+                print(f"⚠️ Failed to load with chunking, trying direct read: {str(e)}")
+                # Fallback: load with limit
+                test_df = pd.read_csv(dataset_path, nrows=max_rows_for_fitting)
+                print(f"✅ Loaded {len(test_df):,} rows (fallback method)")
+            
+            # Ensure required columns exist
+            required_cols = ['step', 'type', 'amount', 'nameOrig', 'oldBalanceOrig', 
+                           'newBalanceOrig', 'nameDest', 'oldBalanceDest', 'newBalanceDest']
+            missing_cols = [col for col in required_cols if col not in test_df.columns]
+            if missing_cols:
+                raise ValueError(f"Test dataset missing required columns: {missing_cols}")
+            
+            # Add isFlaggedFraud if missing
+            if 'isFlaggedFraud' not in test_df.columns:
+                test_df['isFlaggedFraud'] = 0
+            
+            # Fit feature engineer on sampled dataset
+            print("🔧 Fitting feature engineer on sampled dataset...")
+            self.feature_engineer.fit(test_df)
+            print("✅ Feature engineer fitted successfully")
+            
+            # Clear the full dataset from memory
+            del test_df
+            gc.collect()
+            print("🧹 Cleared dataset from memory")
+            
+            # Prepare SHAP background from a small sample (reload minimal data)
+            print("📊 Preparing SHAP background data (small sample)...")
+            shap_sample_size = min(100, max_rows_for_fitting)  # Reduced from 200 to 100
+            # Reload just a tiny sample for SHAP background
+            shap_df = pd.read_csv(dataset_path, nrows=shap_sample_size * 2)  # Get more to sample from
+            shap_sample = shap_df.sample(n=min(shap_sample_size, len(shap_df)), random_state=42)
+            # Ensure required columns
+            if 'isFlaggedFraud' not in shap_sample.columns:
+                shap_sample['isFlaggedFraud'] = 0
+            self.shap_background = self.feature_engineer.transform(shap_sample)
+            del shap_df, shap_sample
+            gc.collect()
+            print(f"✅ SHAP background prepared ({len(self.shap_background)} samples)")
+            
+            # Initialize SHAP explainer
+            if SHAP_AVAILABLE and XGBOOST_AVAILABLE and isinstance(self.model, xgb.XGBClassifier):
+                self.shap_explainer = shap.TreeExplainer(self.model)
+                print("✅ SHAP explainer initialized")
+            else:
+                if not SHAP_AVAILABLE:
+                    print("⚠️ SHAP explainer not initialized (SHAP library not available)")
+                else:
+                    print("⚠️ SHAP explainer not initialized (XGBoost not available or model type unknown)")
+                
+        except Exception as e:
+            print(f"❌ Error fitting feature engineer: {str(e)}")
+            raise
+    
+    def predict(self, transaction_df: pd.DataFrame) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Predict fraud probability for transactions
+        
+        Args:
+            transaction_df: DataFrame with raw transaction data
+            
+        Returns:
+            probabilities: Array of fraud probabilities
+            decisions: Array of binary decisions (0/1)
+        """
+        if self.model is None:
+            raise ValueError("Model not loaded. Call load_model() first.")
+        
+        if self.feature_engineer is None:
+            raise ValueError("Feature engineer not fitted. Call fit_feature_engineer() first.")
+        
+        # Transform transaction using fitted feature engineer
+        X_transformed = self.feature_engineer.transform(transaction_df)
+        
+        # Get probabilities from XGBoost model
+        probabilities = self.model.predict_proba(X_transformed)[:, 1]
+        
+        # Make decisions based on threshold
+        decisions = (probabilities >= self.threshold).astype(int)
+        
+        return probabilities, decisions
+    
+    def explain_shap(self, transaction_df: pd.DataFrame, topk: int = 10) -> pd.DataFrame:
+        """
+        Generate SHAP explanations for a transaction
+        
+        Args:
+            transaction_df: Single transaction DataFrame (raw format)
+            topk: Number of top features to return
+            
+        Returns:
+            DataFrame with feature contributions sorted by importance
+        """
+        if not SHAP_AVAILABLE:
+            raise ValueError("SHAP library not available")
+        
+        if self.model is None:
+            raise ValueError("Model not loaded")
+        
+        if self.feature_engineer is None:
+            raise ValueError("Feature engineer not fitted")
+        
+        # Transform transaction using fitted feature engineer
+        X_trans = self.feature_engineer.transform(transaction_df)
+        feature_names = X_trans.columns.tolist()
+        
+        # Compute SHAP values
+        try:
+            if self.shap_explainer is not None:
+                shap_values = self._compute_shap_values(self.shap_explainer, X_trans)
+            elif XGBOOST_AVAILABLE and isinstance(self.model, xgb.XGBClassifier):
+                # Fallback: create explainer on the fly
+                explainer = shap.TreeExplainer(self.model)
+                shap_values = self._compute_shap_values(explainer, X_trans)
+            else:
+                explainer = shap.Explainer(self.model, X_trans.iloc[[0]], feature_names=feature_names)
+                shap_exp = explainer(X_trans)
+                shap_values = shap_exp.values[0] if shap_exp.values.ndim == 2 else shap_exp.values
+        except Exception as e:
+            print(f"⚠️ SHAP computation failed: {str(e)}")
+            shap_values = np.zeros(X_trans.shape[1])
+        
+        # Ensure shap_values is 1D
+        if shap_values.ndim > 1:
+            shap_values = shap_values[0]
+        
+        # Build feature contribution DataFrame
+        feat_df = pd.DataFrame({
+            'feature': feature_names,
+            'value': X_trans.iloc[0].values,
+            'shap_abs': np.abs(shap_values),
+            'shap': shap_values
+        })
+        
+        # Sort by absolute SHAP value
+        feat_df = feat_df.sort_values('shap_abs', ascending=False).reset_index(drop=True)
+        
+        return feat_df.head(topk)
+    
+    def _compute_shap_values(self, explainer, X_trans: pd.DataFrame) -> np.ndarray:
+        """Helper method to compute SHAP values"""
+        if isinstance(explainer, shap.TreeExplainer):
+            shap_values = explainer.shap_values(X_trans)
+            if isinstance(shap_values, list):
+                shap_values = shap_values[1]  # Get positive class values
+        else:
+            shap_exp = explainer(X_trans)
+            shap_values = shap_exp.values[0] if shap_exp.values.ndim == 2 else shap_exp.values
+        return shap_values
+    
+    def explain_llm(self, probability: float, shap_table: pd.DataFrame, transaction_df: Optional[pd.DataFrame] = None, topk: int = 6, language: str = 'en') -> Optional[str]:
+        """
+        Generate human-readable explanation using Groq LLM
+        
+        Args:
+            probability: Fraud probability
+            shap_table: DataFrame with SHAP contributions
+            topk: Number of top features to include
+            language: Language code ('en' for English, 'bn' for Bangla)
+            
+        Returns:
+            LLM-generated explanation text or None
+        """
+        if not GROQ_AVAILABLE:
+            return None
+        
+        if self.groq_api_key is None:
+            self.groq_api_key = os.getenv('GROQ_API_KEY')
+        
+        if self.groq_api_key is None:
+            return None
+        
+        try:
+            client = Groq(api_key=self.groq_api_key)
+            
+            # Determine if fraud is detected
+            is_fraud = probability >= self.threshold
+            decision = "block" if is_fraud else ("warn" if probability >= self.threshold * 0.5 else "pass")
+            
+            # Get transaction details if available
+            amount = None
+            tx_type = None
+            old_balance_orig = None
+            new_balance_orig = None
+            old_balance_dest = None
+            new_balance_dest = None
+            
+            if transaction_df is not None and len(transaction_df) > 0:
+                row = transaction_df.iloc[0]
+                amount = row.get('amount', None)
+                tx_type = row.get('type', None)
+                old_balance_orig = row.get('oldBalanceOrig', None)
+                new_balance_orig = row.get('newBalanceOrig', None)
+                old_balance_dest = row.get('oldBalanceDest', None)
+                new_balance_dest = row.get('newBalanceDest', None)
+            
+            if language == 'bn':
+                system_prompt = (
+                    "আপনি একজন ব্যবহারকারী-বান্ধব মোবাইল ব্যাংকিং জালিয়াতি সতর্কতা সহায়ক। "
+                    "আপনার কাজ হল সাধারণ ব্যবহারকারীদের জন্য সহজ ভাষায় ব্যাখ্যা করা, কোন লেনদেন কেন নিরাপদ বা ঝুঁকিপূর্ণ। "
+                    "কোনও প্রযুক্তিগত শব্দ (যেমন SHAP, বৈশিষ্ট্য মান,technical detail, values ইত্যাদি) ব্যবহার করবেন না। "
+                    "পরিবর্তে, ব্যবহারকারীকে বলুন: "
+                    "- এই লেনদেনে কোন লাল সংকেত আছে কিনা "
+                    "- তারা কী সতর্ক থাকতে হবে "
+                    "- কেন এই লেনদেন নিরাপদ বা ঝুঁকিপূর্ণ "
+                    "- যদি ফ্রড সনাক্ত হয়, তাহলে কেন এটি ফ্রড হতে পারে "
+                    "- তারা কী করতে পারে বা এড়াতে পারে "
+                    "ব্যাখ্যাটি সহজ, বন্ধুত্বপূর্ণ এবং ব্যবহারকারীর জন্য কার্যকর হতে হবে। "
+                    "সমস্ত উত্তর বাংলায় লিখুন।"
+                )
+                
+                tx_info = ""
+                if amount is not None:
+                    tx_info += f"- লেনদেনের পরিমাণ: ৳ {amount:,.2f}\n"
+                if tx_type is not None:
+                    tx_type_bn = "ক্যাশ আউট" if tx_type == "CASH_OUT" else "স্থানান্তর" if tx_type == "TRANSFER" else tx_type
+                    tx_info += f"- লেনদেনের ধরন: {tx_type_bn}\n"
+                if old_balance_orig is not None and new_balance_orig is not None:
+                    balance_change = new_balance_orig - old_balance_orig
+                    tx_info += f"- প্রেরকের ব্যালেন্স পরিবর্তন: ৳ {balance_change:,.2f}\n"
+                if old_balance_dest is not None and new_balance_dest is not None:
+                    balance_change = new_balance_dest - old_balance_dest
+                    tx_info += f"- গ্রহীতার ব্যালেন্স পরিবর্তন: ৳ {balance_change:,.2f}\n"
+                
+                user_prompt = (
+                    f"লেনদেনের ফ্রড সম্ভাবনা: {probability*100:.2f}%\n"
+                    f"সিদ্ধান্ত: {'ফ্রড সনাক্ত হয়েছে - লেনদেন ব্লক করা হয়েছে' if is_fraud else ('সতর্কতা - ম্যানুয়াল পর্যালোচনা প্রয়োজন' if decision == 'warn' else 'লেনদেন নিরাপদ - অনুমোদন করা যেতে পারে')}\n"
+                    f"লেনদেনের তথ্য:\n{tx_info}"
+                    f"\nএকটি সহজ, ব্যবহারকারী-বান্ধব ব্যাখ্যা লিখুন যা ব্যবহারকারীকে বুঝতে সাহায্য করবে কেন এই লেনদেন নিরাপদ বা ঝুঁকিপূর্ণ, এবং তাদের কী জানা উচিত বা সতর্ক থাকতে হবে।"
+                )
+            else:
+                system_prompt = (
+                    "You are a user-friendly mobile banking fraud alert assistant. "
+                    "Your job is to explain in simple language why a transaction is safe or risky for regular users. "
+                    "Do NOT use any technical terms (like SHAP, feature values, technical detail, values etc.). "
+                    "Instead, tell the user: "
+                    "- What red flags exist in this transaction (if any) "
+                    "- What they should be aware of or cautious about "
+                    "- Why this transaction is safe or risky "
+                    "- If fraud is detected, explain why it might be fraud "
+                    "- What they can do or should avoid "
+                    "The explanation should be simple, friendly, and actionable for the user. "
+                    "Focus on what matters to them, not technical details."
+                )
+                
+                tx_info = ""
+                if amount is not None:
+                    tx_info += f"- Transaction amount: ৳ {amount:,.2f}\n"
+                if tx_type is not None:
+                    tx_info += f"- Transaction type: {tx_type}\n"
+                if old_balance_orig is not None and new_balance_orig is not None:
+                    balance_change = new_balance_orig - old_balance_orig
+                    tx_info += f"- Sender balance change: ৳ {balance_change:,.2f}\n"
+                if old_balance_dest is not None and new_balance_dest is not None:
+                    balance_change = new_balance_dest - old_balance_dest
+                    tx_info += f"- Receiver balance change: ৳ {balance_change:,.2f}\n"
+                
+                user_prompt = (
+                    f"Transaction fraud probability: {probability*100:.2f}%\n"
+                    f"Decision: {'Fraud detected - Transaction blocked' if is_fraud else ('Warning - Manual review required' if decision == 'warn' else 'Transaction safe - Can be approved')}\n"
+                    f"Transaction details:\n{tx_info}"
+                    f"\nWrite a simple, user-friendly explanation that helps the user understand why this transaction is safe or risky, and what they should know or be cautious about."
+                )
+            
+            chat_completion = client.chat.completions.create(
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ],
+                model="llama-3.1-8b-instant",
+                temperature=0.3,
+                max_tokens=500
+            )
+            
+            explanation = chat_completion.choices[0].message.content.strip()
+            return explanation
+            
+        except Exception as e:
+            error_msg = f"(LLM generation failed: {str(e)})"
+            if language == 'bn':
+                error_msg = f"(LLM তৈরি করতে ব্যর্থ: {str(e)})"
+            return error_msg
+    
+    def predict_and_explain(
+        self, 
+        transaction_df: pd.DataFrame, 
+        shap_background: Optional[pd.DataFrame] = None,
+        topk: int = 6,
+        use_llm: bool = True,
+        language: str = 'en'
+    ) -> Dict:
+        """
+        Complete prediction and explanation pipeline
+        
+        Args:
+            transaction_df: Raw transaction DataFrame
+            shap_background: Optional background data for SHAP
+            topk: Number of top features to explain
+            use_llm: Whether to generate LLM explanation
+            language: Language code ('en' for English, 'bn' for Bangla)
+            
+        Returns:
+            Dictionary with:
+                - probabilities: Fraud probabilities
+                - decisions: Binary decisions
+                - shap_table: Feature contributions DataFrame
+                - llm_explanation: Optional LLM explanation text
+        """
+        # Predict
+        probabilities, decisions = self.predict(transaction_df)
+        
+        # Prepare SHAP background if needed
+        if shap_background is not None:
+            self.prepare_shap_background(shap_background)
+        
+        # Generate SHAP explanations
+        shap_table = self.explain_shap(transaction_df, topk=topk)
+        
+        # Generate LLM explanation if requested
+        llm_explanation = None
+        if use_llm and GROQ_AVAILABLE:
+            llm_explanation = self.explain_llm(probabilities[0], shap_table, transaction_df=transaction_df, topk=topk, language=language)
+        
+        return {
+            'probabilities': probabilities,
+            'decisions': decisions,
+            'shap_table': shap_table,
+            'llm_explanation': llm_explanation
+        }
+
+
+def load_inference_engine(
+    model_path: str = "Models/fraud_pipeline_final.pkl",
+    test_dataset_path: Optional[str] = None,
+    threshold: float = 0.0793,
+    groq_api_key: Optional[str] = None,
+    pagerank_limit: Optional[int] = None
+) -> FraudInference:
+    """
+    Convenience function to load inference engine
+    
+    Args:
+        model_path: Path to model file
+        test_dataset_path: Path to test dataset CSV (optional, will search common locations)
+        threshold: Decision threshold
+        groq_api_key: Optional Groq API key
+        pagerank_limit: Optional limit on nodes for PageRank computation
+        
+    Returns:
+        Initialized FraudInference instance
+    """
+    possible_paths = [
+        model_path,
+        f"/app/{model_path}",
+        f"/app/Models/fraud_pipeline_final.pkl",
+        "Models/fraud_pipeline_final.pkl",
+        "../Models/fraud_pipeline_final.pkl"
+    ]
+    
+    actual_path = None
+    for path in possible_paths:
+        if os.path.exists(path):
+            actual_path = path
+            break
+    
+    if actual_path is None:
+        raise FileNotFoundError(
+            f"Model file not found. Tried: {possible_paths}\n"
+            "Please ensure the model file is in one of these locations."
+        )
+    
+    return FraudInference(
+        actual_path, 
+        test_dataset_path=test_dataset_path,
+        threshold=threshold, 
+        groq_api_key=groq_api_key,
+        pagerank_limit=pagerank_limit
+    )
+

main.py

@@ -0,0 +1,530 @@
+"""
+CloverShield ML Inference API
+FastAPI microservice for fraud detection predictions
+"""
+
+import os
+import sys
+import time
+import uuid
+from typing import Optional, Dict, List
+from datetime import datetime
+
+import pandas as pd
+import numpy as np
+from fastapi import FastAPI, HTTPException, Header
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, validator
+import uvicorn
+
+# Add current directory to path for imports
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from inference import FraudInference, load_inference_engine
+import warnings
+
+# Suppress warnings
+warnings.filterwarnings('ignore')
+
+# ============================================================================
+# PYDANTIC MODELS
+# ============================================================================
+
+class TransactionInput(BaseModel):
+    """Transaction input model"""
+    step: Optional[int] = Field(default=1, ge=0, description="Time step")
+    type: str = Field(..., description="Transaction type")
+    amount: float = Field(..., gt=0, description="Transaction amount")
+    nameOrig: str = Field(..., description="Sender user ID")
+    oldBalanceOrig: float = Field(..., ge=0, description="Sender balance before")
+    newBalanceOrig: float = Field(..., ge=0, description="Sender balance after")
+    nameDest: str = Field(..., description="Receiver user ID")
+    oldBalanceDest: float = Field(..., ge=0, description="Receiver balance before")
+    newBalanceDest: float = Field(..., ge=0, description="Receiver balance after")
+    
+    @validator('type')
+    def validate_type(cls, v):
+        allowed = ['CASH_OUT', 'TRANSFER', 'CASH_IN', 'PAYMENT', 'DEBIT']
+        if v not in allowed:
+            raise ValueError(f"Transaction type must be one of {allowed}")
+        return v
+    
+    @validator('nameDest')
+    def validate_different_accounts(cls, v, values):
+        if 'nameOrig' in values and v == values['nameOrig']:
+            raise ValueError("Sender and receiver cannot be the same")
+        return v
+
+class PredictionOptions(BaseModel):
+    """Prediction options"""
+    include_shap: bool = Field(default=True, description="Include SHAP explanations")
+    include_llm_explanation: bool = Field(default=False, description="Include LLM explanation")
+    language: str = Field(default='en', description="Language for explanations")
+    topk: int = Field(default=10, ge=1, le=20, description="Number of top features")
+    
+    @validator('language')
+    def validate_language(cls, v):
+        if v not in ['en', 'bn']:
+            raise ValueError("Language must be 'en' or 'bn'")
+        return v
+
+class PredictRequest(BaseModel):
+    """Request model for /predict endpoint"""
+    transaction: TransactionInput
+    options: Optional[PredictionOptions] = Field(default_factory=PredictionOptions)
+
+class SHAPExplanation(BaseModel):
+    """SHAP explanation model"""
+    feature: str
+    value: float
+    shap: float
+    shap_abs: float
+    rank: int
+
+class PredictionResult(BaseModel):
+    """Prediction result model"""
+    fraud_probability: float = Field(..., ge=0, le=1)
+    decision: str = Field(..., description="pass, warn, or block")
+    risk_level: str = Field(..., description="low, medium, or high")
+    confidence: float = Field(..., ge=0, le=1)
+
+class PredictResponse(BaseModel):
+    """Response model for /predict endpoint"""
+    transaction_id: str
+    prediction: PredictionResult
+    shap_explanations: Optional[List[SHAPExplanation]] = None
+    llm_explanation: Optional[Dict[str, str]] = None
+    processing_time_ms: int
+    model_version: str
+    timestamp: str
+
+class BatchPredictRequest(BaseModel):
+    """Request model for batch prediction"""
+    transactions: List[TransactionInput]
+    options: Optional[PredictionOptions] = Field(default_factory=PredictionOptions)
+
+class BatchPredictResponse(BaseModel):
+    """Response model for batch prediction"""
+    results: List[Dict]
+    processing_time_ms: int
+    total_transactions: int
+
+# ============================================================================
+# FASTAPI APP
+# ============================================================================
+
+app = FastAPI(
+    title="CloverShield ML Inference API",
+    description="Fraud detection ML service for CloverShield platform",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# CORS middleware - configure allowed origins for production
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # TODO: Restrict to specific origins in production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ============================================================================
+# GLOBAL STATE
+# ============================================================================
+
+inference_engine: Optional[FraudInference] = None
+model_loading_lock = False
+MODEL_VERSION = "1.0.0"
+MODEL_THRESHOLD = float(os.getenv("MODEL_THRESHOLD", "0.0793"))
+
+# Risk thresholds (matching config.py)
+RISK_THRESHOLDS = {
+    "pass": 0.30,
+    "warn": 0.30,
+    "block": 0.70
+}
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def load_model():
+    """Load the ML model on startup"""
+    global inference_engine, model_loading_lock
+    
+    # Prevent concurrent loading attempts
+    if model_loading_lock:
+        return
+    model_loading_lock = True
+    
+    model_path = os.getenv("MODEL_PATH", "Models/fraud_pipeline_final.pkl")
+    test_dataset_path = os.getenv("TEST_DATASET_PATH", None)
+    groq_api_key = os.getenv("GROQ_API_KEY")
+    pagerank_limit = os.getenv("PAGERANK_LIMIT", None)
+    
+    # Convert pagerank_limit to int if provided
+    if pagerank_limit:
+        try:
+            pagerank_limit = int(pagerank_limit)
+        except ValueError:
+            pagerank_limit = None
+    
+    # Try multiple paths for model
+    possible_paths = [
+        model_path,
+        f"/app/{model_path}",
+        f"/app/Models/fraud_pipeline_final.pkl",
+        "Models/fraud_pipeline_final.pkl",
+        "../Models/fraud_pipeline_final.pkl"
+    ]
+    
+    actual_path = None
+    for path in possible_paths:
+        if os.path.exists(path):
+            actual_path = path
+            break
+    
+    if actual_path is None:
+        raise FileNotFoundError(
+            f"Model file not found. Tried: {possible_paths}\n"
+            "Please ensure the model file is available."
+        )
+    
+    try:
+        # Validate file exists and is readable
+        if not os.path.exists(actual_path):
+            raise FileNotFoundError(f"Model file not found at {actual_path}")
+        
+        # Check file size (should be at least 1MB for a valid model)
+        file_size = os.path.getsize(actual_path) / (1024 * 1024)
+        if file_size < 1:
+            raise ValueError(
+                f"Model file is too small ({file_size:.1f} MB). "
+                f"Expected at least 1MB. The file may be corrupted or incomplete."
+            )
+        
+        # Try to load the model with test dataset for feature engineering
+        inference_engine = load_inference_engine(
+            model_path=actual_path,
+            test_dataset_path=test_dataset_path,
+            threshold=MODEL_THRESHOLD,
+            groq_api_key=groq_api_key,
+            pagerank_limit=pagerank_limit
+        )
+        print(f"✅ Model loaded successfully from {actual_path} ({file_size:.1f} MB)")
+    except FileNotFoundError as e:
+        error_msg = f"❌ Model file not found: {str(e)}"
+        print(error_msg)
+        raise FileNotFoundError(error_msg) from e
+    except ValueError as e:
+        error_msg = f"❌ Invalid model file: {str(e)}"
+        print(error_msg)
+        raise ValueError(error_msg) from e
+    except Exception as e:
+        error_msg = f"❌ Error loading model: {str(e)}"
+        print(error_msg)
+        print(f"   Model path: {actual_path}")
+        print(f"   File exists: {os.path.exists(actual_path) if actual_path else False}")
+        if actual_path and os.path.exists(actual_path):
+            print(f"   File size: {os.path.getsize(actual_path) / (1024 * 1024):.1f} MB")
+        raise Exception(error_msg) from e
+    finally:
+        model_loading_lock = False
+
+def ensure_model_loaded():
+    """Ensure model is loaded, try to load if not loaded (lazy loading for serverless)"""
+    global inference_engine, model_loading_lock
+    
+    if inference_engine is not None:
+        return True
+    
+    # Try to load if not already loading
+    if not model_loading_lock:
+        try:
+            print("🔄 Model not loaded, attempting to load now...")
+            load_model()
+            return inference_engine is not None
+        except Exception as e:
+            print(f"⚠️ Failed to load model on demand: {str(e)}")
+            return False
+    return False
+
+def calculate_decision(probability: float) -> tuple[str, str]:
+    """Calculate decision and risk level from probability"""
+    if probability >= RISK_THRESHOLDS['block']:
+        return 'block', 'high'
+    elif probability >= RISK_THRESHOLDS['warn']:
+        return 'warn', 'medium'
+    else:
+        return 'pass', 'low'
+
+def calculate_confidence(probability: float) -> float:
+    """Calculate confidence level based on probability"""
+    if probability < 0.1 or probability > 0.9:
+        return 0.9
+    elif probability < 0.2 or probability > 0.8:
+        return 0.75
+    elif probability < 0.3 or probability > 0.7:
+        return 0.6
+    else:
+        return 0.4
+
+def transaction_to_dataframe(transaction: TransactionInput) -> pd.DataFrame:
+    """Convert transaction input to DataFrame"""
+    data = {
+        'step': transaction.step or 1,
+        'type': transaction.type,
+        'amount': float(transaction.amount),
+        'nameOrig': transaction.nameOrig,
+        'oldBalanceOrig': float(transaction.oldBalanceOrig),
+        'newBalanceOrig': float(transaction.newBalanceOrig),
+        'nameDest': transaction.nameDest,
+        'oldBalanceDest': float(transaction.oldBalanceDest),
+        'newBalanceDest': float(transaction.newBalanceDest),
+        'isFlaggedFraud': 0
+    }
+    return pd.DataFrame([data])
+
+# ============================================================================
+# API ENDPOINTS
+# ============================================================================
+
+@app.on_event("startup")
+async def startup_event():
+    """Load model on startup"""
+    port = os.getenv("PORT", "8000")
+    print(f"🚀 Server starting on port {port}")
+    print("📦 Loading model...")
+    
+    try:
+        load_model()
+        if inference_engine is not None:
+            print("✅ Model loaded successfully - API is ready!")
+        else:
+            print("⚠️ Warning: Model loading completed but inference_engine is None")
+            print("⚠️ API will attempt lazy loading on first request")
+    except Exception as e:
+        print(f"⚠️ Warning: Model not loaded on startup: {str(e)}")
+        print("⚠️ API will attempt lazy loading on first request")
+        print("⚠️ This is normal for serverless environments (e.g., Vercel)")
+
+@app.get("/")
+async def root():
+    """Root endpoint"""
+    return {
+        "service": "CloverShield ML Inference API",
+        "version": MODEL_VERSION,
+        "status": "running",
+        "model_loaded": inference_engine is not None
+    }
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    # Lazy loading for serverless environments
+    if inference_engine is None:
+        ensure_model_loaded()
+    
+    model_loaded = inference_engine is not None
+    shap_available = model_loaded and inference_engine.shap_explainer is not None
+    
+    return {
+        "status": "healthy" if model_loaded else "degraded",
+        "model_loaded": model_loaded,
+        "model_version": MODEL_VERSION,
+        "shap_available": shap_available,
+        "llm_available": os.getenv("GROQ_API_KEY") is not None,
+        "message": "Model loaded and ready" if model_loaded else "Model is loading or unavailable"
+    }
+
+@app.get("/model/info")
+async def model_info():
+    """Get model information"""
+    if inference_engine is None:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+    
+    return {
+        "model_version": MODEL_VERSION,
+        "model_type": "XGBoost",
+        "threshold": MODEL_THRESHOLD,
+        "features": [
+            {"name": "step", "type": "integer", "description": "Time step"},
+            {"name": "amount", "type": "float", "description": "Transaction amount"},
+            {"name": "oldBalanceOrig", "type": "float", "description": "Sender balance before"},
+            {"name": "newBalanceOrig", "type": "float", "description": "Sender balance after"},
+            {"name": "oldBalanceDest", "type": "float", "description": "Receiver balance before"},
+            {"name": "newBalanceDest", "type": "float", "description": "Receiver balance after"},
+            {"name": "type", "type": "string", "description": "Transaction type"},
+        ]
+    }
+
+@app.post("/predict", response_model=PredictResponse)
+async def predict(request: PredictRequest):
+    """
+    Predict fraud probability for a single transaction
+    
+    Returns fraud probability, decision, risk level, and SHAP explanations
+    """
+    # Lazy loading for serverless environments
+    if inference_engine is None:
+        if not ensure_model_loaded():
+            raise HTTPException(
+                status_code=503, 
+                detail="Model not loaded. The model is still loading or failed to load. Please try again in a moment or check /health endpoint."
+            )
+    
+    start_time = time.time()
+    transaction_id = str(uuid.uuid4())
+    
+    try:
+        # Convert transaction to DataFrame
+        transaction_df = transaction_to_dataframe(request.transaction)
+        
+        # Get options
+        options = request.options or PredictionOptions()
+        
+        # Predict
+        result = inference_engine.predict_and_explain(
+            transaction_df,
+            shap_background=None,
+            topk=options.topk,
+            use_llm=options.include_llm_explanation,
+            language=options.language
+        )
+        
+        probability = float(result['probabilities'][0])
+        decision, risk_level = calculate_decision(probability)
+        confidence = calculate_confidence(probability)
+        
+        # Format SHAP explanations
+        shap_explanations = None
+        if options.include_shap and result.get('shap_table') is not None:
+            shap_df = result['shap_table']
+            shap_explanations = [
+                SHAPExplanation(
+                    feature=row['feature'],
+                    value=float(row['value']),
+                    shap=float(row['shap']),
+                    shap_abs=float(row['shap_abs']),
+                    rank=idx + 1
+                )
+                for idx, (_, row) in enumerate(shap_df.iterrows())
+            ]
+        
+        # Format LLM explanation
+        llm_explanation = None
+        if result.get('llm_explanation'):
+            llm_explanation = {
+                "text": result['llm_explanation'],
+                "language": options.language
+            }
+        
+        processing_time = int((time.time() - start_time) * 1000)
+        
+        return PredictResponse(
+            transaction_id=transaction_id,
+            prediction=PredictionResult(
+                fraud_probability=probability,
+                decision=decision,
+                risk_level=risk_level,
+                confidence=confidence
+            ),
+            shap_explanations=shap_explanations,
+            llm_explanation=llm_explanation,
+            processing_time_ms=processing_time,
+            model_version=MODEL_VERSION,
+            timestamp=datetime.utcnow().isoformat() + "Z"
+        )
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        print(f"❌ Prediction error: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Prediction failed: {str(e)}")
+
+@app.post("/predict/batch", response_model=BatchPredictResponse)
+async def predict_batch(request: BatchPredictRequest):
+    """
+    Predict fraud probability for multiple transactions
+    
+    Returns predictions for all transactions in batch
+    """
+    # Lazy loading for serverless environments
+    if inference_engine is None:
+        if not ensure_model_loaded():
+            raise HTTPException(
+                status_code=503, 
+                detail="Model not loaded. The model is still loading or failed to load. Please try again in a moment."
+            )
+    
+    start_time = time.time()
+    options = request.options or PredictionOptions()
+    
+    results = []
+    
+    try:
+        for transaction in request.transactions:
+            transaction_df = transaction_to_dataframe(transaction)
+            
+            # Predict (without SHAP for batch to speed up)
+            probabilities, decisions = inference_engine.predict(transaction_df)
+            probability = float(probabilities[0])
+            decision, risk_level = calculate_decision(probability)
+            
+            results.append({
+                "transaction_id": str(uuid.uuid4()),
+                "prediction": {
+                    "fraud_probability": probability,
+                    "decision": decision,
+                    "risk_level": risk_level
+                }
+            })
+        
+        processing_time = int((time.time() - start_time) * 1000)
+        
+        return BatchPredictResponse(
+            results=results,
+            processing_time_ms=processing_time,
+            total_transactions=len(results)
+        )
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Batch prediction failed: {str(e)}")
+
+# ============================================================================
+# ERROR HANDLERS
+# ============================================================================
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": exc.detail,
+            "status_code": exc.status_code
+        }
+    )
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+if __name__ == "__main__":
+    # Get port from environment (required for Render, Railway, etc.)
+    port = int(os.getenv("PORT", 8000))
+    host = os.getenv("HOST", "0.0.0.0")
+    
+    print(f"🌐 Binding to {host}:{port}")
+    
+    uvicorn.run(
+        "main:app",
+        host=host,
+        port=port,
+        reload=False,
+        workers=1,  # Single worker for ML model
+        log_level="info"
+    )
+

railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.app/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "Dockerfile"
+  },
+  "deploy": {
+    "startCommand": "uvicorn main:app --host 0.0.0.0 --port $PORT",
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10
+  }
+}
+

render.yaml

@@ -0,0 +1,26 @@
+# Render.com deployment configuration for CloverShield ML API
+
+services:
+  - type: web
+    name: clovershield-ml-api
+    runtime: docker
+    dockerfilePath: ./Dockerfile
+    dockerContext: .
+    envVars:
+      - key: MODEL_PATH
+        value: Models/fraud_pipeline_final.pkl
+      - key: MODEL_THRESHOLD
+        value: 0.0793
+      - key: PORT
+        value: 8000
+      - key: HOST
+        value: 0.0.0.0
+      - key: MAX_FIT_ROWS
+        value: "30000"  # Reduced for Render free tier (512MB RAM)
+      - key: PAGERANK_LIMIT
+        value: "5000"  # Reduced for memory efficiency
+      - key: GROQ_API_KEY
+        sync: false  # Set in Render dashboard
+    healthCheckPath: /health
+    plan: starter  # Upgrade for production
+

requirements.txt

@@ -0,0 +1,35 @@
+# CloverShield ML Inference API - Dependencies
+# Python 3.9+
+
+# FastAPI and server
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.0.0
+
+# Data processing
+pandas>=1.5.0
+numpy>=1.23.0
+
+# Model loading and ML dependencies
+joblib>=1.2.0
+scikit-learn>=1.2.0
+xgboost>=1.7.0
+
+# Explainability
+shap>=0.44.0
+
+# LLM explanations (optional)
+groq>=1.0.0
+
+# Environment variable management
+python-dotenv>=1.0.0
+
+# Graph features (for model pipeline)
+networkx>=3.0
+
+# Optional: For better performance
+scipy>=1.10.0
+
+# CORS support (included in FastAPI)
+# python-multipart for file uploads (if needed)
+

vercel.json

@@ -0,0 +1,20 @@
+{
+  "version": 2,
+  "builds": [
+    {
+      "src": "main.py",
+      "use": "@vercel/python"
+    }
+  ],
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "main.py"
+    }
+  ],
+  "env": {
+    "MODEL_PATH": "Models/fraud_pipeline_final.pkl",
+    "MODEL_THRESHOLD": "0.0793"
+  }
+}
+