# 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.