# Yadadri Borewell Audit CLI — Groundwater & 44-Village Supply Tracker

## PURPOSE
A command-line tool that ingests a CSV roster of the crisis villages in Yadadri district and
the 50 private borewells the Rural Water Supply Department rented, then reports which
villages are under-served. Field staff export a spreadsheet; this CLI turns it into per-village
coverage numbers, allocation gaps, and a ranked priority list — without any web server.

## WHY THIS MATTERS
The video reports two hard numbers: 44 villages in crisis and 50 rented private borewells.
That is roughly one borewell per village, but real demand is never that tidy — a village with
900 households and one low-yield borewell is far worse off than a 120-household hamlet. The
CLI makes the imbalance visible so engineers like Karunakaran can reallocate instead of
assuming the count is fair. It teaches data-driven triage from a real scarcity scenario.

## HOW TO BUILD
1. `pip install click pandas`
2. Model the input as two CSV files: `villages.csv` (name, households, borewells_assigned,
   litres_today) and `borewells.csv` (id, village, yield_lph, rented, owner).
3. Use Click command groups: `audit summary`, `audit gaps`, `audit rank`.
4. Compute LPCD with Pandas groupby and flag anything under the 40 LPCD threshold.

```python
merged = villages.merge(borewells.groupby("village").size().rename("live_borewells"),
                        on="name", how="left").fillna({"live_borewells": 0})
merged["lpcd"] = merged["litres_today"] / merged["households"].clip(lower=1)
gaps = merged[merged["lpcd"] < 40].sort_values("lpcd")
```

## WHEN TO USE IN PRODUCTION
Ideal for a district engineer running ad-hoc audits on downloaded spreadsheets, cron jobs
that email a daily gap report, or ETL in a low-bandwidth office. Do NOT use it as the live
system of record — it reads files; pair it with the registry service when writes matter.

## HOW IT HELPS STUDENTS
Students learn Click command structuring, Pandas merges and groupby, threshold flagging,
and CLI UX (exit codes, `--format json`). It is the classic "make operations legible" skill.

## STARTER CODE
See `starter/main.py` — a working Click CLI skeleton with `summary`, `gaps`, and `rank`
commands and TODO markers for JSON output and borewell yield weighting.
