# Panchayat Layout Audit CLI

## PURPOSE
A command-line tool built with **Click + Pandas** that batch-audits a spreadsheet of plot
layouts against the mandatory 10% social-space rule from the West Godavari district report.
Given a CSV of layouts (`layout_id`, `panchayat`, `total_area_sqm`, `social_space_sqm`), it
computes each layout's reserved percentage, its shortfall, an estimated revenue loss, and a
pass/fail compliance flag — then prints a ranked summary so an officer can see the worst
offenders first. A second command exports a clean non-compliance report for filing.

## WHY THIS MATTERS
The news item says officials "identified that numerous illegal layouts are emerging" across
major panchayats. In practice that discovery work starts with a register — a list of parcels
— and the job is to flag which rows break the rule. This project teaches **data-frame
thinking for regulation**: vectorised arithmetic over a table instead of a loop, and an
auditor-friendly output that names the losing panchayats and the money at stake.

## HOW TO BUILD
1. Create a Click group `cli` with two commands: `audit` and `export`.
2. In `audit`, read the CSV with `pandas.read_csv` and validate the required columns.
3. Vectorise the rule:
   `pct = social_space_sqm / total_area_sqm * 100`,
   `shortfall = (total_area_sqm * 0.10 - social_space_sqm).clip(lower=0)`,
   `loss = shortfall * rate`.
4. Print totals (rows, compliant, non-compliant, total loss) and the sorted table.
5. `export` writes the enriched frame to a new CSV.

Key snippet:

```python
df["social_space_pct"] = (df["social_space_sqm"] / df["total_area_sqm"] * 100).round(2)
df["shortfall_sqm"] = (df["total_area_sqm"] * (min_pct / 100)
                       - df["social_space_sqm"]).clip(lower=0).round(2)
df["est_revenue_loss_inr"] = (df["shortfall_sqm"] * rate).round(2)
df["compliant"] = df["shortfall_sqm"] == 0
```

## WHEN TO USE IN PRODUCTION
Ideal for scheduled audits of a panchayat register export, for data-cleaning pipelines that
tag violations before they reach a dashboard, or for one-off RTI-style analyses. Prefer it
over an API when the source is a file and the output is a report. Do **not** use it for
transactional approval workflows or where row counts are small enough for a human to eyeball;
and never treat the estimated loss as an official figure until the per-panchayat rate is
wired in.

## HOW IT HELPS STUDENTS
Students gain practical Pandas vectorisation, defensive input validation, and Click command
design — the exact skills that turn a messy government spreadsheet into a decision. They also
learn to fail loudly with clear error messages, which matters far more than clever code.

## STARTER CODE
`starter/main.py` contains the `cli` group, working `audit` and `export` commands, column
validation, and vectorised compliance maths. Replace the flat rate and add Excel/PDF export
at the marked `# TODO` points.
