# District Rain Advisory API

## PURPOSE
A FastAPI service that turns an India Meteorological Department (IMD) style two-day rain forecast into a farmer-facing advisory for Bhadradri Kothagudem district. The transcript reports sudden cool weather, thunder and lightning, "light rains may occur in several places in the district", and officials telling farmers to be very alert, especially to protect crops at the harvesting stage. This API encodes that exact workflow: ingest a forecast, decide an alert level, and return plain-language guidance a farmer or extension officer can act on.

## WHY THIS MATTERS
It teaches how to convert a raw weather bulletin into a deterministic decision rule. The video's core message is a warning: rain during harvest damages ripened crop. Modelling that as a service (forecast in, advisory out) is the foundation of any real early-warning system, and it shows students how policy/news content becomes machine-usable logic.

## HOW TO BUILD
1. Create a `forecast` schema with `district`, `rain_mm_next_2_days`, `thunder`, and `crops_at_harvest_stage`.
2. Write a pure `decide_advisory()` function that maps the forecast to `NORMAL`, `WATCH`, or `ALERT` using simple thresholds — deterministic, no LLM needed.
3. Expose `POST /advisory` and `GET /health` with FastAPI; return the level plus the reason.

```python
from fastapi import FastAPI
from pydantic import BaseModel

class Forecast(BaseModel):
    district: str
    rain_mm_next_2_days: float
    thunder: bool
    crops_at_harvest_stage: list[str] = []

def decide_advisory(f: Forecast) -> str:
    if f.rain_mm_next_2_days >= 5 and f.crops_at_harvest_stage:
        return "ALERT"
    if f.rain_mm_next_2_days > 0 or f.thunder:
        return "WATCH"
    return "NORMAL"
```

## WHEN TO USE IN PRODUCTION
Use it when a district agriculture office or cooperative wants to broadcast a single canonical advisory from a forecast feed, or when an app backend needs a stable `level` field. Do NOT use it for real-time nowcasting, for sub-hour severe-storm warnings, or where IMD's official bulletin wording is legally binding — always mirror, never replace, the official advisory.

## HOW IT HELPS STUDENTS
Learners practise request/response modelling, Pydantic validation, pure decision functions that are unit-testable, and clear API contracts. They leave understanding how a news bulletin becomes a production service endpoint, and how to keep business rules separate from transport code.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with a deterministic advisory stub and `# TODO` markers for wiring a real IMD feed.
