# P2 — Polling Station Facility Audit CLI (Click + Pandas)

## PURPOSE
A command-line tool for auditors who must quickly summarise polling-station readiness
from a spreadsheet. In the video the Additional Commissioner inspected the 18 polling
stations at Chandrampalem High School in the Madhurawada zone, checking drinking water,
continuous power, and ramps for the elderly and disabled. This CLI ingests an inspection
CSV, reports the zone readiness score, and lists every station that fails a mandatory
facility so officials can be told — as the transcript puts it — to have things
"perfectly prepared."

## WHY THIS MATTERS
Officials rarely get data through a nice API; they get a CSV from a field team. The hard
part is turning messy rows into a trustworthy answer fast. This project teaches the
tabular-audit pattern: load, validate, filter, and summarise — the same loop behind every
compliance report.

## HOW TO BUILD
1. Install deps from `requirements.txt` in a virtualenv.
2. Use Click to define a `click.Group` with commands: `summary`, `gaps`, `by-facility`.
3. Load the CSV with `pandas.read_csv`, coerced booleans for the three facility columns.
4. Compute readiness = all mandatory facilities true; exit code 1 if any gaps remain.
5. Run `python starter/main.py summary --csv inspections.csv`.

Key snippet:
```python
@click.command()
@click.option("--csv", "csv_path", required=True, type=click.Path(exists=True))
def gaps(csv_path):
    df = pd.read_csv(csv_path)
    bad = df[~df[REQUIRED].all(axis=1)]
    click.echo(bad[["station_id", "missing_facility"]].to_string(index=False))
```

## WHEN TO USE IN PRODUCTION
Great for pre-election readiness sweeps, recurring facility audits, and any "diff the
spreadsheet" job in a CI pipeline or cron. Do NOT use it for real-time monitoring — a CLI
runs on demand, not continuously. Do NOT let it write back into the source CSV; emit a
separate gaps report so the original field data stays intact for audit.

## HOW IT HELPS STUDENTS
Students practise Click command design, Pandas filtering, sensible exit codes, and
building a tool an ops team would actually run every morning.

## STARTER CODE
`starter/main.py` contains the Click group, Pandas loaders, and a deterministic sample
DataFrame fallback so it runs without a CSV, with `# TODO` markers for real I/O.
