# Case Diary Timeline CLI for Kidnapping Investigations

## PURPOSE
A Click + Pandas command-line tool that ingests the officer's raw case-diary entries for a
kidnapping — the kind of night-by-night log kept in the Vinayaka Nagar (Vijayawada)
kidnap-and-rescue case — and turns them into a clean, sortable, filterable timeline. It
answers the questions investigators actually ask: what happened Sunday night, when did the
victim cross into Palnadu district, how many suspects were booked, and how many hours
elapsed between the report and the rescue?

## WHY THIS MATTERS
The transcript is essentially a timeline: reported Sunday night after a property dispute →
technical evidence developed → victim located in Palnadu district → rescued "without any
harm" on Monday → four suspects arrested and sent to remand. Structured timelines are how
prosecutors prove custody duration and property-dispute motive. This project teaches that
turning free-text diary notes into typed, time-ordered rows is the foundation of any
case-analytics pipeline.

## HOW TO BUILD
1. Define a Click group with commands `ingest`, `timeline`, `gaps`, `summary`.
2. Load diary rows (CSV) into a Pandas DataFrame; parse `occurred_at` with `pd.to_datetime`.
3. Normalise `event_type` into a controlled vocabulary and `district` into
   Vijayawada / Palnadu values seen in the transcript.
4. Compute elapsed hours between `reported` and `rescued`, and flag gaps > N hours.

```python
@cli.command()
@click.option("--case", "diary", type=click.Path(exists=True))
def timeline(diary: str):
    df = pd.read_csv(diary, parse_dates=["occurred_at"]).sort_values("occurred_at")
    click.echo(df[["occurred_at", "district", "event_type"]].to_string(index=False))
```

## WHEN TO USE IN PRODUCTION
Use it in cyber-cell case prep, RTI/prosecution handoffs, and as the ETL step before a
Case Management System. Do NOT use it for live tracking (it is batch, not real-time) and do
not let it hold unredacted victim identity in a shared repo.

## HOW IT HELPS STUDENTS
Practise CLI ergonomics (Click options/args), real Pandas date handling and group-by
aggregation, controlled vocabularies for messy field data, and reproducible reporting —
core data-engineering skills recruiters screen for.

## STARTER CODE
`starter/main.py` implements the Click group, a deterministic sample diary, timeline/gaps/
summary commands and a `# TODO` for a real CSV loader and CSV export.
