# Kakinada Road Hazard Ticket CLI

## PURPOSE
A Click + Pandas command-line tool that ingests a pothole complaint log for the
main road from Kumbhabhishekam Port in Kakinada towards the tidal area and turns it
into a triaged worklist. It filters by severity, groups tickets by road segment,
and exports a ranked repair priority table that a municipal engineering team could
action tomorrow morning.

## WHY THIS MATTERS
The transcript reports that large potholes on this route are a "major obstacle to
traffic" and that hundreds of two-wheeler workers commuting to nearby industries
are facing accidents. When complaints arrive as free text or CSV, they are useless
until aggregated. This project teaches data cleaning, severity triage and
prioritisation — the analytics backbone behind any civic response.

## HOW TO BUILD
Use Click for the command surface and Pandas for the transforms.
1. `pip install click pandas tabulate`
2. Define a fixed CSV schema: `ticket_id,segment,depth_cm,two_wheeler_pct,reports,date`.
3. Write a `score` function mapping measurable fields to a 1-5 severity band.
4. Add commands: `ingest`, `triage --min-severity`, `export --format csv|md`.
5. Keep the loader tolerant: coerce types, drop rows missing a segment name.

Core scoring and aggregation:

```python
def add_severity(df: pd.DataFrame) -> pd.DataFrame:
    df = df.copy()
    df["severity"] = (
        (df["depth_cm"] / 4.0) + (df["two_wheeler_pct"] / 25.0)
    ).round().clip(1, 5).astype(int)
    return df.sort_values(["severity", "reports"], ascending=False)
```

## WHEN TO USE IN PRODUCTION
Use it for periodic batch triage of exported complaint CSVs, for scheduled cron
jobs that email a daily priority list, or as the ETL step before a dashboard loads.
Do NOT use it for real-time intake or interactive map review — that is the job of
the API and dashboard projects. It assumes clean tabular input, not raw geotagged
photos.

## HOW IT HELPS STUDENTS
Students practise CLI UX design, dataframe transformation, defensive parsing and
report generation. They learn to express a public-interest problem as a
reproducible pipeline, which is the exact skill analytics roles demand.

## STARTER CODE
See `starter/main.py` — a Click group with `ingest` and `triage` commands, a
deterministic severity function, and `# TODO` markers for validation and export
formats.
