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 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 ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Weather APIs │ │ OpenAI API │ │ Geographic APIs │ │ │ │ │ │ │ │ • Open-Meteo │ │ • GPT Models │ │ • Geocoding │ │ • Tomorrow.io │ │ • Alert Gen │ │ • Village Data │ │ • OpenWeather │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ └───────────────────────┼───────────────────────┘ │ ┌─────────────────┐ │ FastAPI Core │ │ │ │ • Alert Engine │ │ • Crop Calendar │ │ • Workflow Mgmt │ └─────────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ A2A Agents │ │ Web Interface │ │ API Clients │ │ │ │ │ │ │ │ • SMS Agent │ │ • Gradio UI │ │ • MCP Protocol │ │ • WhatsApp │ │ • CSV Export │ │ • REST API │ │ • 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 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 python main.py
Core Components
- 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:
alert_data = await generate_dynamic_alert("Patna", "Bihar")
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
Each district has specific crop preferences:
DISTRICT_CROPS = {
'patna': {
'primary': ['rice', 'wheat', 'potato'],
'secondary': ['mustard', 'gram'],
'specialty': ['sugarcane']
},
... 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 Creates concise SMS messages (160 characters max): def create_sms_message(alert_data): return f"BIHAR ALERT: {crop} in {location} - {weather_summary}" WhatsApp Agent Generates rich WhatsApp messages with emojis and formatting: def create_whatsapp_message(alert_data): return { "text": formatted_message, "buttons": action_buttons } USSD Agent Creates interactive USSD menu structures: def create_ussd_menu(alert_data): return { "menu": "CON Weather Alert...\n1. Details\n2. Actions" } IVR Agent Generates voice script for phone systems: def create_ivr_script(alert_data): return { "script": "Welcome to Bihar weather alert...", "menu_options": [...] } Telegram Agent Creates Telegram messages with inline keyboards: def create_telegram_message(alert_data): return { "text": message, "reply_markup": inline_keyboard }
API Reference Core Endpoints
- Workflow Execution POST /api/run-workflow Request Body: { "state": "bihar", "district": "patna" } Response: { "message": "workflow_results", "status": "success", "csv": "csv_data", "raw_data": { "alert_data": {...}, "agent_responses": {...} } }
- Health Check GET /api/health Response: { "status": "healthy", "openai_available": true, "timestamp": "2025-08-13T10:30:00" }
- MCP Tool Execution POST /mcp Request Body: { "tool": "get_current_weather", "parameters": { "latitude": 25.5941, "longitude": 85.1376 } }
- Geographic Data GET /api/districts/{state} GET /api/villages/{state}/{district}
- Weather Data 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 class AlertRequest(BaseModel): alert_json: dict WorkflowRequest class WorkflowRequest(BaseModel): state: str district: str MCPRequest class MCPRequest(BaseModel): tool: str parameters: dict Alert Data Structure { "alert_id": "BH_PAT_VIL_20250813_103000", "timestamp": "2025-08-13T10:30:00Z", "location": { "village": "Danapur", "district": "Patna", "state": "Bihar", "coordinates": [25.5941, 85.1376], "coordinates_source": "village_danapur" }, "crop": { "name": "rice", "stage": "Tillering", "season": "kharif", "planted_estimate": "2025-06-15" }, "alert": { "type": "heavy_rain_warning", "urgency": "high", "message": "Heavy rainfall expected...", "action_items": ["delay_fertilizer", "check_drainage"], "ai_generated": true }, "weather": { "temperature": "28.5°C", "expected_rainfall": "35.2mm", "wind_speed": "15.3 km/h", "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) CORS Configuration app.add_middleware( CORSMiddleware, allow_origins=["https://mcp-ui.vercel.app", ""], allow_credentials=True, allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"], allow_headers=[""] ) Bihar Districts Configuration The system supports 39 Bihar districts: Patna, Gaya, Bhagalpur, Muzaffarpur, Darbhanga Siwan, Begusarai, Katihar, Nalanda, Rohtas And 29 others...
Deployment Local Development python main.py FastAPI server: http://localhost:8000 Gradio interface: http://localhost:7860 Production Deployment Docker Deployment FROM python:3.9-slim
WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt
COPY . . EXPOSE 8000 7860
CMD ["python", "main.py"] HuggingFace Spaces The application automatically detects HuggingFace Spaces environment and configures accordingly: 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
- OpenAI API Key Missing Error: OpenAI API key not found - AI features will be limited Solution: Add OPENAI_API_KEY to .env file
- Weather API Failures Error: Failed to get weather data Solutions: Check internet connectivity Verify API keys in .env Check API quotas and limits
- 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"
- 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 export LOG_LEVEL=DEBUG python main.py Check Log Output logger.info(f"Selected village: {village}") logger.error(f"Weather API error: {error}") Performance Optimization
- API Response Caching Consider implementing Redis caching for weather data:
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 For production, consider using PostgreSQL/MongoDB:
Store alert history
await db.alerts.insert_one(alert_data)
Contributing Development Guidelines
- Code Style Follow PEP 8 Python style guide Use type hints for function parameters Add docstrings for all functions Maximum line length: 100 characters
- Testing import pytest
def test_crop_selection(): crop = select_regional_crop("patna", "bihar") assert crop in ["rice", "wheat", "potato"]
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 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
- New Weather Provider
tools/new_weather_api.py
async def get_current_weather(latitude, longitude, api_key): # Implementation return weather_data 2. New Communication Channel
a2a_agents/slack_agent.py
def create_slack_message(alert_data): return { "text": message, "attachments": [] } 3. New Crop Types CROP_CALENDAR["new_crop"] = { "season": "Rabi", "planting": "December", "harvesting": "May", "duration_days": 150, "stages": ["Sowing", "Growth", "Harvest"] }
Last Updated: August 13, 2025.