EduBotX ML API Documentation

AI-Powered Wastewater Treatment ML Backend

This folder contains structured documentation for the EduBotX Wastewater Treatment ML API - a FastAPI-based backend providing machine learning predictions for water quality analysis.

---

Quick Start

Prerequisites

• Python 3.10+
• pip or conda

Installation

# Navigate to ML directory
cd ml

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the API server
uvicorn main:app --reload --port 8000

Verify Installation

# Check API health
curl http://localhost:8000/health

# Or open in browser
# http://localhost:8000/docs

---

Documentation

Document	Description
API Reference	Complete API documentation with examples
Changelog	Version history and release notes

---

API Overview

Available Models

Model	Endpoint	Artifacts	Description
Reusability Predictor	/api/predict/reusability	models_v1/	Water reusability classification with CPCB compliance
Treatment Recommender	/api/predict/treatment	models_v2/	Treatment stage recommendations

Key Features

• Reusability Prediction: Classify treated wastewater for various reuse applications (irrigation, industrial, drinking, etc.)
• CPCB Compliance: Check effluent against CPCB inland surface water discharge limits
• Treatment Recommendation: Recommend treatment stages (Primary/Secondary/Tertiary/Advanced)
• Chemical Suggestions: Get chlorine and alum dosing recommendations
• Risk Assessment: Evaluate health/environmental risks
• Batch Processing: Process multiple samples in one request
• WebSocket Streaming: Real-time predictions for SCADA integration
• PDF Reports: Generate downloadable treatment reports

---

Project Structure

ml/
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── models_v1/              # Reusability prediction model artifacts
│   ├── model.joblib        # Trained classifier
│   ├── imputer.joblib      # Missing value imputer
│   ├── scaler.joblib       # Feature scaler
│   ├── label_encoder.joblib # Class label encoder
│   └── features.joblib     # Feature names list
├── models_v2/              # Treatment recommendation model artifacts
│   ├── sih_model.pkl       # Trained classifier
│   ├── sih_scaler.pkl      # Feature scaler
│   └── sih_label_encoder.pkl # Stage label encoder
├── prediction_v1/          # Additional prediction artifacts
├── docs/                   # Documentation (you are here)
│   ├── README.md           # This file
│   ├── api.md              # API reference
│   └── CHANGELOG.md        # Version history
└── ws_scada_simulator.py   # WebSocket SCADA simulator script

---

Interactive Documentation

When the server is running:

URL	Description
http://localhost:8000	API root / health check
http://localhost:8000/docs	Swagger UI (interactive)
http://localhost:8000/redoc	ReDoc (alternative docs)
http://localhost:8000/health	Detailed health status

---

WebSocket Endpoints

For real-time streaming predictions (SCADA integration):

Endpoint	Description
/ws/reusability	Real-time reusability predictions
/ws/treatment	Real-time treatment recommendations

Testing WebSocket

# Using the SCADA simulator
python ws_scada_simulator.py

---

Environment Variables

The ML API can be configured via environment variables:

Variable	Default	Description
HOST	0.0.0.0	Server host
PORT	8000	Server port
RELOAD	false	Auto-reload on code changes
LOG_LEVEL	info	Logging level

---

Integration with Frontend

The Next.js frontend connects to this API via the NEXT_PUBLIC_ML_API_URL environment variable:

# In core/.env.local
NEXT_PUBLIC_ML_API_URL=http://localhost:8000

---

Quick API Examples

Health Check

curl http://localhost:8000/health

Reusability Prediction

curl -X POST http://localhost:8000/api/predict/reusability \
  -H "Content-Type: application/json" \
  -d '{
    "flow_rate": 150,
    "influent_BOD": 200,
    "influent_COD": 400,
    "influent_TSS": 150,
    "influent_pH": 7.2,
    "influent_TDS": 500,
    "aeration_rate": 50,
    "chemical_dose": 25,
    "sludge_recycle_rate": 30,
    "retention_time": 8,
    "temperature": 28,
    "effluent_BOD_lag1": 20
  }'

Treatment Recommendation

curl -X POST "http://localhost:8000/api/predict/treatment?use_case=Irrigation" \
  -H "Content-Type: application/json" \
  -d '{
    "pH": 7.5,
    "TSS": 120,
    "Turbidity": 45,
    "BOD": 180,
    "COD": 350,
    "NH4_N": 25,
    "Total_Nitrogen": 40,
    "Phosphate": 8,
    "Fecal_Coliform": 5000,
    "Oil_Grease": 15,
    "TDS": 600,
    "Heavy_Metals": 0.5
  }'

---

Last Updated: December 2024