HydraAI 1.0

Smart Water Demand Prediction and Conservation System

A production-ready system that uses a trained XGBoost model to predict daily water consumption, generate conservation recommendations, and visualize 7-day demand forecasts — all through a REST API and a modern web dashboard.

---

Table of Contents

• Project Structure
• How It Works
• Requirements
• Setup and Running the Project
  • Option A — Local development
  • Option B — Docker
• Environment Variables
• API Reference
• Frontend Features
• Model Details
• Troubleshooting

---

Project Structure

HydraAI 1.0/
|
|-- backend/                    Backend API server
|   |-- src/
|   |   |-- generate_data.py    Generates the synthetic water usage dataset
|   |   |-- pipeline.py         Cleans and engineers features from the raw data
|   |   |-- train.py            Trains the XGBoost model and saves artifacts
|   |   |-- recommendation.py   Rule-based recommendation engine
|   |   `-- api.py              FastAPI application (the HTTP server)
|   |-- data/
|   |   |-- raw/                Raw CSV dataset
|   |   `-- processed/          Processed CSV dataset used by the model and API
|   |-- models/
|   |   |-- saved_model.pkl     Trained XGBoost model binary
|   |   |-- feature_importance.png
|   |   `-- actual_vs_predicted.png
|   |-- Dockerfile
|   `-- requirements.txt
|
|-- frontend/                   Next.js dashboard
|   |-- app/
|   |   |-- layout.tsx          Root HTML layout
|   |   |-- page.tsx            Main dashboard page
|   |   `-- globals.css         Design system and global styles
|   |-- lib/
|   |   `-- api.ts              Typed API client functions
|   |-- next.config.js
|   `-- package.json
|
|-- docker-compose.yml          Orchestrates backend + frontend together
|-- .env.example                Template for environment variables
`-- README.md

---

How It Works

1. Data generation — A synthetic dataset is created with realistic seasonal and weekly water usage patterns, including noise and controlled null values.
2. Feature engineering — The pipeline computes rolling averages, seasonal indicators, temperature effects, and weekly patterns from the raw CSV.
3. Model training — An XGBoost regressor is trained with early stopping on an 80/20 chronological split. The model must achieve R-squared above 0.80 or training fails.
4. Serving predictions — The FastAPI server loads the trained model on startup and exposes REST endpoints. On each prediction request, it re-engineers features using the latest historical data as context.
5. Recommendations — A rule-based engine analyzes the prediction and input conditions to generate prioritized conservation actions.
6. Dashboard — A Next.js frontend lets users adjust input sliders and instantly see predictions, 7-day forecasts, and historical usage charts.

---

Requirements

Backend

Dependency	Version
Python	3.10 or higher
pip	any recent version

Install Python from python.org.

Frontend

Dependency	Version
Node.js	18 or higher
npm	9 or higher

Install Node.js from nodejs.org.

Docker (optional)

Only needed if you want to run both services in containers.

Install Docker Desktop from docker.com.

---

Setup and Running the Project

Option A — Local development (recommended)

Run the backend and frontend in two separate terminal windows.

Step 1 — Copy environment variables

# In the project root (HydraAI 1.0/)
cp .env.example .env

On Windows:

Copy-Item .env.example .env

Step 2 — Create a Python virtual environment

# In the project root
python -m venv venv

Step 3 — Activate the virtual environment

On Windows (PowerShell):

.\venv\Scripts\Activate.ps1

On Mac and Linux:

source venv/bin/activate

Step 4 — Install backend dependencies

pip install -r backend/requirements.txt

Step 5 — Start the backend server

cd backend
uvicorn src.api:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000. Interactive API documentation is at http://localhost:8000/docs.

The model and data are already pre-trained and included. If you want to re-train from scratch, see Retraining the Model below.

Step 6 — Start the frontend (in a new terminal)

cd frontend
npm install
npm run dev

The dashboard will be available at http://localhost:3000.

---

Option B — Docker

Run both the backend and frontend as containers with a single command.

Step 1 — Copy environment variables

cp .env.example .env

Step 2 — Build and start all services

docker-compose up --build -d

Step 3 — Verify services are running

docker-compose ps
docker-compose logs backend

Stopping all services

docker-compose down

---

Retraining the Model

Only run these commands if you want to regenerate the dataset and retrain the model. The pre-trained model in backend/models/saved_model.pkl is already sufficient to run the project.

Run from the backend/ directory with the virtual environment active:

cd backend

# Step 1 — Generate raw dataset
python src/generate_data.py

# Step 2 — Process and engineer features
python src/pipeline.py

# Step 3 — Train and evaluate the model
python src/train.py

After training, the files in backend/models/ will be updated.

---

Environment Variables

Copy .env.example to .env and adjust if needed.

Variable	Default	Description
NEXT_PUBLIC_API_URL	http://localhost:8000	URL the frontend uses to reach the backend API
FRONTEND_URL	http://localhost:3000	URL the backend allows in its CORS policy

---

API Reference

All endpoints are served from the backend at http://localhost:8000.

Interactive documentation (Swagger UI) is available at http://localhost:8000/docs.

GET /api/health

Returns the current status of the server and whether the model is loaded.

Response

{
  "status": "ok",
  "model_loaded": true,
  "uptime_seconds": 312.5
}

---

POST /api/predict

Predicts water demand and returns conservation recommendations.

Request body

{
  "temperature": 25.0,
  "humidity": 60.0,
  "rainfall": 5.0,
  "occupancy_level": 0.7,
  "day_of_week": 1
}

Field	Type	Range	Description
temperature	float	-20 to 50	Air temperature in Celsius
humidity	float	0 to 100	Relative humidity in percent
rainfall	float	0 to 300	Rainfall in millimeters
occupancy_level	float	0.0 to 1.0	Building occupancy, 0 = empty
day_of_week	int	0 to 6	0 = Sunday, 6 = Saturday

Response

{
  "predicted_water_usage_liters": 15420.3,
  "confidence_interval": [14649.3, 16191.3],
  "demand_level": "medium",
  "recommendations": [
    {
      "category": "Maintenance",
      "icon": "Wrench",
      "action": "Review leak detection logs.",
      "impact": "Low",
      "savings_liters": 308.4,
      "priority": "low"
    }
  ],
  "sustainability_score": 19
}

---

GET /api/forecast/week

Generates a 7-day predicted usage forecast using the provided weather conditions.

Query parameters

Parameter	Type	Example
temperature	float	25
humidity	float	60
rainfall	float	5
occupancy_level	float	0.7

Example request

GET /api/forecast/week?temperature=25&humidity=60&rainfall=5&occupancy_level=0.7

Response

[
  { "day_offset": 0, "day_of_week": 1, "predicted_usage": 15380.2 },
  { "day_offset": 1, "day_of_week": 2, "predicted_usage": 14900.5 }
]

---

GET /api/history

Returns the last 90 days of processed historical water usage data.

Response

[
  { "date": "2024-10-01", "water_usage_liters": 14523.1, "temperature": 22.4, ... }
]

---

Frontend Features

Feature	Description
Predict tab	Adjust sliders for weather and occupancy, then run a live prediction
Conservation panel	Prioritized action recommendations with estimated water savings
Sustainability score	A 0-100 score showing how much water could be saved given the conditions
7-Day Forecast tab	Bar chart of predicted usage for each day of the upcoming week
History tab	Area chart of the last 30 days from the processed dataset
Status bar	Live indicator showing whether the backend model is loaded and the uptime
API Docs link	Direct link to the FastAPI Swagger documentation

---

Model Details

Property	Value
Algorithm	XGBoost Regressor
Target	Daily water usage in liters
Train/test split	80% train, 20% test (chronological)
Validation	10% of training set for early stopping
Min. R-squared	0.80 (enforced by an assertion in train.py)
Saved artifact	backend/models/saved_model.pkl

Input features used by the model

Feature	Description
temperature	Air temperature in Celsius
humidity	Relative humidity in percent
rainfall	Precipitation in millimeters
occupancy_level	Building occupancy fraction
rolling_mean_usage	Average usage over the last 7 days
day_of_week	Day index (0 = Sunday)
season_indicator	Season index derived from calendar month
temperature_effect	Scaled interaction of temperature and 7-day mean
weekly_pattern	Historical mean usage for the same day of week

---

Troubleshooting

Backend says model is not loaded

The API starts but logs a load error. Make sure you are running the server from the backend/ directory, not from the project root:

cd backend
uvicorn src.api:app --host 0.0.0.0 --port 8000

Frontend cannot reach the backend

Check that the backend is running on port 8000. If you changed the port, update NEXT_PUBLIC_API_URL in your .env file and restart the frontend.

npm commands fail with "Cannot find package.json"

The package.json is inside the frontend/ directory. Always run npm commands from there:

cd frontend
npm install
npm run dev

Docker build fails

Make sure the Docker daemon is running (Docker Desktop must be open on Windows). Then try:

docker-compose down
docker-compose up --build