# VayuChat MCP

Natural language data analysis for air quality data using MCP (Model Context Protocol).

## Features

### Pre-loaded Datasets
- **air_quality**: Hourly PM2.5, PM10, NO2, SO2, CO, O3 readings for Delhi & Bangalore
- **funding**: Government air quality funding by city/year (2020-2024)
- **city_info**: City metadata - population, vehicles, industries, green cover

### Analysis Tools (No Code Required!)
| Function | Description |
|----------|-------------|
| `list_tables` | Show available tables |
| `show_table` | Display table data |
| `describe_table` | Detailed statistics |
| `query_table` | Filter with pandas query |
| `compare_weekday_weekend` | Weekday vs weekend analysis |
| `compare_cities` | Compare metrics across cities |
| `analyze_correlation` | Correlation analysis |
| `analyze_funding` | Funding breakdown |
| `get_city_profile` | Comprehensive city profile |

### Visualization Tools
| Function | Description |
|----------|-------------|
| `plot_comparison` | Bar/box charts |
| `plot_time_series` | Time series charts |
| `plot_weekday_weekend` | Weekday vs weekend bars |
| `plot_funding_trend` | Funding over years |
| `plot_hourly_pattern` | Hourly patterns |

## Installation

```bash
# Using uv
uv pip install -e .

# Or with pip
pip install -e .
```

## Usage

### As MCP Server (with Claude Code)

Add to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "vayuchat": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vayuchat-mcp", "vayuchat-mcp"]
    }
  }
}
```

### As Gradio App (HF Spaces)

```bash
# Run locally
python app.py

# Or with gradio
gradio app.py
```

Then open http://localhost:7860

### Deploy to Hugging Face Spaces

1. Create a new Space on HF (Gradio SDK)
2. Upload these files:
   - `app.py`
   - `requirements.txt`
   - `src/` folder
   - `data/` folder

Or connect your GitHub repo directly to HF Spaces.

## Example Queries

```
# Data exploration
"What tables are available?"
"Show me the funding table"
"Describe the air quality data"

# Analysis
"Compare weekday vs weekend PM2.5"
"Compare cities by PM10 levels"
"Get Delhi city profile"
"Show correlation with PM2.5"

# Funding
"Show funding for Delhi"
"What's the funding trend?"

# Visualizations
"Plot weekday vs weekend PM2.5"
"Show hourly pattern for NO2"
"Plot funding trend chart"
```

## Architecture

```
NLQ (User Question)
       ↓
  Gradio Chat UI
       ↓
  Query Router (keyword-based / LLM)
       ↓
  MCP Tool Call
       ↓
  Response (Markdown + Base64 Plot)
       ↓
  Rendered in UI
```

## Why Predefined Functions vs LLM-Generated Code?

This project uses **predefined MCP functions** instead of letting the LLM generate arbitrary pandas/matplotlib code. Here's why:

### Comparison Table

| Aspect | Predefined Functions (This Approach) | LLM-Generated Code | Function-Calling LLM |
|--------|-------------------------------------|-------------------|---------------------|
| **Reliability** | ✅ Deterministic, always works | ❌ May hallucinate syntax | ⚠️ Better but can miss params |
| **Speed** | ✅ Instant (no code generation) | ❌ Slow (generate → parse → execute) | ⚠️ Moderate |
| **Cost** | ✅ Minimal tokens | ❌ Long prompts with schema | ⚠️ Moderate |
| **Security** | ✅ No arbitrary code execution | ❌ Code injection risk | ✅ Safe |
| **Consistency** | ✅ Same visualization style | ❌ Random styling each time | ✅ Consistent |
| **Model Size** | ✅ Works with small/cheap models | ❌ Needs capable coder model | ⚠️ Needs fine-tuned model |
| **Flexibility** | ❌ Limited to predefined queries | ✅ Infinite flexibility | ⚠️ Limited to defined functions |
| **Error Handling** | ✅ Graceful, predictable | ❌ May crash, retry loops | ✅ Structured errors |

### When to Use Each Approach

**Use Predefined Functions (this approach) when:**
- You have a known, bounded set of analysis patterns
- Users are non-technical (need consistent UX)
- Cost/latency matters (production deployment)
- You want guaranteed correct outputs
- Using smaller/cheaper models (Haiku, GPT-3.5)

**Use LLM-Generated Code when:**
- Exploratory data analysis with unknown patterns
- Power users who can debug code
- One-off analyses
- Prototype/research phase

**Use Function-Calling LLM when:**
- You have predefined functions BUT need better intent parsing
- Using OpenAI/Claude with native function calling
- Queries are ambiguous and need sophisticated NLU

### The Hybrid Approach (Best of Both)

```
User Query
     ↓
┌─────────────────────────────────────┐
│  LLM with Function Calling          │  ← Parses intent, extracts params
│  (Claude, GPT-4, etc.)              │
└─────────────────────────────────────┘
     ↓
┌─────────────────────────────────────┐
│  MCP Predefined Functions           │  ← Executes reliably
│  (compare_cities, plot_trend, etc.) │
└─────────────────────────────────────┘
     ↓
  Structured Response + Plot
```

This gives you:
- **LLM's NLU capabilities** for parsing complex queries
- **Predefined functions' reliability** for execution
- **No code hallucination** risk
- **Consistent outputs** every time

### Example: Same Query, Different Approaches

**Query:** "Compare PM2.5 on weekdays vs weekends for Delhi and Bangalore"

**LLM-Generated Code (risky):**
```python
# LLM might generate:
df['is_weekend'] = df['day'].isin(['Sat', 'Sun'])  # Wrong column name!
df.groupby(['city', 'is_weekend'])['pm25'].mean()  # Wrong column name!
# ... errors, retries, inconsistent output
```

**Predefined Function (reliable):**
```python
# MCP calls:
compare_weekday_weekend(value_column="PM2.5", group_by="city")
# Always works, consistent format, proper column names
```

### Cost Comparison (Approximate)

| Approach | Tokens per Query | Cost (GPT-4) | Latency |
|----------|------------------|--------------|---------|
| Predefined + Keyword Router | ~100 | $0.001 | <100ms |
| Predefined + LLM Router | ~500 | $0.005 | ~500ms |
| LLM-Generated Code | ~2000+ | $0.02+ | 2-5s |

For 1000 queries/day:
- Predefined: ~$1-5/day
- LLM Code Gen: ~$20+/day

## Data Sources

- Air quality data: Simulated based on real patterns from Indian cities
- Funding data: Mock data representing typical government allocations
- City info: Approximate real statistics

## License

MIT