# Vijayawada–Palnadu Kidnap-Response Analytics Dashboard

## PURPOSE
A Streamlit + Plotly dashboard that visualises how a kidnapping case unfolded across two
jurisdictions, using the Vijayawada case as the worked example: reported Sunday night after
a property dispute in Vinayaka Nagar, victim traced to Palnadu district, rescued unharmed
on Monday, four suspects arrested and remanded. It puts time-to-rescue, district split,
motive mix and custody status on one screen for a station officer or a district review
meeting.

## WHY THIS MATTERS
The transcript ends on an outcome that is quietly a metric: "saved him on Monday without any
harm." Rescue latency and remand compliance are the two numbers that determine whether a
case holds up. Turning a raw event log into a district-comparison chart is how police
leadership spots which stations resolve fast and which remand paperwork slips — a
translation of narrative facts into decision-ready visuals.

## HOW TO BUILD
1. Build a tidy events table (timestamp, district, event_type, motive, suspects).
2. Use `st.sidebar` filters for district, motive and date window.
3. Plot with `plotly.express`: a horizontal bar of hours-to-rescue per district, a timeline
   `scatter` with markers per event, and a pie of dispute motive.
4. Add `st.metric` cards for elapsed hours, suspects remanded and % remanded on time.

```python
hour_metric = st.metric("Report → rescue", f"{elapsed_h:.1f} h")
fig = px.bar(df.groupby("district")["hours"].sum().reset_index(),
             x="district", y="hours", title="Handling time by district")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use it for weekly district crime reviews, sharing a de-identified case story with training
academies, and monitoring remand compliance trends. Do NOT use it to publish live victim
identity, and do not treat stub demo rows as real statistics — connect it to the actual
case-management database before any operational use.

## HOW IT HELPS STUDENTS
Students learn the modern analyst loop: tidy data → interactive filters → earned insight,
plus Streamlit layout, Plotly chart selection and the discipline of de-identifying
sensitive fields before plotting.

## STARTER CODE
`starter/main.py` is a functional Streamlit app with a deterministic in-app event dataset,
sidebar filters, three Plotly figures and metric cards, with `# TODO` markers for DB wiring.
