Spaces:

JalGuard
/

Rural_Water

Sleeping

Rural_Water / DETAILED_README.md

KaustavMP

Update changes

c1f92c2 7 months ago

11.7 kB

# JalGuard - Rural Water Intelligence Platform

[![Hugging Face Spaces](https://img.shields.io/badge/Hugging%20Face-Spaces-orange)](https://huggingface.co/spaces/JalGuard/Rural_Water)
[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/Kaustavmp/Rural_Water)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-green)](https://fastapi.tiangolo.com/)

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**
   ```bash
   git clone https://github.com/Kaustavmp/Rural_Water.git
   cd Rural_Water_env
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Set environment variables**
   ```bash
   # Create .env file
   echo "OPENAI_API_KEY=your_key_here" > .env
   ```

4. **Start the application**
   ```powershell
   # 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
```bash
# .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
```bash
python start_jalguard.py
# Navigate to http://127.0.0.1:7860/dashboard
```

### Running Inference
```bash
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
```python
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:
```python
requests.post("http://localhost:7860/api/tasks/load", 
              json={"task_id": "drought_response"})
```

---

## 🐳 Docker Deployment

### Build Docker Image
```bash
docker build -t jalguard:latest .
```

### Run Container
```bash
docker run -p 7860:7860 \
  -e OPENAI_API_KEY=your_key \
  jalguard:latest
```

### Deploy to Hugging Face Spaces
The project includes HF Spaces integration:
```bash
git push hf master
```

---

## 📊 Logging & Analytics

### Episode Logs
Structured logs are saved in `backend/data/logs/episodes.jsonl`:
```json
{
  "episode": 1,
  "scenario": "drought_response",
  "actions": [...],
  "total_reward": 42.5,
  "timestamp": "2026-04-12T10:30:00"
}
```

### View Logs
```python
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:
```python
from backend.services.ai_service import AIService
ai = AIService(config)
response = ai.chat(message="How to handle drought?")
```

### OpenEnv Compatibility
Implements OpenEnv environment interface:
```python
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
```bash
# 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:
```bash
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
```bash
# Use a different port
uvicorn backend.main:app --port 8080
```

### Missing API Key
```bash
# Set API key before running
export OPENAI_API_KEY=your_key_here
python start_jalguard.py
```

### Module Import Errors
```bash
# Reinstall dependencies
pip install --upgrade -r requirements.txt
```

### Clear Cache
```bash
# 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](https://github.com/Kaustavmp)
- Repository: [Rural_Water](https://github.com/Kaustavmp/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](https://fastapi.tiangolo.com/)
- [OpenEnv Documentation](https://docs.openenv.org/)
- [OpenAI API Reference](https://platform.openai.com/docs/)
- [Hugging Face Spaces](https://huggingface.co/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.

	# JalGuard - Rural Water Intelligence Platform

	[![Hugging Face Spaces](https://img.shields.io/badge/Hugging%20Face-Spaces-orange)](https://huggingface.co/spaces/JalGuard/Rural_Water)
	[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/Kaustavmp/Rural_Water)
	[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
	[![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-green)](https://fastapi.tiangolo.com/)

	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
	```bash
	git clone https://github.com/Kaustavmp/Rural_Water.git
	cd Rural_Water_env
	```

	2. Install dependencies
	```bash
	pip install -r requirements.txt
	```

	3. Set environment variables
	```bash
	# Create .env file
	echo "OPENAI_API_KEY=your_key_here" > .env
	```

	4. Start the application
	```powershell
	# 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
	```bash
	# .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
	```bash
	python start_jalguard.py
	# Navigate to http://127.0.0.1:7860/dashboard
	```

	### Running Inference
	```bash
	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
	```python
	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:
	```python
	requests.post("http://localhost:7860/api/tasks/load",
	json={"task_id": "drought_response"})
	```

	---

	## 🐳 Docker Deployment

	### Build Docker Image
	```bash
	docker build -t jalguard:latest .
	```

	### Run Container
	```bash
	docker run -p 7860:7860 \
	-e OPENAI_API_KEY=your_key \
	jalguard:latest
	```

	### Deploy to Hugging Face Spaces
	The project includes HF Spaces integration:
	```bash
	git push hf master
	```

	---

	## 📊 Logging & Analytics

	### Episode Logs
	Structured logs are saved in `backend/data/logs/episodes.jsonl`:
	```json
	{
	"episode": 1,
	"scenario": "drought_response",
	"actions": [...],
	"total_reward": 42.5,
	"timestamp": "2026-04-12T10:30:00"
	}
	```

	### View Logs
	```python
	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:
	```python
	from backend.services.ai_service import AIService

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

	### OpenEnv Compatibility
	Implements OpenEnv environment interface:
	```python
	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
	```bash
	# 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:
	```bash
	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
	```bash
	# Use a different port
	uvicorn backend.main:app --port 8080
	```

	### Missing API Key
	```bash
	# Set API key before running
	export OPENAI_API_KEY=your_key_here
	python start_jalguard.py
	```

	### Module Import Errors
	```bash
	# Reinstall dependencies
	pip install --upgrade -r requirements.txt
	```

	### Clear Cache
	```bash
	# 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](https://github.com/Kaustavmp)
	- Repository: [Rural_Water](https://github.com/Kaustavmp/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](https://fastapi.tiangolo.com/)
	- [OpenEnv Documentation](https://docs.openenv.org/)
	- [OpenAI API Reference](https://platform.openai.com/docs/)
	- [Hugging Face Spaces](https://huggingface.co/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.