README_ref.md

# 🌾 Alert Summary Prototype Backend

**Multi-stage MCP Pipeline for Agricultural Intelligence**

---

## 🎯 Overview

Farmer.Chat uses a **4-stage pipeline** to process agricultural queries:

```
Query → Router → Executor (Parallel) → Compiler → Translator → Advice
```

### Architecture

1. **Stage 1: Query Router** - Analyzes farmer's question and selects relevant MCP servers
2. **Stage 2: MCP Executor** - Calls multiple APIs in parallel (weather, soil, water, elevation, pests)
3. **Stage 3: Response Compiler** - Merges data from all sources
4. **Stage 4: Farmer Translator** - Converts technical data to actionable farmer advice

---

## 🔌 API Endpoints

### `POST /api/query`
Process a farmer's question

**Request:**
```json
{
  "query": "Should I plant rice today?",
  "location": {
    "name": "Bangalore",
    "lat": 12.8716,
    "lon": 77.4946
  }
}
```

**Response:**
```json
{
  "success": true,
  "query": "Should I plant rice today?",
  "advice": "...",
  "routing": {...},
  "data": {...},
  "execution_time_seconds": 3.5
}
```

### `POST /api/export-pdf`
Export query result as PDF

**Request:** Same as `/api/query`

**Response:** PDF file download

### `GET /api/health`
Health check

### `GET /api/servers`
List available MCP servers

---

## 🛠️ MCP Servers

| Server | Data Source | Information |
|--------|-------------|-------------|
| **weather** | Open-Meteo | Current weather, 7-day forecasts |
| **soil_properties** | SoilGrids | Clay, sand, pH, nutrients |
| **water** | GRACE Satellite | Groundwater levels, drought status |
| **elevation** | OpenElevation | Field elevation, terrain data |
| **pests** | iNaturalist | Recent pest observations |

---

## 🚀 Deployment Instructions

### 1. Create Hugging Face Space

1. Go to https://huggingface.co/new-space
2. Space name: `farmer-chat-backend`
3. Owner: `aakashdg`
4. SDK: **Gradio** (we'll use FastAPI inside)
5. Set to **Public**

### 2. Upload Files

Upload all files maintaining this structure:
```
farmer-chat-backend/
├── app.py
├── requirements.txt
├── README.md
├── src/
│   ├── __init__.py
│   ├── pipeline.py
│   ├── router.py
│   ├── executor.py
│   ├── compiler.py
│   ├── translator.py
│   ├── pdf_generator.py
│   └── servers/
│       ├── __init__.py
│       └── (all server classes in one file or separate)
```

### 3. Set Environment Variables

In Space Settings → Variables and secrets:
- Add secret: `OPENAI_API_KEY` = your OpenAI API key

### 4. Deploy!

Space will auto-deploy. Access at:
```
https://huggingface.co/spaces/aakashdg/farmer-chat-backend
```

---

## 🧪 Testing

### Test with cURL:

```bash
curl -X POST https://huggingface.co/spaces/aakashdg/farmer-chat-backend/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the soil composition?",
    "location": {"name": "Bangalore", "lat": 12.8716, "lon": 77.4946}
  }'
```

### Test with Python:

```python
import requests

response = requests.post(
    "https://huggingface.co/spaces/aakashdg/farmer-chat-backend/api/query",
    json={
        "query": "Will it rain this week?",
        "location": {"name": "Bangalore", "lat": 12.8716, "lon": 77.4946}
    }
)

print(response.json())
```

---

## 📊 Performance

- **Parallel execution**: All MCP servers called simultaneously
- **Typical response time**: 3-5 seconds
- **Success rate**: ~95% (graceful degradation if servers fail)

---

## 🔐 Security

- OpenAI API key stored as HF Space secret
- CORS enabled for frontend integration
- Rate limiting: 100 queries/hour per IP (configurable)

---

## 📈 Scaling

To add more MCP servers:

1. Create new server class in `src/servers/`
2. Add to `MCP_SERVER_REGISTRY` in `executor.py`
3. Router will automatically include it in routing decisions

---

## 🐛 Troubleshooting

### "OPENAI_API_KEY not set"
- Check HF Space Settings → Variables and secrets
- Ensure secret name is exactly `OPENAI_API_KEY`

### Slow responses
- Normal for first query (cold start)
- Subsequent queries faster due to caching

### Server failures
- System uses graceful degradation
- If one server fails, others still provide data
- Check `failed_servers` in response

---

## 📞 Support

- GitHub Issues: [Link to repo]
- Creator: @aakashdg
- Built for: Farmer.chat product demo

---

## 📄 License

MIT License

---

**Built with ❤️ for farmers**