DETAILED_README.md

JalGuard - Rural Water Intelligence Platform

JalGuard is an OpenEnv-compatible intelligent water management platform designed for rural community water systems. It leverages AI-powered decision making, environmental simulation, and real-time analytics to optimize water resource allocation and crisis response.

---

🌟 Features

Core Capabilities

• Live Dashboard Control Center - Real-time monitoring and manual control of water systems
• Scenario Builder - Create and simulate custom water management scenarios
• Analytics & Reports - Comprehensive data visualization and performance metrics
• Admin Panel - Developer tools, validation utilities, and system diagnostics
• AI Copilot - Conversational interface with GPT-powered water management advice
• OpenEnv Integration - Compatible with OpenEnv gym-like environment simulation

Technical Highlights

• Modular FastAPI Backend - RESTful APIs for all platform operations
• Conversational AI - Integration with OpenAI GPT models
• Structured Logging - Episode-based logging for training and analysis
• Multi-Scenario Support - Predefined and custom scenario management
• Docker Ready - Containerized deployment for HuggingFace Spaces & Docker

---

📁 Project Structure

Rural_Water_env/
├── backend/                      # FastAPI application core
│   ├── api/                      # API route handlers
│   │   ├── routes_admin.py      # Admin endpoints
│   │   ├── routes_ai.py         # AI/Copilot endpoints
│   │   ├── routes_env.py        # Environment control endpoints
│   │   └── routes_tasks.py      # Task management endpoints
│   ├── core/                    # Core logic
│   │   ├── environment.py       # Water environment simulation
│   │   ├── actions.py           # Action definitions
│   │   ├── state.py             # State management
│   │   └── config.py            # Configuration
│   ├── services/                # Business logic services
│   │   ├── ai_service.py        # OpenAI integration
│   │   ├── scenario_chat.py     # Scenario-based conversations
│   │   ├── scenario_loader.py   # Scenario loading & parsing
│   │   └── logger.py            # Episode logging
│   ├── tasks/                   # Predefined scenarios
│   │   ├── drought_response.py
│   │   ├── monsoon_overflow.py
│   │   ├── festival_high_demand.py
│   │   ├── emergency_shortage_mgmt.py
│   │   ├── tank_leakage_crisis.py
│   │   ├── odisha_survival.py
│   │   ├── custom_user_scenario.py
│   │   └── registry.py          # Scenario registry
│   ├── utils/                   # Utilities
│   │   ├── validators.py        # Input validation
│   │   └── exceptions.py        # Custom exceptions
│   ├── data/                    # Data storage
│   │   ├── logs/               # Episode logs
│   │   └── scenarios/          # Scenario configurations
│   ├── static/                 # Frontend assets
│   │   ├── dashboard.html
│   │   ├── scenario.html
│   │   ├── analytics.html
│   │   ├── admin.html
│   │   ├── settings.html
│   │   ├── css/
│   │   └── js/
│   └── main.py                # FastAPI app entry point
├── inference.py               # Standalone inference script
├── models.py                  # Model definitions
├── app.py                     # Alternative app entry
├── main.py                    # Root level main
├── start_jalguard.py         # Startup script
├── Dockerfile                # Docker configuration
├── pyproject.toml            # Python package config
├── requirements.txt          # Python dependencies
└── README.md                 # Quick start guide

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• pip or conda
• OpenAI API Key (for AI features)

Installation

1. Clone the repository

   git clone https://github.com/Kaustavmp/Rural_Water.git
   cd Rural_Water_env
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set environment variables

   # Create .env file
   echo "OPENAI_API_KEY=your_key_here" > .env
   

4. Start the application

   # Option 1: Using startup script
   python start_jalguard.py
   
   # Option 2: Using uvicorn directly
   uvicorn backend.main:app --host 0.0.0.0 --port 7860
   

5. Access the platform

   • Dashboard: http://127.0.0.1:7860/dashboard
   • API Docs: http://127.0.0.1:7860/docs

---

🔧 Configuration

Environment Variables

Variable	Default	Description
OPENAI_API_KEY	Required	OpenAI API key for AI features
API_BASE_URL	https://api.openai.com/v1	OpenAI API endpoint
MODEL_NAME	gpt-4o-mini	Model for AI copilot
LOG_DIR	backend/data/logs	Logging directory
SCENARIOS_DIR	backend/data/scenarios	Scenarios directory

Load from .env file

# .env
OPENAI_API_KEY=sk-...
MODEL_NAME=gpt-4o-mini

---

📡 API Overview

Base URL

http://localhost:7860/api

Main Endpoints

Environment Control (/api/env)

• POST /reset - Initialize environment
• POST /step - Execute action
• GET /state - Get current state
• POST /render - Get visual representation

Scenarios (/api/tasks)

• GET /list - List all scenarios
• POST /load - Load specific scenario
• GET /{task_id}/info - Get scenario metadata

AI Copilot (/api/ai)

• POST /chat - Conversational query
• POST /advise - Get AI recommendations
• POST /analyze - Analyze current state

Admin (/api/admin)

• GET /stats - System statistics
• POST /validate - Validation tools
• GET /logs - Access logs and episodes

---

💻 Usage Examples

Running the Dashboard

python start_jalguard.py
# Navigate to http://127.0.0.1:7860/dashboard

Running Inference

python inference.py

The inference script generates structured logs:

[START] {"scenario": "drought_response", "episode": 1}
[STEP] {"action": "reduce_supply", "reward": 0.85}
[END] {"total_reward": 42.5, "success": true}

Using the API

import requests

# Initialize environment
response = requests.post("http://localhost:7860/api/env/reset", 
                        json={"scenario": "drought_response"})
state = response.json()

# Execute action
action = {"type": "reduce_supply", "amount": 30}
response = requests.post("http://localhost:7860/api/env/step", json=action)
new_state = response.json()

---

🎯 Scenarios

JalGuard includes pre-built water management scenarios:

1. Drought Response - Managing severe water scarcity
2. Monsoon Overflow - Handling excess water during monsoons
3. Emergency Shortage - Crisis management protocols
4. Festival High Demand - Managing peak usage periods
5. Tank Leakage Crisis - Responding to infrastructure failures
6. Odisha Survival - Region-specific challenges
7. Custom Scenarios - User-defined situations

Load a scenario:

requests.post("http://localhost:7860/api/tasks/load", 
              json={"task_id": "drought_response"})

---

🐳 Docker Deployment

Build Docker Image

docker build -t jalguard:latest .

Run Container

docker run -p 7860:7860 \
  -e OPENAI_API_KEY=your_key \
  jalguard:latest

Deploy to Hugging Face Spaces

The project includes HF Spaces integration:

git push hf master

---

📊 Logging & Analytics

Episode Logs

Structured logs are saved in backend/data/logs/episodes.jsonl:

{
  "episode": 1,
  "scenario": "drought_response",
  "actions": [...],
  "total_reward": 42.5,
  "timestamp": "2026-04-12T10:30:00"
}

View Logs

from backend.services.logger import EpisodeLogger

logger = EpisodeLogger("path/to/episodes.jsonl")
episodes = logger.load_episodes()

---

🔌 Integration Points

OpenAI Integration

Uses OpenAI GPT models for AI copilot:

from backend.services.ai_service import AIService

ai = AIService(config)
response = ai.chat(message="How to handle drought?")

OpenEnv Compatibility

Implements OpenEnv environment interface:

from backend.core.environment import WaterEnvironment

env = WaterEnvironment()
state, reward, done, info = env.step(action)

---

📝 Development

Code Structure

• Core Logic - backend/core/
• API Routes - backend/api/
• Business Services - backend/services/
• Data & Config - backend/data/ & backend/core/config.py
• Utilities - backend/utils/

Key Modules

• environment.py - Main simulation engine
• ai_service.py - LLM interactions
• scenario_loader.py - Configuration management
• logger.py - Episode tracking

Testing Inference

# Standalone inference
python inference.py

# Check output logs
cat backend/data/logs/episodes.jsonl | tail -5

---

📋 Requirements

See requirements.txt for full dependencies:

• fastapi ≥0.104.0
• uvicorn ≥0.24.0
• pydantic ≥2.0.0
• numpy ≥1.26.0
• openai ≥2.7.2
• openenv-core ≥0.2.3
• python-dotenv ≥1.0.0
• requests ≥2.32.0
• PyYAML ≥6.0

---

🚢 Deployment

GitHub

Push to main repository:

git push origin master

Hugging Face Spaces

Automatic deployment via git push hf master (HF remote configured).

CI/CD

The project is set up for automated deployments with Dockerfile.

---

🐛 Troubleshooting

Port Already in Use

# Use a different port
uvicorn backend.main:app --port 8080

Missing API Key

# Set API key before running
export OPENAI_API_KEY=your_key_here
python start_jalguard.py

Module Import Errors

# Reinstall dependencies
pip install --upgrade -r requirements.txt

Clear Cache

# Remove cached files
rm -rf backend/__pycache__ backend/*/__pycache__
pip cache purge

---

📄 License

This project is licensed under the Other License. See LICENSE file for details.

---

👤 Author

Kaustav Priyam Mohanty

• GitHub: @Kaustavmp
• Repository: Rural_Water

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your fork
5. Submit a pull request

---

📚 Resources

• FastAPI Documentation
• OpenEnv Documentation
• OpenAI API Reference
• Hugging Face Spaces

---

🎓 Project Status

• Version: 1.0.0
• Status: Active Development
• Last Updated: April 12, 2026
• Python: 3.10+

For issues, feature requests, or questions, please open an issue on GitHub.