# Indiramma Beneficiary List Audit CLI (Click + Pandas)

## PURPOSE
A command-line tool that loads raw Indiramma housing beneficiary lists (CSV/Excel dumps
from district offices), de-duplicates applicants, validates them against scheme rules, and
emits a clean sanctioned list plus a rejection report. The transcript says the administration
"has taken steps to select beneficiaries in a transparent manner" — this CLI is the audit
layer that proves it, turning messy field data into a defensible, publishable list.

## WHY THIS MATTERS
Transparency is a data-quality problem before it is a communication problem. Field lists
arrive with duplicate Aadhaar rows, spelling variants of the same village, income values
in inconsistent units, and applicants who already own a house. The video insists there is
"no question of taking a step back" on welfare delivery even amid financial difficulties —
which means the eligible pool must be correct, because a corrupt pool wastes a scarce
housing budget. Rule-as-code keeps the decision reproducible.

## HOW TO BUILD
1. `pip install click pandas openpyxl`.
2. Group commands under a `@click.group()` root so `validate`, `dedupe`, `report` compose.
3. Load with `pd.read_csv`, coerce income with `pd.to_numeric(errors="coerce")`.
4. Flag duplicates on a hashed Aadhaar key with `df.duplicated(subset=[...], keep="first")`.
5. Apply rule filters, write `sanctioned.csv` and `rejected.csv` with reasons.

Key snippet:

```python
@cli.command()
@click.argument("csv_path", type=click.Path(exists=True))
@click.option("--income-ceiling", default=200000, type=int)
@click.option("--out", default="reports")
def validate(csv_path, income_ceiling, out):
    df = load_applicants(csv_path)
    key = df["aadhaar"].astype(str).apply(lambda a: hashlib.sha256(a.encode()).hexdigest())
    df = df.assign(aadhaar_hash=key)
    df["reason"] = df.apply(lambda r: flag_reasons(r, income_ceiling), axis=1)
    ok = df[df["reason"] == ""]
    ok.to_csv(f"{out}/sanctioned.csv", index=False)
    df[df["reason"] != ""].to_csv(f"{out}/rejected.csv", index=False)
```

## WHEN TO USE IN PRODUCTION
Use it at district data-prep time, in a nightly cron that re-validates the master list, or
inside a CI check that fails the build if duplicate Aadhaar counts spike. Do NOT use a
batch CLI for real-time citizen status queries — that needs an API. Do NOT use it as the
system of record; it is a transform-and-report tool.

## HOW IT HELPS STUDENTS
Students practise real Pandas wrangling, Click command design, deterministic rule functions,
privacy-preserving hashing, and reproducible audit outputs — the exact skills data teams
apply to government and NGO datasets.

## STARTER CODE
See `starter/main.py` — a Click group with `validate`, `dedupe` and `report` commands,
deterministic stubs, and `# TODO` markers.
