Update README.md

README.md

@@ -1,47 +1,42 @@
----
-license: mit
-title: Bihar AgMCP
-sdk: gradio
-emoji: 🐢
-colorFrom: red
-colorTo: red
-pinned: false
----
-Bihar AgMCP - Agricultural Weather Alert System Documentation
-Table of Contents
-System Overview
-Architecture
-Installation & Setup
-Core Components
-Server-side
-Client-side
-API Reference
-Data Models
-Configuration
-Deployment
-Troubleshooting
-Contributing
-
-System Overview
-Purpose
+# Bihar AgMCP - Agricultural Weather Alert System
+
+## Table of Contents
+- [System Overview](#system-overview)
+- [Architecture](#architecture)
+- [Installation & Setup](#installation--setup)
+- [Core Components](#core-components)
+- [API Reference](#api-reference)
+- [Data Models](#data-models)
+- [Configuration](#configuration)
+- [Deployment](#deployment)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+
+## System Overview
+
+### Purpose
 The Bihar AgMCP (Agricultural Model Control Protocol) is an AI-powered weather alert system designed to provide personalized agricultural advisories to farmers in Bihar, India. The system generates location-specific weather alerts with crop-specific recommendations.
-Key Features
-AI-Enhanced Weather Alerts: OpenAI-powered intelligent alert generation
-Multi-Channel Communication: SMS, WhatsApp, USSD, IVR, and Telegram support
-Regional Crop Intelligence: District-specific crop recommendations based on seasons
-Real-time Weather Data: Integration with multiple weather APIs
-Geographic Intelligence: Village-level weather data and coordinates
-Web Interface: User-friendly Gradio interface for easy access
-CSV Export: Data export functionality for analysis
-Target Users
-Agricultural extension workers
-Farmers and farmer organizations
-Government agricultural departments
-Research institutions
-NGOs working in agriculture
-
-Architecture
-System Architecture Diagram
+
+### Key Features
+- **AI-Enhanced Weather Alerts**: OpenAI-powered intelligent alert generation
+- **Multi-Channel Communication**: SMS, WhatsApp, USSD, IVR, and Telegram support
+- **Regional Crop Intelligence**: District-specific crop recommendations based on seasons
+- **Real-time Weather Data**: Integration with multiple weather APIs
+- **Geographic Intelligence**: Village-level weather data and coordinates
+- **Web Interface**: User-friendly Gradio interface for easy access
+- **CSV Export**: Data export functionality for analysis
+
+### Target Users
+- Agricultural extension workers
+- Farmers and farmer organizations
+- Government agricultural departments
+- Research institutions
+- NGOs working in agriculture
+
+## Architecture
+
+### System Architecture Diagram
+```
 ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
 │   Weather APIs  │    │   OpenAI API    │    │ Geographic APIs │
 │                 │    │                 │    │                 │
@@ -70,73 +65,102 @@ System Architecture Diagram
 │ • USSD/IVR      │    │ • District Sel  │    │ • JSON-RPC      │
 │ • Telegram      │    │                 │    │                 │
 └─────────────────┘    └─────────────────┘    └─────────────────┘
-Technology Stack
-Backend: FastAPI (Python 3.8+)
-AI: OpenAI GPT 
-Weather Data: Open-Meteo, Tomorrow.io, OpenWeatherMap
-Frontend: Gradio
-Data Processing: Pandas, CSV
-Async Operations: asyncio
-Configuration: dotenv
-Logging: Python logging
-
-Installation & Setup
-Prerequisites
-Python 3.8 or higher
-pip package manager
-Internet connection for API access
-Environment Setup
-Clone the repository
-git clone <repository-url>
-cd bihar-agmcp
-Install dependencies
-pip install fastapi uvicorn gradio pandas python-dotenv pydantic
-Create environment file Create a .env file in the root directory:
-# Required
-OPENAI_API_KEY=your_openai_api_key_here
-
-# Optional Weather APIs
-TOMORROW_IO_API_KEY=your_tomorrow_io_key
-GOOGLE_WEATHER_API_KEY=your_google_weather_key
-OPENWEATHERMAP_API_KEY=your_openweathermap_key
-ACCUWEATHER_API_KEY=your_accuweather_key
-
-# Logging
-LOG_LEVEL=INFO
-Tool dependencies Ensure the following modules are available:
-tools/ - Weather and geographic tools
-a2a_agents/ - Communication agents
-utils/ - Utility functions
-Quick Start
+```
+
+### Technology Stack
+- **Backend**: FastAPI (Python 3.8+)
+- **AI**: OpenAI GPT 
+- **Weather Data**: Open-Meteo, Tomorrow.io, OpenWeatherMap
+- **Frontend**: Gradio
+- **Data Processing**: Pandas, CSV
+- **Async Operations**: asyncio
+- **Configuration**: dotenv
+- **Logging**: Python logging
+
+## Installation & Setup
+
+### Prerequisites
+- Python 3.8 or higher
+- pip package manager
+- Internet connection for API access
+
+### Environment Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd bihar-agmcp
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install fastapi uvicorn gradio pandas python-dotenv pydantic
+   ```
+
+3. **Create environment file**
+   Create a `.env` file in the root directory:
+   ```env
+   # Required
+   OPENAI_API_KEY=your_openai_api_key_here
+   
+   # Optional Weather APIs
+   TOMORROW_IO_API_KEY=your_tomorrow_io_key
+   GOOGLE_WEATHER_API_KEY=your_google_weather_key
+   OPENWEATHERMAP_API_KEY=your_openweathermap_key
+   ACCUWEATHER_API_KEY=your_accuweather_key
+   
+   # Logging
+   LOG_LEVEL=INFO
+   ```
+
+4. **Tool dependencies**
+   Ensure the following modules are available:
+   - `tools/` - Weather and geographic tools
+   - `a2a_agents/` - Communication agents
+   - `utils/` - Utility functions
+
+### Quick Start
+```bash
 python main.py
+```
+
+## Core Components
+
+### 1. Server-side
+
+#### a. Alert Generation Engine
+- **Primary Function**: `generate_dynamic_alert(district, state)`
+- **Purpose**: Generates comprehensive weather alerts for specific districts.
 
-Core Components
-1. Server-side
-Alert Generation Engine
-Primary Function: generate_dynamic_alert(district, state)
-Generates comprehensive weather alerts for specific districts.
-Process Flow:
-Village Selection: Randomly selects a village from the district
-Coordinate Resolution: Gets GPS coordinates for location
-Crop Intelligence: Selects appropriate crop based on:
-Current season (Kharif/Rabi/Zaid)
-District crop preferences
-Regional agricultural patterns
-Weather Data Collection: Fetches weather data from APIs
-Alert Generation: Creates weather-based alerts
-AI Enhancement: Applies OpenAI analysis (if available)
-Example Usage:
+**Process Flow:**
+1. **Village Selection**: Randomly selects a village from the district
+2. **Coordinate Resolution**: Gets GPS coordinates for location
+3. **Crop Intelligence**: Selects appropriate crop based on:
+   - Current season (Kharif/Rabi/Zaid)
+   - District crop preferences
+   - Regional agricultural patterns
+4. **Weather Data Collection**: Fetches weather data from APIs
+5. **Alert Generation**: Creates weather-based alerts
+6. **AI Enhancement**: Applies OpenAI analysis (if available)
+
+**Example Usage:**
+```python
 alert_data = await generate_dynamic_alert("Patna", "Bihar")
-      b. Crop Calendar System
-Crop Definitions
+```
+
+#### b. Crop Calendar System
+
+**Crop Definitions**
 The system includes detailed crop calendars for major Bihar crops:
-Rice (Kharif): June-July planting, October-November harvest
-Wheat (Rabi): November-December planting, March-April harvest
-Maize (Kharif/Zaid): Dual season crop
-Sugarcane (Annual): February-March planting
-Mustard (Rabi): October-November planting
-District Crop Mapping
+- **Rice (Kharif)**: June-July planting, October-November harvest
+- **Wheat (Rabi)**: November-December planting, March-April harvest
+- **Maize (Kharif/Zaid)**: Dual season crop
+- **Sugarcane (Annual)**: February-March planting
+- **Mustard (Rabi)**: October-November planting
+
+**District Crop Mapping**
 Each district has specific crop preferences:
+```python
 DISTRICT_CROPS = {
     'patna': {
         'primary': ['rice', 'wheat', 'potato'], 
@@ -145,64 +169,94 @@ DISTRICT_CROPS = {
     },
     # ... other districts
 }
-      c. Weather Integration
-Supported Weather APIs
-Open-Meteo (Primary): Free, reliable weather data
-Tomorrow.io: Professional weather services
-OpenWeatherMap: Popular weather API
-AccuWeather: Commercial weather data
-Google Weather: Google's weather services
-Weather Alert Types
-Heavy Rain Warning: >25mm rainfall expected
-Moderate Rain Warning: 10-25mm rainfall expected
-Heat/Drought Warning: High temperature + low rainfall
-Cold Warning: Temperature <10°C
-High Wind Warning: Wind speed >30 km/h
-Weather Update: Normal conditions
-2. Client-side
-A2A Communication Agents
-SMS Agent
+```
+
+#### c. Weather Integration
+
+**Supported Weather APIs:**
+- **Open-Meteo** (Primary): Free, reliable weather data
+- **Tomorrow.io**: Professional weather services
+- **OpenWeatherMap**: Popular weather API
+- **AccuWeather**: Commercial weather data
+- **Google Weather**: Google's weather services
+
+**Weather Alert Types:**
+- **Heavy Rain Warning**: >25mm rainfall expected
+- **Moderate Rain Warning**: 10-25mm rainfall expected
+- **Heat/Drought Warning**: High temperature + low rainfall
+- **Cold Warning**: Temperature <10°C
+- **High Wind Warning**: Wind speed >30 km/h
+- **Weather Update**: Normal conditions
+
+### 2. Client-side
+
+#### A2A Communication Agents
+
+**SMS Agent**
 Creates concise SMS messages (160 characters max):
+```python
 def create_sms_message(alert_data):
     return f"BIHAR ALERT: {crop} in {location} - {weather_summary}"
-WhatsApp Agent
+```
+
+**WhatsApp Agent**
 Generates rich WhatsApp messages with emojis and formatting:
+```python
 def create_whatsapp_message(alert_data):
     return {
         "text": formatted_message,
         "buttons": action_buttons
     }
-USSD Agent
+```
+
+**USSD Agent**
 Creates interactive USSD menu structures:
+```python
 def create_ussd_menu(alert_data):
     return {
         "menu": "CON Weather Alert...\n1. Details\n2. Actions"
     }
-IVR Agent
+```
+
+**IVR Agent**
 Generates voice script for phone systems:
+```python
 def create_ivr_script(alert_data):
     return {
         "script": "Welcome to Bihar weather alert...",
         "menu_options": [...]
     }
-Telegram Agent
+```
+
+**Telegram Agent**
 Creates Telegram messages with inline keyboards:
+```python
 def create_telegram_message(alert_data):
     return {
         "text": message,
         "reply_markup": inline_keyboard
     }
+```
+
+## API Reference
 
-API Reference
-Core Endpoints
-1. Workflow Execution
+### Core Endpoints
+
+#### 1. Workflow Execution
+```http
 POST /api/run-workflow
-Request Body:
+```
+
+**Request Body:**
+```json
 {
     "state": "bihar",
     "district": "patna"
 }
-Response:
+```
+
+**Response:**
+```json
 {
     "message": "workflow_results",
     "status": "success",
@@ -212,17 +266,29 @@ Response:
         "agent_responses": {...}
     }
 }
-2. Health Check
+```
+
+#### 2. Health Check
+```http
 GET /api/health
-Response:
+```
+
+**Response:**
+```json
 {
     "status": "healthy",
     "openai_available": true,
     "timestamp": "2025-08-13T10:30:00"
 }
-3. MCP Tool Execution
+```
+
+#### 3. MCP Tool Execution
+```http
 POST /mcp
-Request Body:
+```
+
+**Request Body:**
+```json
 {
     "tool": "get_current_weather",
     "parameters": {
@@ -230,36 +296,50 @@ Request Body:
         "longitude": 85.1376
     }
 }
-4. Geographic Data
+```
+
+#### 4. Geographic Data
+```http
 GET /api/districts/{state}
 GET /api/villages/{state}/{district}
-5. Weather Data
+```
+
+#### 5. Weather Data
+```http
 GET /api/weather/{latitude}/{longitude}
-A2A Agent Endpoints
-SMS
-POST /a2a/sms
-WhatsApp
-POST /a2a/whatsapp
-USSD
-POST /a2a/ussd
-IVR
-POST /a2a/ivr
-Telegram
-POST /a2a/telegram
-
-Data Models
-AlertRequest
+```
+
+### A2A Agent Endpoints
+- **SMS**: `POST /a2a/sms`
+- **WhatsApp**: `POST /a2a/whatsapp`
+- **USSD**: `POST /a2a/ussd`
+- **IVR**: `POST /a2a/ivr`
+- **Telegram**: `POST /a2a/telegram`
+
+## Data Models
+
+### AlertRequest
+```python
 class AlertRequest(BaseModel):
     alert_json: dict
-WorkflowRequest
+```
+
+### WorkflowRequest
+```python
 class WorkflowRequest(BaseModel):
     state: str
     district: str
-MCPRequest
+```
+
+### MCPRequest
+```python
 class MCPRequest(BaseModel):
     tool: str
     parameters: dict
-Alert Data Structure
+```
+
+### Alert Data Structure
+```json
 {
     "alert_id": "BH_PAT_VIL_20250813_103000",
     "timestamp": "2025-08-13T10:30:00Z",
@@ -290,18 +370,24 @@ Alert Data Structure
         "rain_probability": "85%"
     }
 }
+```
+
+## Configuration
+
+### Environment Variables
+
+#### Required
+- `OPENAI_API_KEY`: OpenAI API key for AI features
+
+#### Optional
+- `TOMORROW_IO_API_KEY`: Tomorrow.io weather API
+- `GOOGLE_WEATHER_API_KEY`: Google Weather API
+- `OPENWEATHERMAP_API_KEY`: OpenWeatherMap API
+- `ACCUWEATHER_API_KEY`: AccuWeather API
+- `LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)
 
-Configuration
-Environment Variables
-Required
-OPENAI_API_KEY: OpenAI API key for AI features
-Optional
-TOMORROW_IO_API_KEY: Tomorrow.io weather API
-GOOGLE_WEATHER_API_KEY: Google Weather API
-OPENWEATHERMAP_API_KEY: OpenWeatherMap API
-ACCUWEATHER_API_KEY: AccuWeather API
-LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
-CORS Configuration
+### CORS Configuration
+```python
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["https://mcp-ui.vercel.app", "*"],
@@ -309,19 +395,27 @@ app.add_middleware(
     allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allow_headers=["*"]
 )
-Bihar Districts Configuration
+```
+
+### Bihar Districts Configuration
 The system supports 39 Bihar districts:
-Patna, Gaya, Bhagalpur, Muzaffarpur, Darbhanga
-Siwan, Begusarai, Katihar, Nalanda, Rohtas
-And 29 others...
+- Patna, Gaya, Bhagalpur, Muzaffarpur, Darbhanga
+- Siwan, Begusarai, Katihar, Nalanda, Rohtas
+- And 29 others...
+
+## Deployment
 
-Deployment
-Local Development
+### Local Development
+```bash
 python main.py
-FastAPI server: http://localhost:8000
-Gradio interface: http://localhost:7860
-Production Deployment
-Docker Deployment
+```
+- FastAPI server: http://localhost:8000
+- Gradio interface: http://localhost:7860
+
+### Production Deployment
+
+#### Docker Deployment
+```dockerfile
 FROM python:3.9-slim
 
 WORKDIR /app
@@ -332,62 +426,91 @@ COPY . .
 EXPOSE 8000 7860
 
 CMD ["python", "main.py"]
-HuggingFace Spaces
+```
+
+#### HuggingFace Spaces
 The application automatically detects HuggingFace Spaces environment and configures accordingly:
+```python
 if os.getenv("SPACE_ID") or os.getenv("GRADIO_SERVER_NAME"):
     # HuggingFace Spaces mode
     fastapi_thread = threading.Thread(target=run_fastapi, daemon=True)
     fastapi_thread.start()
     demo.launch(server_name="0.0.0.0", server_port=7860)
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. OpenAI API Key Missing
+- **Error**: `OpenAI API key not found - AI features will be limited`
+- **Solution**: Add `OPENAI_API_KEY` to `.env` file
+
+#### 2. Weather API Failures
+- **Error**: `Failed to get weather data`
+- **Solutions**:
+  - Check internet connectivity
+  - Verify API keys in `.env`
+  - Check API quotas and limits
 
+#### 3. Geographic Data Issues
+- **Error**: `District 'xyz' not found in Bihar`
+- **Solutions**:
+  - Use correct district spelling
+  - Check district name in `BIHAR_DISTRICTS` list
+  - Verify state parameter is "bihar"
 
+#### 4. Import Errors
+- **Error**: `ModuleNotFoundError: No module named 'tools'`
+- **Solution**: Ensure all required modules are in the project directory:
+  - `tools/`
+  - `a2a_agents/`
+  - `utils/`
 
-Troubleshooting
-Common Issues
-1. OpenAI API Key Missing
-Error: OpenAI API key not found - AI features will be limited Solution: Add OPENAI_API_KEY to .env file
-2. Weather API Failures
-Error: Failed to get weather data Solutions:
-Check internet connectivity
-Verify API keys in .env
-Check API quotas and limits
-3. Geographic Data Issues
-Error: District 'xyz' not found in Bihar Solutions:
-Use correct district spelling
-Check district name in BIHAR_DISTRICTS list
-Verify state parameter is "bihar"
-4. Import Errors
-Error: ModuleNotFoundError: No module named 'tools' Solution: Ensure all required modules are in the project directory:
-tools/
-a2a_agents/
-utils/
-Logging and Debugging
-Enable Debug Logging
+### Logging and Debugging
+
+#### Enable Debug Logging
+```bash
 export LOG_LEVEL=DEBUG
 python main.py
-Check Log Output
+```
+
+#### Check Log Output
+```python
 logger.info(f"Selected village: {village}")
 logger.error(f"Weather API error: {error}")
-Performance Optimization
-1. API Response Caching
+```
+
+### Performance Optimization
+
+#### 1. API Response Caching
 Consider implementing Redis caching for weather data:
+```python
 # Pseudo-code
 @cache.cached(timeout=300)  # 5 minute cache
 async def get_weather_data(lat, lon):
     return await weather_api.fetch(lat, lon)
-2. Database Integration
+```
+
+#### 2. Database Integration
 For production, consider using PostgreSQL/MongoDB:
+```python
 # Store alert history
 await db.alerts.insert_one(alert_data)
+```
 
-Contributing
-Development Guidelines
-1. Code Style
-Follow PEP 8 Python style guide
-Use type hints for function parameters
-Add docstrings for all functions
-Maximum line length: 100 characters
-2. Testing
+## Contributing
+
+### Development Guidelines
+
+#### 1. Code Style
+- Follow PEP 8 Python style guide
+- Use type hints for function parameters
+- Add docstrings for all functions
+- Maximum line length: 100 characters
+
+#### 2. Testing
+```python
 import pytest
 
 def test_crop_selection():
@@ -397,28 +520,42 @@ def test_crop_selection():
 async def test_weather_api():
     result = await open_meteo.get_current_weather(25.5941, 85.1376)
     assert "temperature" in result
-3. Documentation
-Update this documentation for new features
-Add inline comments for complex logic
-Create examples for new API endpoints
-4. Version Control
+```
+
+#### 3. Documentation
+- Update this documentation for new features
+- Add inline comments for complex logic
+- Create examples for new API endpoints
+
+#### 4. Version Control
+```bash
 git checkout -b feature/new-weather-provider
 git commit -m "Add new weather API integration"
 git push origin feature/new-weather-provider
-Adding New Features
-1. New Weather Provider
+```
+
+### Adding New Features
+
+#### 1. New Weather Provider
+```python
 # tools/new_weather_api.py
 async def get_current_weather(latitude, longitude, api_key):
     # Implementation
     return weather_data
-2. New Communication Channel
+```
+
+#### 2. New Communication Channel
+```python
 # a2a_agents/slack_agent.py
 def create_slack_message(alert_data):
     return {
         "text": message,
         "attachments": []
     }
-3. New Crop Types
+```
+
+#### 3. New Crop Types
+```python
 CROP_CALENDAR["new_crop"] = {
     "season": "Rabi",
     "planting": "December",
@@ -426,6 +563,8 @@ CROP_CALENDAR["new_crop"] = {
     "duration_days": 150,
     "stages": ["Sowing", "Growth", "Harvest"]
 }
+```
 
+---
 
-Last Updated: August 13, 2025.
+**Last Updated**: August 13, 2025