Hugging Face's logo

Spaces:
elanuk
/
mcp-hf
Running

App Files Community
mcp-hf / README.md
elanuk's picture
elanuk
Update README.md
993588c verified
preview code
|
raw
history blame contribute delete
15.2 kB

Bihar AgMCP - Agricultural Weather Alert System

Table of Contents

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

  1. Clone the repository

    git clone <repository-url>
cd bihar-agmcp

  2. Install dependencies

    pip install fastapi uvicorn gradio pandas python-dotenv pydantic

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

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

1. Server-side

a. Alert Generation Engine

  • Primary Function: generate_dynamic_alert(district, state)
  • Purpose: Generates comprehensive weather alerts for specific districts.

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:

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

1. 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": {...}
    }
}

2. Health Check 

GET /api/health

Response:

{
    "status": "healthy",
    "openai_available": true,
    "timestamp": "2025-08-13T10:30:00"
}

3. MCP Tool Execution 

POST /mcp

Request Body:

{
    "tool": "get_current_weather",
    "parameters": {
        "latitude": 25.5941,
        "longitude": 85.1376
    }
}

4. Geographic Data 

GET /api/districts/{state}
GET /api/villages/{state}/{district}

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

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

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 

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

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

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 

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

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