# Mandal Rainfall Bulletin Analyzer CLI

## PURPOSE
A Click + Pandas command-line tool that parses daily rainfall bulletins for a
district like West Godavari and answers the questions a newsroom or agriculture
officer actually asks: which mandal had the most rain today, how many mandals crossed
a threshold, and how does a mandal compare to the district average. The video's
example — 24 mm in Koyyalagudem, other areas up to nearly 10 mm — is the canonical
input row set the tool is designed around.

## WHY THIS MATTERS
Raw weather bulletins arrive as prose or messy CSVs. Before any dashboard or alert,
someone must turn "moderate rainfall recorded in several mandals" into a clean table
of mandal → millimeters and a sorted ranking. This project teaches that translation
using the two libraries every data engineer reaches for first.

## HOW TO BUILD
Create a Click group with subcommands `summary`, `top`, and `threshold`. Load the
bulletin CSV with `pandas.read_csv`, coerce the `millimeters` column to numeric with
`errors="coerce"`, and drop rows you cannot trust. Use `groupby("mandal")`
aggregation for the summary and `nlargest` for the ranking.

Key snippet:

```python
import click
import pandas as pd

@click.group()
def cli():
    """Analyze mandal rainfall bulletins."""

@cli.command()
@click.argument("csv_path", type=click.Path(exists=True))
def top(csv_path):
    df = pd.read_csv(csv_path)
    df["millimeters"] = pd.to_numeric(df["millimeters"], errors="coerce")
    ranked = df.dropna().nlargest(5, "millimeters")
    click.echo(ranked.to_string(index=False))
```

## WHEN TO USE IN PRODUCTION
Use it in a cron job that fetches the daily bulletin and writes a ranked digest to
Slack or email; use it in a data-cleaning step before loading a warehouse. Do NOT
use a CLI for interactive exploration with non-technical users — give them the
dashboard instead. Do NOT use Pandas on multi-gigabyte archives; push down to SQL.

## HOW IT HELPS STUDENTS
Students learn sane CLI ergonomics (arguments vs options, exit codes), defensive
Pandas (dtype coercion, NaN handling), and how to make a script reproducible and
composable in shell pipelines.

## STARTER CODE
See `starter/main.py` for the Click group, three subcommands, an in-memory sample
bulletin drawn from the transcript, and `# TODO` markers for real file parsing and output formats.
