# Festival Crowd Advisory CLI Analyzer (Click + Pandas)

## PURPOSE
Warangal police issued a festival-season advisory naming Dasara and Diwali as the
highest-risk crowding periods in markets and malls. A district office that issues such
advisories still has to review reports from many zones after the fact. This command-line
tool ingests a CSV of zone footfall and incident reports, flags zones that breached safe
capacity, and prints a plain-language advisory summary an officer can paste into a notice.

## WHY THIS MATTERS
The transcript frames advisories as *pre-emptive*: warnings issued in advance to prevent
stampedes. Turning raw crowd reports into ranked, human-readable warnings is exactly the
"last mile" of that idea. You learn how tabular analysis becomes an actionable advisory —
group-by aggregation, thresholds, and formatting — with no heavyweight infrastructure.

## HOW TO BUILD
1. `pip install click pandas tabulate`.
2. Structure a CSV with columns: `zone,date,festival,footfall,capacity,incidents`.
3. Use `@click.group()` with subcommands `summarize`, `flag`, and `advisory`.
4. In `flag`, compute `occupancy = footfall / capacity` and select rows above a
   `--threshold` (default 0.9) — the same advance-warning threshold logic police use.
5. In `advisory`, render the flagged rows into a templated notice.

Key snippet:
```python
@cli.command()
@click.option("--csv", type=click.Path(exists=True))
@click.option("--threshold", default=0.9)
def flag(csv, threshold):
    df = pd.read_csv(csv)
    df["occupancy"] = df["footfall"] / df["capacity"].clip(lower=1)
    hot = df[df["occupancy"] > threshold].sort_values("occupancy", ascending=False)
    click.echo(tabulate(hot, headers="keys", tablefmt="github"))
```

## WHEN TO USE IN PRODUCTION
Great for daily or weekly batch review before issuing advisories, for post-festival audits,
and as a scheduled cron job writing advisory drafts to a file for human sign-off. Do **not**
use it for live crowd control — it reads static CSV, gives no real-time feed, and has no
alerting. Avoid it when a dashboard or streaming pipeline already covers the same data.

## HOW IT HELPS STUDENTS
You learn Click command design, idiomatic Pandas aggregation, safe division, and turning
analysis into an output a non-technical stakeholder can use. It is a compact portfolio
piece proving you can build a real ops tool, not just a notebook.

## STARTER CODE
See `starter/main.py` for the Click group, the Pandas pipeline, and `# TODO` markers for
CSV schema validation and templated advisory export.
