DRISHTI deploy

.gitattributes

@@ -0,0 +1 @@
+*.parquet filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,13 @@
+# raw data is 110MB — never commit it; the app only needs data/processed/*
+data/raw/
+
+__pycache__/
+*.pyc
+.ipynb_checkpoints/
+.venv/
+venv/
+.DS_Store
+.streamlit/secrets.toml
+
+# never commit real credentials
+auth_config.yaml

.streamlit/config.toml

@@ -0,0 +1,31 @@
+# Define BOTH a light and dark purple theme natively. Streamlit themes every
+# widget (including tables) consistently, and the user switches via ⋮ → Settings.
+[theme]
+base = "dark"
+primaryColor = "#8B5CF6"
+font = "sans serif"
+
+[theme.dark]
+backgroundColor = "#150C2E"
+secondaryBackgroundColor = "#1E1640"
+textColor = "#F4F1FF"
+
+[theme.dark.sidebar]
+backgroundColor = "#190F33"
+secondaryBackgroundColor = "#241748"
+
+[theme.light]
+backgroundColor = "#F7F4FF"
+secondaryBackgroundColor = "#FFFFFF"
+textColor = "#1E1338"
+
+[theme.light.sidebar]
+backgroundColor = "#EFEAFB"
+secondaryBackgroundColor = "#FFFFFF"
+
+[server]
+headless = true
+enableXsrfProtection = true
+# --- optional: enable HTTPS locally (see notes). Uncomment after creating certs ---
+# sslCertFile = "cert.pem"
+# sslKeyFile = "key.pem"

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+# LightGBM needs the OpenMP runtime (libgomp1); the slim image doesn't ship it.
+RUN apt-get update && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# install Python deps first (better layer caching)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# copy the app (data/raw and auth_config.yaml are gitignored, so never shipped)
+COPY . .
+
+# Hugging Face Spaces runs containers as a non-root user (UID 1000)
+RUN useradd -m -u 1000 user && chown -R user:user /app
+USER user
+
+EXPOSE 8501
+
+CMD ["streamlit", "run", "app.py", \
+     "--server.port=8501", "--server.address=0.0.0.0", "--server.headless=true"]

README.md

@@ -0,0 +1,161 @@
+---
+title: ParkSight
+emoji: 🅿️
+colorFrom: purple
+colorTo: indigo
+sdk: docker
+app_port: 8501
+pinned: false
+short_description: Parking-induced congestion intelligence for Bengaluru
+---
+
+# ParkSight — Parking-Induced Congestion Intelligence (Bengaluru)
+
+AI-driven parking-violation intelligence that **detects illegal-parking
+hotspots and quantifies their impact on traffic flow**, then **forecasts where
+hotspots will flare up next** — turning reactive, patrol-based enforcement into
+data-driven, targeted deployment.
+
+Built for *Flipkart Gridlock Hackathon 2.0 — Theme 1*.
+
+- **Detect** chronic hotspots over a city-wide H3 hex grid.
+- **Quantify** flow impact with a transparent **Congestion Impact Index (CII)**.
+- **Forecast** next-day intensity per zone with LightGBM.
+- **Act** — a ranked, downloadable enforcement-priority list + interactive map.
+
+> Results on the provided data: **298,445** parking violations → **2,534**
+> impact zones; forecast MAE **0.71**, ~**34% better** than a same-weekday
+> baseline.
+
+---
+
+## Architecture in one line
+The heavy offline pipeline (`src/`) crunches the 110 MB CSV and writes a few
+small artifacts (`data/processed/*`). The Streamlit app (`app.py`) reads only
+those, so it loads in seconds and runs inside free-tier memory.
+
+```
+parking-impact/
+├── app.py                  # Streamlit dashboard (serving layer)
+├── requirements.txt
+├── .streamlit/config.toml  # dark theme
+├── data/
+│   ├── raw/violations.csv  # the provided CSV (gitignored)
+│   └── processed/          # hotspots.parquet · forecast.parquet · meta.json
+├── src/                    # offline pipeline
+│   ├── config.py           # ALL tunable knobs (weights, H3 res, lags ...)
+│   ├── data_prep.py        # load · parse · tz-fix · filter to parking
+│   ├── features.py         # H3 indexing
+│   ├── hotspots.py         # per-cell stats
+│   ├── impact_index.py     # the CII
+│   ├── model.py            # LightGBM next-day forecast
+│   └── build_artifacts.py  # runs the whole pipeline
+├── models/lgbm_intensity.txt
+└── docs/methodology.md     # CII rationale (cite this in the deck)
+```
+
+---
+
+## Step-by-step: run it locally
+
+**1. Python 3.10–3.12 and a virtual env**
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+```
+
+**2. Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+**3. Put the dataset in place**
+Copy the provided CSV to `data/raw/violations.csv`.
+
+**4. Build the artifacts (offline, run once)**
+```bash
+python -m src.build_artifacts
+```
+This writes `data/processed/hotspots.parquet`, `forecast.parquet`, `meta.json`
+and `models/lgbm_intensity.txt`. Takes ~1–2 minutes.
+
+**5. Launch the dashboard**
+```bash
+streamlit run app.py
+```
+Opens at `http://localhost:8501`.
+
+---
+
+## Deploy to a public URL (free)
+
+The repo is deploy-ready for **either** platform. Commit the small
+`data/processed/*` artifacts (they're tiny); the raw CSV stays gitignored.
+
+### Option A — Hugging Face Spaces (recommended, 16 GB free RAM)
+1. Create a Space → SDK = **Streamlit**.
+2. Push this repo to the Space (entry file must be `app.py` at root — it is).
+3. Commit `data/processed/*` so the app has data. Done — you get a public URL.
+
+### Option B — Streamlit Community Cloud (simplest)
+1. Push to GitHub (public).
+2. share.streamlit.io → New app → pick the repo, main file `app.py`.
+3. Set a custom subdomain. Every `git push` auto-redeploys.
+
+---
+
+## Tuning (for your 2 optimization days)
+Everything is in `src/config.py`:
+- `PARKING_SEVERITY` — re-weight violation types.
+- `CII_WEIGHTS`, `CII_JUNCTION_ALPHA` — re-balance the index.
+- `H3_RES` — 8 (coarser) ↔ 10 (finer) zones.
+- `LAGS`, `ROLL_WINDOWS`, `MIN_CELL_VIOLATIONS`, `VALID_DAYS` — the model.
+Re-run `python -m src.build_artifacts` after any change.
+
+---
+
+## Multi-language, theme, history & login
+
+**Languages (English / ಕನ್ನಡ / हिन्दी)** — sidebar selector translates the UI and
+powers **voice + text search in Kannada and Hindi**. Native-script place names
+are resolved to the data's English localities via transliteration + fuzzy match
+(e.g. ಶಿವಾಜಿನಗರ → Shivaji Nagar). Voice input uses the matching locale
+(`kn-IN` / `hi-IN`). *Spoken read-back* uses the selected locale but depends on
+the OS/browser having that voice installed — it may fall back to English; demo
+in Chrome.
+
+**Theme** — Streamlit already ships a reliable light/dark toggle in
+⋮ → Settings → Theme. The sidebar toggle additionally flips the map basemap
+(reliable) and nudges the chrome via CSS (partial — native per-user runtime
+theming isn't supported yet, so the Settings menu is the robust path).
+
+**Session history** — the sidebar logs your searches this session (downloadable,
+clearable). Cross-session, per-user history needs the login add-on **plus** a
+database — free-tier disks are wiped on restart, so a server-side history file
+will not survive. For real persistence, write to a free Postgres (Neon/Supabase)
+via `st.secrets`.
+
+**Login add-on (optional, off by default)** — `src/auth.py` +
+`auth_config.yaml` give bcrypt-hashed, role-based login (admin / officer) via
+`streamlit-authenticator`. Enable by adding to the top of `app.py`:
+```python
+from src.auth import require_login
+name, username, roles = require_login()
+```
+Run `python hash.py` to hash passwords and replace the plain-text values in
+`auth_config.yaml` (which is gitignored — never commit real credentials). The
+login `login()` signature varies by library version, so pin it and test locally.
+
+
+| Form field | What to submit |
+|---|---|
+| Title | ParkSight — Parking-Induced Congestion Intelligence |
+| Description | Problem, CII method, forecast, impact (see deck) |
+| Theme | Poor Visibility on Parking-Induced Congestion |
+| Snapshots | Screenshots of the map / priorities / forecast tabs |
+| Video URL | 3-min screen-recorded demo (Loom / unlisted YouTube) |
+| Presentation | Your pitch deck (PDF) |
+| Demo Link | The public Spaces / Streamlit URL |
+| Repository URL | Your GitHub repo |
+| Source Code | A zip of this repo |
+| Instructions to Run | The "run it locally" section above |

app.py

@@ -0,0 +1,745 @@
+"""ParkSight — Parking-Induced Congestion Intelligence for Bengaluru.
+
+Serving layer: reads only the small precomputed artifacts in data/processed/.
+Run locally:   streamlit run app.py
+"""
+import io
+import re
+import json
+import hashlib
+from datetime import datetime
+from pathlib import Path
+
+import pandas as pd
+import pydeck as pdk
+import plotly.graph_objects as go
+import streamlit as st
+import streamlit.components.v1 as components
+
+try:
+    from streamlit_option_menu import option_menu
+    HAS_MENU = True
+except Exception:
+    HAS_MENU = False
+try:
+    from streamlit_mic_recorder import speech_to_text
+    HAS_MIC = True
+except Exception:
+    HAS_MIC = False
+try:
+    from streamlit_autorefresh import st_autorefresh
+    HAS_AUTOREFRESH = True
+except Exception:
+    HAS_AUTOREFRESH = False
+
+from src.i18n import LANGS, SPEECH_LANG, t, build_area_vocab, resolve_area
+
+ROOT = Path(__file__).resolve().parent
+PROC = ROOT / "data" / "processed"
+VIOLET = "#8B5CF6"
+GOLD = "#D4AF37"
+DONUT_COLORS = ["#8B5CF6", "#22D3EE", "#EC4899", "#6366F1", "#0EA5E9",
+                "#F472B6", "#A855F7", "#34D399", "#FB7185", "#818CF8"]
+
+# ---- demo-grade login (self-contained, no fragile dependency) ----
+# NOTE: demonstration auth — credentials are shown on the login screen so judges
+# can always get in. Production would use a real identity provider. To DISABLE
+# the login entirely, comment out the `require_login()` call below.
+_USERS = {"admin": "Traffic Admin (BTP)", "officer": "Patrol Officer"}
+_PW = {"admin": hashlib.sha256(b"admin123").hexdigest(),
+       "officer": hashlib.sha256(b"officer123").hexdigest()}
+
+
+def require_login():
+    if st.session_state.get("authed"):
+        return
+    # keep the session logged in across theme-switch page reloads (demo only)
+    if st.query_params.get("auth") == "1":
+        st.session_state.authed = True
+        st.session_state.user = "Traffic Admin (BTP)"
+        return
+    st.markdown(
+        "<div style='background:linear-gradient(135deg,#7C3AED,#EC4899);"
+        "border-radius:18px;padding:26px 30px;color:#fff;margin-bottom:20px;'>"
+        "<div style='font-size:2rem;font-weight:800;'>दृष्टि — DRISHTI</div>"
+        "<div style='opacity:0.92;margin-top:4px;'>Digital Real-time Intelligence for "
+        "Smart Hotspot &amp; Traffic Insights · हर सड़क पर नज़र, हर सफ़र आसान</div></div>",
+        unsafe_allow_html=True)
+    st.subheader("🔐 Secure sign-in")
+    with st.form("login_form"):
+        u = st.text_input("Username")
+        p = st.text_input("Password", type="password")
+        ok = st.form_submit_button("Sign in")
+    if ok:
+        if u in _PW and _PW[u] == hashlib.sha256(p.encode()).hexdigest():
+            st.session_state.authed = True
+            st.session_state.user = _USERS[u]
+            st.query_params["auth"] = "1"
+            st.rerun()
+        st.error("Invalid username or password.")
+    st.info("**Demo login** → `admin` / `admin123`  ·  `officer` / `officer123`")
+    st.stop()
+
+# sidebar starts open so the nav is always visible
+st.set_page_config(page_title="DRISHTI · Bengaluru", page_icon="🚦",
+                   layout="wide", initial_sidebar_state="expanded")
+
+
+# ---------------- data ----------------
+@st.cache_data
+def load():
+    hot = pd.read_parquet(PROC / "hotspots.parquet")
+    fc = pd.read_parquet(PROC / "forecast.parquet")
+    off = pd.read_parquet(PROC / "offenders.parquet")
+    meta = json.loads((PROC / "meta.json").read_text())
+    fc = fc.merge(hot[["h3", "location", "junction_name", "cii"]], on="h3", how="left")
+    return hot, fc, off, meta
+
+
+@st.cache_data
+def load_trends():
+    return pd.read_parquet(PROC / "trends.parquet")
+
+
+@st.cache_data
+def load_byday():
+    return pd.read_parquet(PROC / "trends_byday.parquet")
+
+
+def cii_color(cii):
+    x = max(0.0, min(1.0, cii / 100.0))
+    g, y, r = (22, 163, 74), (245, 158, 11), (220, 38, 38)
+    if x < 0.5:
+        f, a, b = x / 0.5, g, y
+    else:
+        f, a, b = (x - 0.5) / 0.5, y, r
+    return [int(a[i] + (b[i] - a[i]) * f) for i in range(3)] + [185]
+
+
+def cii_to_hex(c):
+    r, g, b, _ = cii_color(c)
+    return f"rgb({r},{g},{b})"
+
+
+# ---------------- theme CSS (theme-AGNOSTIC: adapts to light & dark) ----------------
+def inject_css():
+    # No hardcoded background/text colours -> the native Light/Dark theme (⋮ menu)
+    # stays fully consistent, including tables. Only shape + accent + font here.
+    st.markdown("""
+    <style>
+      @import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700;800&display=swap');
+      html, body, [class*="css"], .stApp { font-family:'Plus Jakarta Sans',sans-serif; }
+      /* translucent violet glow works over both dark and light backgrounds */
+      .stApp { background-image:
+        radial-gradient(1000px 520px at 80% -10%, rgba(124,77,255,0.16), transparent 60%); }
+      footer { visibility:hidden; }          /* keep the header so the ⋮ menu + sidebar toggle work */
+      .block-container { padding-top:1.6rem; }
+      h1,h2,h3,h4 { font-weight:700; letter-spacing:-0.01em; }
+      [data-testid="stMetric"] {
+        background:rgba(212,175,55,0.07); border:1px solid rgba(212,175,55,0.45);
+        border-radius:16px; padding:16px 18px;
+        box-shadow:0 8px 30px rgba(160,120,20,0.10); backdrop-filter:blur(8px); }
+      .stButton button, .stDownloadButton button {
+        background:linear-gradient(135deg,#7C3AED,#A855F7); color:#fff;
+        border:none; border-radius:10px; font-weight:600; }
+      .stTextInput input, [data-baseweb="select"] > div {
+        border:1px solid rgba(139,92,246,0.35) !important; border-radius:10px; }
+    </style>""", unsafe_allow_html=True)
+
+
+# ---------------- voice ----------------
+def play_tts(text, lang_code):
+    """Reliable, multilingual TTS via gTTS (plays an MP3). Browser fallback if offline."""
+    try:
+        from gtts import gTTS
+        buf = io.BytesIO()
+        gTTS(text=text, lang=lang_code).write_to_fp(buf)
+        st.audio(buf.getvalue(), format="audio/mp3", autoplay=True)
+        return True
+    except Exception:
+        loc = {"en": "en-IN", "hi": "hi-IN", "kn": "kn-IN"}.get(lang_code, "en-IN")
+        safe = json.dumps(text)
+        components.html(f"""<script>
+            const u=new SpeechSynthesisUtterance({safe});u.lang="{loc}";
+            window.speechSynthesis.cancel();window.speechSynthesis.speak(u);</script>""",
+                        height=0)
+        return False
+
+
+def parse_command(text):
+    low = (text or "").lower().strip()
+    out = {"speak": any(w in low for w in ["read", "speak", "say", "aloud", "tell",
+                                           "ಮಾತ", "ಓದ", "बोल", "पढ"])}
+    # which language to SPEAK the answer in (overrides the UI language)
+    if any(w in low for w in ["hindi", "हिंदी", "हिन्दी", "हिंदी में"]):
+        out["say_lang"] = "hi"
+    elif any(w in low for w in ["kannada", "ಕನ್ನಡ", "kannad"]):
+        out["say_lang"] = "kn"
+    elif "english" in low:
+        out["say_lang"] = "en"
+    m = re.search(r"(?:top|ಮೇಲಿನ|शीर्ष)\s*(\d+)", low)
+    if m:
+        out["topn"] = max(5, min(50, int(m.group(1))))
+    if any(w in low for w in ["worst", "high impact", "critical", "severe",
+                              "ಕೆಟ್ಟ", "खराब", "गंभीर"]):
+        out["min_cii"] = 80
+    return out
+
+
+def speak_summary(rows, say_lang, n):
+    """Build a spoken summary of the top-n zones in the requested language."""
+    rows = rows.head(n)
+    if say_lang == "hi":
+        parts = [f"शीर्ष {len(rows)} क्षेत्र।"]
+        for i, (_, r) in enumerate(rows.iterrows(), 1):
+            parts.append(f"{i}. {r['location'].split(',')[0]}, "
+                         f"सी आई आई {r['cii']:.0f}, {int(r['n_violations'])} उल्लंघन।")
+        return " ".join(parts)
+    if say_lang == "kn":
+        parts = [f"ಮೇಲಿನ {len(rows)} ಪ್ರದೇಶಗಳು."]
+        for i, (_, r) in enumerate(rows.iterrows(), 1):
+            parts.append(f"{i}. {r['location'].split(',')[0]}, "
+                         f"ಸಿ ಐ ಐ {r['cii']:.0f}, {int(r['n_violations'])} ಉಲ್ಲಂಘನೆ.")
+        return " ".join(parts)
+    nums = ["one", "two", "three", "four", "five", "six", "seven", "eight"]
+    parts = [f"Top {len(rows)} zones."]
+    for i, (_, r) in enumerate(rows.iterrows()):
+        label = nums[i] if i < len(nums) else str(i + 1)
+        parts.append(f"{label}: {r['location'].split(',')[0]}, "
+                     f"C I I {r['cii']:.0f}, {int(r['n_violations'])} violations.")
+    return " ".join(parts)
+
+
+# ---------------- plotly helpers (let theme="streamlit" adapt to light/dark) ----------------
+def _layout(fig, height=240, title=None):
+    fig.update_layout(height=height, margin=dict(l=10, r=10, t=36 if title else 8, b=8),
+                      title=dict(text=title, font=dict(size=14)) if title else None,
+                      paper_bgcolor="rgba(0,0,0,0)", plot_bgcolor="rgba(0,0,0,0)",
+                      showlegend=False)
+    return fig
+
+
+def line_chart(daily, title, mark_last=False):
+    fig = go.Figure(go.Scatter(x=daily["label"], y=daily["value"], mode="lines",
+                               line=dict(color=VIOLET, width=2.5), fill="tozeroy",
+                               fillcolor="rgba(139,92,246,0.22)"))
+    if mark_last and len(daily):
+        row = daily.iloc[-1]
+        fig.add_trace(go.Scatter(x=[row["label"]], y=[row["value"]], mode="markers",
+                                 marker=dict(color="#F472B6", size=13)))
+    fig.update_xaxes(showgrid=False)
+    return _layout(fig, title=title)
+
+
+def bar_chart(d, title, ramp=False):
+    colors = [cii_to_hex(v / (max(d["value"]) or 1) * 100) for v in d["value"]] if ramp else VIOLET
+    fig = go.Figure(go.Bar(x=d["label"], y=d["value"], marker_color=colors))
+    fig.update_xaxes(showgrid=False)
+    return _layout(fig, title=title)
+
+
+def rainbow_gauge(value, title):
+    stops = [(0.0, (34, 211, 238)), (0.4, (52, 211, 153)),
+             (0.7, (250, 204, 21)), (1.0, (244, 114, 182))]
+
+    def lerp(tt):
+        for i in range(len(stops) - 1):
+            t0, c0 = stops[i]
+            t1, c1 = stops[i + 1]
+            if tt <= t1:
+                f = (tt - t0) / (t1 - t0 + 1e-9)
+                return tuple(int(c0[j] + (c1[j] - c0[j]) * f) for j in range(3))
+        return stops[-1][1]
+
+    seg = 28
+    steps = [{"range": [i / seg * 100, (i + 1) / seg * 100],
+              "color": f"rgb{lerp((i + 0.5) / seg)}"} for i in range(seg)]
+    fig = go.Figure(go.Indicator(
+        mode="gauge+number", value=value, number={"suffix": "%", "font": {"size": 38}},
+        gauge={"axis": {"range": [0, 100], "tickwidth": 0},
+               "bar": {"color": "rgba(255,255,255,0)"}, "borderwidth": 0, "steps": steps}))
+    return _layout(fig, height=250, title=title)
+
+
+# ---------------- gradient KPI card + donut ----------------
+def sparkline_svg(series, color, w=120, h=36):
+    if not series or len(series) < 2:
+        return ""
+    mn, mx = min(series), max(series)
+    rng = (mx - mn) or 1
+    pts = " ".join(
+        f"{i/(len(series)-1)*w:.1f},{h - (v-mn)/rng*(h-7) - 4:.1f}"
+        for i, v in enumerate(series))
+    last = pts.split()[-1]
+    return (f"<svg width='{w}' height='{h}' viewBox='0 0 {w} {h}' "
+            f"preserveAspectRatio='none'><polyline points='{pts}' fill='none' "
+            f"stroke='{color}' stroke-width='2' stroke-linecap='round' "
+            f"stroke-linejoin='round'/><circle cx='{last.split(',')[0]}' "
+            f"cy='{last.split(',')[1]}' r='2.6' fill='{color}'/></svg>")
+
+
+def bars_svg(vals, colors, w=120, h=36):
+    mx = max(vals) or 1
+    bw = w / (len(vals) * 1.7)
+    gap = bw * 0.7
+    rects = "".join(
+        f"<rect x='{i*(bw+gap)+gap:.1f}' y='{h-(v/mx)*(h-5)-2:.1f}' width='{bw:.1f}' "
+        f"height='{(v/mx)*(h-5):.1f}' rx='2' fill='{colors[i]}'/>"
+        for i, v in enumerate(vals))
+    return f"<svg width='{w}' height='{h}' viewBox='0 0 {w} {h}'>{rects}</svg>"
+
+
+def _delta(series, lower_is_better=True):
+    if not series or len(series) < 14:
+        return ""
+    k = min(30, len(series) // 2)
+    recent = sum(series[-k:]) / k
+    prior = sum(series[-2 * k:-k]) / k
+    if prior == 0:
+        return ""
+    pct = (recent - prior) / prior * 100
+    up = pct >= 0
+    good = (not up) if lower_is_better else up
+    color = "#34D399" if good else "#F87171"
+    return (f"<span style='color:{color};font-weight:600;'>{'▲' if up else '▼'} "
+            f"{abs(pct):.1f}%</span> <span style='opacity:0.55;font-size:0.72rem;'>"
+            f"vs prev {k}d</span>")
+
+
+def kpi_card(icon, label, value, accent=VIOLET, series=None, viz="spark",
+             sub=None, lower_is_better=True):
+    if viz == "bars" and series:
+        chart = bars_svg(series, ["rgba(170,170,190,0.30)", accent])
+    elif series:
+        chart = sparkline_svg(series, accent)
+    else:
+        chart = ""
+    delta = sub if sub else _delta(series, lower_is_better)
+    delta_html = (f"<div style='font-size:0.78rem;margin-top:7px;'>{delta}</div>"
+                  if delta else "")
+    st.markdown(
+        f"<div style='background:rgba(139,92,246,0.06);"
+        f"border:1px solid rgba(139,92,246,0.28);border-radius:16px;"
+        f"padding:16px 18px;height:152px;box-shadow:0 6px 20px rgba(80,40,160,0.10);'>"
+        f"<div style='display:flex;justify-content:space-between;align-items:flex-start;'>"
+        f"<div style='width:36px;height:36px;border-radius:10px;background:{accent}26;"
+        f"display:flex;align-items:center;justify-content:center;font-size:18px;'>{icon}</div>"
+        f"<div>{chart}</div></div>"
+        f"<div style='font-size:0.82rem;opacity:0.7;margin-top:10px;'>{label}</div>"
+        f"<div style='font-size:1.9rem;font-weight:800;line-height:1.1;'>{value}</div>"
+        f"{delta_html}</div>", unsafe_allow_html=True)
+
+
+def donut(labels, values, title):
+    fig = go.Figure(go.Pie(labels=list(labels), values=list(values), hole=0.62,
+                           marker=dict(colors=DONUT_COLORS), textinfo="percent",
+                           textfont=dict(color="#fff", size=12), sort=True))
+    fig.update_layout(height=300, margin=dict(l=10, r=10, t=42, b=10),
+                      title=dict(text=title, font=dict(size=14)),
+                      paper_bgcolor="rgba(0,0,0,0)", plot_bgcolor="rgba(0,0,0,0)",
+                      legend=dict(orientation="v", x=1, y=0.5, font=dict(size=11)))
+    return fig
+
+
+def active_theme():
+    """Active theme ('light'/'dark'); defaults to dark on first run / older Streamlit."""
+    try:
+        tp = st.context.theme.type
+        return tp if tp in ("light", "dark") else "dark"
+    except Exception:
+        return "dark"
+
+
+# ==================== APP ====================
+inject_css()
+require_login()        # comment this line out to disable the login gate
+hot, fc, off, meta = load()
+THEME = active_theme()
+ACCENT = "#FACC15" if THEME == "dark" else "#2563EB"   # gold text -> yellow (dark) / blue (light)
+area_vocab = build_area_vocab(hot)
+hot["fill"] = hot["cii"].apply(cii_color)
+mm = meta["model_metrics"]
+
+NAV_KEYS = ["tab_map", "tab_ops", "tab_trends", "tab_rank", "tab_off", "tab_fc"]
+NAV_ICONS = ["geo-alt-fill", "broadcast", "graph-up", "list-check",
+             "exclamation-triangle-fill", "magic"]
+
+with st.sidebar:
+    st.markdown(
+        "<div style='display:flex;align-items:center;gap:11px;margin:2px 0 14px 0;'>"
+        "<div style='width:42px;height:42px;border-radius:12px;"
+        "background:linear-gradient(135deg,#7C3AED,#EC4899);color:#fff;font-weight:800;"
+        "font-size:23px;display:flex;align-items:center;justify-content:center;"
+        "box-shadow:0 4px 16px rgba(124,77,255,0.45);'>D</div>"
+        "<div><div style='font-weight:800;font-size:1.18rem;line-height:1.05;'>DRISHTI</div>"
+        "<div style='font-size:0.7rem;opacity:0.6;letter-spacing:0.02em;'>"
+        "दृष्टि · Bengaluru Traffic Police</div></div></div>",
+        unsafe_allow_html=True)
+    if st.session_state.get("user"):
+        lo1, lo2 = st.columns([2, 1])
+        lo1.markdown(
+            f"<div style='background:rgba(139,92,246,0.12);border-radius:10px;"
+            f"padding:7px 11px;font-size:0.82rem;'>👤 <b>{st.session_state['user']}</b>"
+            f"</div>", unsafe_allow_html=True)
+        if lo2.button("Log out", use_container_width=True):
+            st.session_state.clear()
+            st.query_params.clear()
+            st.rerun()
+    st.markdown("<div style='height:8px;'></div>", unsafe_allow_html=True)
+    lang_label = st.selectbox("🌐 " + t("language", "en"), list(LANGS.keys()))
+    lang = LANGS[lang_label]
+    st.markdown("<div style='font-size:0.7rem;font-weight:700;letter-spacing:0.08em;"
+                "opacity:0.45;margin:10px 0 2px 2px;'>NAVIGATION</div>",
+                unsafe_allow_html=True)
+    labels = [re.sub(r"^[^\w]+", "", t(k, lang)).strip() for k in NAV_KEYS]
+    if HAS_MENU:
+        choice = option_menu(
+            None, labels, icons=NAV_ICONS, default_index=0,
+            styles={"container": {"background-color": "transparent", "padding": "2px 0"},
+                    "icon": {"color": "#9B8FC2", "font-size": "15px"},
+                    "nav-link": {"color": "#9B8FC2", "font-size": "14px",
+                                 "border-radius": "10px", "margin": "3px 0",
+                                 "--hover-color": "rgba(139,92,246,0.15)"},
+                    "nav-link-selected": {"background-color": VIOLET, "color": "#fff",
+                                          "font-weight": "600"}})
+    else:
+        st.caption("⚠️ run `pip install -r requirements.txt` for the icon nav")
+        choice = st.radio("Navigate", labels, label_visibility="collapsed")
+    section = NAV_KEYS[labels.index(choice)]
+
+    st.divider()
+    st.markdown("<div style='font-size:0.72rem;font-weight:700;letter-spacing:0.06em;"
+                "opacity:0.5;margin-bottom:6px;'>🎨 THEME</div>", unsafe_allow_html=True)
+    _cur = st.query_params.get("theme", "system")
+    _keep = "auth=1&" if st.session_state.get("authed") else ""
+    _seg = [("system", "◐", "System"), ("light", "☀", "Light"), ("dark", "🌙", "Dark")]
+    _html = ("<div style='display:flex;gap:4px;background:rgba(139,92,246,0.10);"
+             "border:1px solid rgba(139,92,246,0.25);border-radius:11px;padding:4px;'>")
+    for _val, _ic, _lab in _seg:
+        _active = (_cur == _val)
+        _href = "?" + _keep + ("" if _val == "system" else f"theme={_val}")
+        _href = _href.rstrip("&") or "?"
+        _style = ("background:#8B5CF6;color:#fff;box-shadow:0 2px 8px rgba(139,92,246,0.4);"
+                  if _active else "color:#9B8FC2;")
+        _html += (f"<a href='{_href}' target='_self' style='flex:1;text-align:center;"
+                  f"padding:7px 2px;border-radius:8px;text-decoration:none;line-height:1.25;"
+                  f"font-size:0.7rem;font-weight:600;{_style}'>"
+                  f"<div style='font-size:1.05rem;'>{_ic}</div>{_lab}</a>")
+    _html += "</div>"
+    st.markdown(_html, unsafe_allow_html=True)
+    st.divider()
+    if "history" not in st.session_state:
+        st.session_state.history = []
+    st.markdown("**" + t("history", lang) + "**")
+    if st.session_state.history:
+        for h in reversed(st.session_state.history[-8:]):
+            st.caption(f"• {h['q']}  _( {h['t']} )_")
+        if st.button(t("clear_history", lang)):
+            st.session_state.history = []
+            st.rerun()
+    else:
+        st.caption(t("no_history", lang))
+    st.markdown(
+        f"<div style='margin-top:14px;background:rgba(52,211,153,0.10);"
+        f"border:1px solid rgba(52,211,153,0.3);border-radius:12px;padding:10px 12px;"
+        f"font-size:0.76rem;'>🟢 <b>Live</b> · {meta['n_cells']:,} zones monitored<br>"
+        f"<span style='opacity:0.65;'>Forecast MAE {mm['valid_mae']} · "
+        f"↓{mm.get('improvement_pct','')}% vs baseline</span></div>",
+        unsafe_allow_html=True)
+
+# ----- header + KPIs (always) -----
+st.markdown(
+    "<h1 style='line-height:1.55;margin:0 0 2px 0;padding-top:0.14em;font-size:2.55rem;"
+    "font-weight:800;letter-spacing:-0.01em;'>दृष्टि — DRISHTI</h1>",
+    unsafe_allow_html=True)
+st.markdown(
+    f"<div style='color:{ACCENT};font-weight:600;font-size:1.02rem;'>"
+    "Digital Real-time Intelligence for Smart Hotspot &amp; Traffic Insights</div>",
+    unsafe_allow_html=True)
+st.caption("हर सड़क पर नज़र, हर सफ़र आसान  ·  "
+           f"Bengaluru · {meta['date_range'][0]} → {meta['date_range'][1]} · "
+           f"{meta['n_records']:,} violations · {meta['n_cells']:,} zones")
+
+sp = meta.get("kpi_sparks", {})
+kc = st.columns(4)
+with kc[0]:
+    kpi_card("🚗", t("kpi_violations", lang), f"{meta['n_records']:,}",
+             accent="#8B5CF6", series=sp.get("violations"))
+with kc[1]:
+    kpi_card("📍", t("kpi_zones", lang), f"{meta['n_cells']:,}",
+             accent="#22D3EE", series=sp.get("zones"))
+with kc[2]:
+    kpi_card("🔥", t("kpi_high", lang), f"{int((hot.cii >= 70).sum()):,}",
+             accent=ACCENT, series=sp.get("peak"))
+with kc[3]:
+    bl = mm.get("baseline_lag7_mae", 1.0)
+    kpi_card("🎯", t("kpi_mae", lang), mm["valid_mae"], accent="#34D399",
+             series=[bl, mm["valid_mae"]], viz="bars",
+             sub=(f"<span style='color:#34D399;font-weight:600;'>↓ "
+                  f"{mm['improvement_pct']}% vs baseline</span>"
+                  if mm.get("improvement_pct") else None))
+st.write("")
+
+# ----- voice / command bar (always) -----
+st.subheader("🎙️ " + t("voice_nav", lang))
+cv1, cv2 = st.columns([3, 1])
+with cv1:
+    typed = st.text_input(t("ask", lang), placeholder=t("placeholder", lang))
+spoken = None
+with cv2:
+    st.write("")
+    if HAS_MIC:
+        spoken = speech_to_text(language=SPEECH_LANG.get(lang, "en-IN"),
+                                start_prompt=t("speak", lang), stop_prompt=t("stop", lang),
+                                just_once=True, use_container_width=True, key="stt")
+mic_status = ("🎤 mic ready (use Chrome, allow the mic, stay online)" if HAS_MIC
+              else "⚠️ mic component missing — run `pip install -r requirements.txt`")
+st.caption(mic_status + "  ·  🔊 read-aloud works in English / Kannada / Hindi")
+
+query = spoken or typed
+if query:
+    cmd = parse_command(query)
+    res = hot.copy()
+    area = resolve_area(query, lang, area_vocab)
+    if area:
+        res = res[res["location"].str.contains(re.escape(area), case=False, na=False)]
+    if "min_cii" in cmd:
+        res = res[res["cii"] >= cmd["min_cii"]]
+    res = res.head(cmd.get("topn", 10))
+    st.session_state.history.append(
+        {"q": query, "t": datetime.now().strftime("%H:%M"), "lang": lang,
+         "area": area or "", "results": len(res)})
+    tag = f" → {area}" if area else ""
+    st.markdown(f"**{t('understood', lang)}:** _{query}_{tag} ({len(res)})")
+    st.dataframe(res[["cii_rank", "cii", "location", "junction_name", "n_violations",
+                      "top_violation"]].rename(columns={
+        "cii_rank": "Rank", "cii": "CII", "location": "Location",
+        "junction_name": "Junction", "n_violations": "Violations",
+        "top_violation": "Top violation"}), use_container_width=True, hide_index=True)
+    if len(res):
+        say_lang = cmd.get("say_lang", lang)        # query language overrides UI language
+        speak_n = min(len(res), cmd.get("topn", 3), 8)
+        summary = speak_summary(res, say_lang, speak_n)
+        lang_name = {"en": "English", "hi": "Hindi", "kn": "Kannada"}[say_lang]
+        if cmd.get("speak"):
+            play_tts(summary, say_lang)
+        if st.button(f"🔊 Read aloud ({lang_name})", key="read_btn"):
+            play_tts(summary, say_lang)
+
+st.divider()
+
+# ==================== sections ====================
+if section == "tab_map":
+    min_cii = st.slider(t("min_cii", lang), 0, 100, 40, 5)
+    view = hot[hot.cii >= min_cii]
+    st.caption(f"{len(view):,} / {len(hot):,}")
+    layer = pdk.Layer("H3HexagonLayer", view, pickable=True, filled=True, extruded=True,
+                      get_hexagon="h3", get_fill_color="fill",
+                      get_elevation="cii", elevation_scale=18, opacity=0.55)
+    st.pydeck_chart(pdk.Deck(
+        layers=[layer],
+        initial_view_state=pdk.ViewState(latitude=12.97, longitude=77.59, zoom=11, pitch=45),
+        map_style="dark",
+        tooltip={"html": "<b>CII {cii}</b> (rank #{cii_rank})<br/>{location}<br/>"
+                         "<b>{n_violations}</b> violations · <b>{active_days}</b> days<br/>"
+                         "Top: {top_violation}"},
+    ), use_container_width=True, height=560)
+
+elif section == "tab_ops":
+    st.subheader("🚨 Live operations — congestion alerts & enforcement")
+    st.caption("⚠️ Simulated live feed: historical hotspots replayed as real-time alerts. "
+               "In production this is driven by live ANPR / e-challan feeds, with push "
+               "notifications to field officers and control-room displays.")
+
+    thr = st.slider("Trigger an alert when CII ≥", 50, 100, 75, 5)
+    alerts = (hot[hot.cii >= thr].sort_values("cii", ascending=False)
+              .head(20).reset_index(drop=True))
+
+    def rec_action(c):
+        if c >= 88:
+            return "🚨 Deploy patrol + initiate towing"
+        if c >= 78:
+            return "⚠️ On-spot enforcement / challan drive"
+        return "👁 Monitor + advisory signage"
+    alerts["Recommended action"] = alerts["cii"].apply(rec_action)
+
+    if st.checkbox("🔴 Live mode (auto-refresh)") and HAS_AUTOREFRESH and len(alerts):
+        n = st_autorefresh(interval=2500, key="ops")
+        latest = alerts.iloc[n % len(alerts)]
+        st.markdown(
+            "<div style='background:linear-gradient(135deg,#EF4444,#EC4899);"
+            "border-radius:14px;padding:14px 18px;color:#fff;font-weight:600;'>"
+            f"🔴 LIVE · {datetime.now().strftime('%H:%M:%S')} · "
+            f"{latest['location'].split(',')[0]} · CII {latest['cii']:.0f} · "
+            f"{latest['Recommended action']}</div>", unsafe_allow_html=True)
+        st.write("")
+
+    m = st.columns(3)
+    m[0].metric("Active alerts", len(alerts))
+    m[1].metric("Critical (CII ≥ 88)", int((alerts.cii >= 88).sum()))
+    m[2].metric("Zones monitored", f"{len(hot):,}")
+
+    st.dataframe(alerts[["cii_rank", "cii", "location", "junction_name", "n_violations",
+                         "top_violation", "Recommended action"]].rename(columns={
+        "cii_rank": "Rank", "cii": "CII", "location": "Location",
+        "junction_name": "Junction", "n_violations": "Violations",
+        "top_violation": "Top violation"}),
+        use_container_width=True, hide_index=True, height=340)
+
+    st.markdown("#### 🚓 Impose a regulatory action")
+    if "dispatch_log" not in st.session_state:
+        st.session_state.dispatch_log = []
+    e1, e2 = st.columns(2)
+    zone = e1.selectbox("Zone", alerts["location"].tolist() if len(alerts) else ["—"])
+    act = e2.selectbox("Action", ["Deploy patrol", "Issue no-parking enforcement",
+                                  "Tow & fine", "Install signage / barricade",
+                                  "Escalate to control room", "Mark resolved"])
+    if st.button("📨 Dispatch action"):
+        st.session_state.dispatch_log.insert(0, {
+            "Time": datetime.now().strftime("%H:%M:%S"),
+            "Officer": st.session_state.get("user", "—"),
+            "Zone": zone.split(",")[0], "Action": act})
+        st.success(f"Dispatched: {act} → {zone.split(',')[0]}")
+    if st.session_state.dispatch_log:
+        st.markdown("**Dispatch log — this session**")
+        st.dataframe(pd.DataFrame(st.session_state.dispatch_log),
+                     use_container_width=True, hide_index=True, height=200)
+
+elif section == "tab_trends":
+    tr = load_trends()
+    byday = load_byday()
+    daily = tr[tr.kind == "daily"].sort_values("order").reset_index(drop=True)
+    DOW = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+    cursor = None
+    live = st.checkbox(t("live_replay", lang), value=False)
+    if live and HAS_AUTOREFRESH:
+        n = st_autorefresh(interval=1200, key="replay")
+        cursor = n % len(daily)
+        row = daily.iloc[cursor]
+        lc1, lc2 = st.columns(2)
+        lc1.metric("Replay day", row["label"])
+        lc2.metric("Violations that day", int(row["value"]))
+    elif live and not HAS_AUTOREFRESH:
+        st.caption("Install `streamlit-autorefresh` to enable live replay.")
+
+    if cursor is not None:
+        # cumulative time-lapse for the line + animated bars
+        rday = daily.iloc[cursor]["label"]
+        dline = daily.iloc[:cursor + 1]
+        bh = (byday[(byday.dim == "hour") & (byday.date <= rday)]
+              .groupby("key")["value"].sum().reset_index())
+        bh.columns = ["label", "value"]
+        bh["order"] = bh["label"].astype(int)
+        hourly = bh.sort_values("order")
+        dd = dline.copy()
+        dd["dow"] = pd.to_datetime(dd["label"]).dt.dayofweek
+        bw = dd.groupby("dow")["value"].sum().reindex(range(7), fill_value=0)
+        dow = pd.DataFrame({"label": DOW, "value": bw.values, "order": range(7)})
+        line = line_chart(dline, t("t_daily", lang), mark_last=True)
+    else:
+        hourly = tr[tr.kind == "hourly"].sort_values("order")
+        dow = tr[tr.kind == "dow"].sort_values("order")
+        line = line_chart(daily, t("t_daily", lang))
+
+    veh = tr[tr.kind == "vehicle"].sort_values("value", ascending=False)
+    vtype = tr[tr.kind == "vtype"].sort_values("value", ascending=False)
+
+    st.plotly_chart(line, use_container_width=True)
+    r1 = st.columns(2)
+    with r1[0]:
+        st.plotly_chart(bar_chart(hourly, t("t_hourly", lang), ramp=True), use_container_width=True)
+    with r1[1]:
+        st.plotly_chart(bar_chart(dow, t("t_dow", lang)), use_container_width=True)
+    r2 = st.columns(2)
+    with r2[0]:
+        st.plotly_chart(donut(veh["label"], veh["value"], t("t_vehicle", lang)),
+                        use_container_width=True)
+    with r2[1]:
+        st.plotly_chart(donut(vtype["label"], vtype["value"], t("t_vtype", lang)),
+                        use_container_width=True)
+    g = st.columns([1, 2, 1])
+    with g[1]:
+        conc = round(hot.head(100)["n_violations"].sum() / meta["n_records"] * 100, 1)
+        st.plotly_chart(rainbow_gauge(conc, t("t_gauge", lang)), use_container_width=True)
+
+elif section == "tab_rank":
+    topn = st.slider(t("top_n_zones", lang), 5, 50, 20, 5)
+    cols = ["cii_rank", "cii", "location", "junction_name", "police_station",
+            "n_violations", "active_days", "persistence", "peak_share", "top_violation"]
+    tbl = hot[cols].head(topn).copy()
+    tbl["persistence"] = (tbl["persistence"] * 100).round(0).astype(int).astype(str) + "%"
+    tbl["peak_share"] = (tbl["peak_share"] * 100).round(0).astype(int).astype(str) + "%"
+    st.dataframe(tbl.rename(columns={
+        "cii_rank": "Rank", "cii": "CII", "location": "Location",
+        "junction_name": "Nearest junction", "police_station": "Police station",
+        "n_violations": "Violations", "active_days": "Active days",
+        "persistence": "Persistence", "peak_share": "Peak share",
+        "top_violation": "Top violation"}),
+        use_container_width=True, hide_index=True, height=520)
+    st.download_button(t("dl_priorities", lang), hot[cols].head(topn).to_csv(index=False),
+                       "enforcement_priorities.csv", mime="text/csv")
+
+elif section == "tab_off":
+    s = meta.get("offender_summary", {})
+    o1, o2, o3 = st.columns(3)
+    o1.metric(t("repeat_offenders", lang), f"{s.get('repeat_offenders', 0):,}")
+    o2.metric(t("share_violations", lang), f"{s.get('repeat_share_pct', 0)}%")
+    o3.metric(t("worst_vehicle", lang), f"{s.get('worst_count', 0)}")
+
+    st.markdown("##### Offender intelligence")
+    cc = st.columns(2)
+    with cc[0]:
+        topo = off.head(12)
+        st.plotly_chart(bar_chart(
+            pd.DataFrame({"label": topo["vehicle_number"], "value": topo["n_violations"]}),
+            "Top 12 offenders · violations", ramp=True), use_container_width=True)
+    with cc[1]:
+        vt = off.groupby("vehicle_type").size().sort_values(ascending=False)
+        st.plotly_chart(donut(vt.index.tolist(), vt.values.tolist(),
+                              "Offenders by vehicle type"), use_container_width=True)
+    zh = off.groupby("n_zones").size().reset_index(name="cnt").sort_values("n_zones")
+    st.plotly_chart(bar_chart(
+        pd.DataFrame({"label": zh["n_zones"].astype(str) + " zone(s)", "value": zh["cnt"]}),
+        "Spatial spread · how many distinct zones each offender hits"),
+        use_container_width=True)
+
+    q = st.text_input(t("search_vehicle", lang), key="off_search")
+    view = off
+    if q:
+        view = off[off["vehicle_number"].str.contains(q, case=False, na=False)
+                   | off["top_location"].str.contains(q, case=False, na=False)]
+    n_off = st.slider(t("top_n_off", lang), 5, 100, 25, 5, key="off_n")
+    st.dataframe(view.head(n_off)[["rank", "vehicle_number", "n_violations", "n_zones",
+                                   "vehicle_type", "top_location", "first_seen",
+                                   "last_seen"]].rename(columns={
+        "rank": "Rank", "vehicle_number": "Vehicle (anon.)", "n_violations": "Violations",
+        "n_zones": "Zones hit", "vehicle_type": "Type", "top_location": "Most-seen location",
+        "first_seen": "First seen", "last_seen": "Last seen"}),
+        use_container_width=True, hide_index=True, height=460)
+    st.download_button(t("dl_offenders", lang), view.head(n_off).to_csv(index=False),
+                       "repeat_offenders.csv", mime="text/csv", key="off_dl")
+
+elif section == "tab_fc":
+    day = fc["forecast_for"].iat[0]
+    st.caption(f"{day}")
+    topf = fc.head(25).copy()
+    fc_layer = pdk.Layer("ScatterplotLayer", topf, pickable=True, get_position="[lon, lat]",
+                         get_radius="pred_intensity * 6 + 60",
+                         get_fill_color="[244, 114, 182, 160]")
+    st.pydeck_chart(pdk.Deck(
+        layers=[fc_layer],
+        initial_view_state=pdk.ViewState(latitude=12.97, longitude=77.59, zoom=11, pitch=0),
+        map_style="dark",
+        tooltip={"html": "Risk #{risk_rank} · {pred_intensity}<br/>{location}"},
+    ), use_container_width=True, height=520)
+    st.dataframe(topf[["risk_rank", "location", "junction_name",
+                       "pred_intensity", "cii"]].rename(columns={
+        "risk_rank": "Risk rank", "location": "Location", "junction_name": "Nearest junction",
+        "pred_intensity": "Predicted intensity", "cii": "Current CII"}),
+        use_container_width=True, hide_index=True)
+
+st.divider()
+st.caption(f"CII = severity-weighted volume (45%) + persistence (30%) + peak "
+           f"concentration (25%), amplified near junctions. Forecast: LightGBM, "
+           f"MAE {mm['valid_mae']} ({mm['improvement_pct']}% better than baseline).")

data/processed/forecast.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3dc6af6e39b79339ec846f8910b3aa1474501ba5bb1c81fb15cd16b7e441707
+size 38055

data/processed/hotspots.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da19eea574bc73e04e05843033d342fba40cde8d2b4c61139aed3824e098183f
+size 197264

data/processed/meta.json

@@ -0,0 +1,503 @@
+{
+  "date_range": [
+    "2023-11-10",
+    "2024-04-08"
+  ],
+  "total_days": 151,
+  "n_records": 298445,
+  "n_cells": 2534,
+  "h3_res": 9,
+  "severity_weights": {
+    "PARKING IN A MAIN ROAD": 1.0,
+    "PARKING NEAR ROAD CROSSING": 0.9,
+    "PARKING NEAR TRAFFIC LIGHT OR ZEBRA CROSS": 0.9,
+    "DOUBLE PARKING": 0.85,
+    "PARKING NEAR BUSTOP/SCHOOL/HOSPITAL ETC": 0.7,
+    "PARKING OPPOSITE TO ANOTHER PARKED VEHICLE": 0.6,
+    "PARKING ON FOOTPATH": 0.5,
+    "WRONG PARKING": 0.5,
+    "PARKING OTHER THAN BUS STOP": 0.45,
+    "NO PARKING": 0.4
+  },
+  "cii_weights": {
+    "volume": 0.45,
+    "persistence": 0.3,
+    "peak": 0.25
+  },
+  "cii_junction_alpha": 0.5,
+  "offender_summary": {
+    "distinct_vehicles": 231890,
+    "repeat_offenders": 35585,
+    "repeat_share_pct": 34.2,
+    "worst_count": 55
+  },
+  "model_metrics": {
+    "valid_mae": 0.708,
+    "valid_rmse": 2.747,
+    "baseline_lag7_mae": 1.078,
+    "improvement_pct": 34.4,
+    "n_modeled_cells": 1047,
+    "best_iteration": 282
+  },
+  "kpi_sparks": {
+    "violations": [
+      1173,
+      2094,
+      2521,
+      1594,
+      2194,
+      2202,
+      2327,
+      2719,
+      2974,
+      2554,
+      1758,
+      2111,
+      2206,
+      2047,
+      1003,
+      1965,
+      2253,
+      1661,
+      2316,
+      1998,
+      1834,
+      2175,
+      1898,
+      2215,
+      1621,
+      1398,
+      1943,
+      2249,
+      2207,
+      2226,
+      2321,
+      1537,
+      2061,
+      2418,
+      2437,
+      1517,
+      1828,
+      2342,
+      1472,
+      2102,
+      2187,
+      2346,
+      1987,
+      2244,
+      2711,
+      1394,
+      1912,
+      2301,
+      2111,
+      2056,
+      1926,
+      2775,
+      1460,
+      2351,
+      1969,
+      2182,
+      2464,
+      2535,
+      2991,
+      1644,
+      2366,
+      2122,
+      2081,
+      2111,
+      2022,
+      2662,
+      1744,
+      2690,
+      2243,
+      2395,
+      2404,
+      2046,
+      2924,
+      2455,
+      2052,
+      2207,
+      2508,
+      1228,
+      1208,
+      1075,
+      1293,
+      2334,
+      1713,
+      1854,
+      1994,
+      1885,
+      1832,
+      1499,
+      2056,
+      2244,
+      1943,
+      1771,
+      1946,
+      2219,
+      1515,
+      1763,
+      1780,
+      2046,
+      2094,
+      1900,
+      2049,
+      1479,
+      1631,
+      1637,
+      1730,
+      2085,
+      2432,
+      2051,
+      1737,
+      1793,
+      1650,
+      2045,
+      1587,
+      2002,
+      2106,
+      1316,
+      2002,
+      1928,
+      1758,
+      1922,
+      2054,
+      1879,
+      1113,
+      2289,
+      2099,
+      1961,
+      1938,
+      1656,
+      1708,
+      1381,
+      1497,
+      1369,
+      1503,
+      1441,
+      1543,
+      2070,
+      1274,
+      1604,
+      1887,
+      2153,
+      1570,
+      2267,
+      2576,
+      1689,
+      2175,
+      1871,
+      2037,
+      1418,
+      1872,
+      2326,
+      2044
+    ],
+    "zones": [
+      157,
+      314,
+      326,
+      224,
+      359,
+      327,
+      351,
+      329,
+      343,
+      331,
+      227,
+      330,
+      319,
+      311,
+      133,
+      298,
+      295,
+      212,
+      330,
+      311,
+      319,
+      353,
+      290,
+      301,
+      206,
+      201,
+      311,
+      359,
+      338,
+      327,
+      328,
+      215,
+      332,
+      317,
+      321,
+      303,
+      307,
+      294,
+      216,
+      303,
+      358,
+      318,
+      353,
+      324,
+      333,
+      187,
+      287,
+      285,
+      333,
+      299,
+      314,
+      335,
+      209,
+      327,
+      322,
+      331,
+      312,
+      347,
+      353,
+      199,
+      329,
+      341,
+      321,
+      316,
+      341,
+      315,
+      231,
+      371,
+      321,
+      342,
+      302,
+      316,
+      316,
+      223,
+      316,
+      303,
+      322,
+      110,
+      195,
+      154,
+      189,
+      319,
+      294,
+      305,
+      309,
+      255,
+      260,
+      194,
+      316,
+      303,
+      295,
+      264,
+      235,
+      303,
+      178,
+      278,
+      286,
+      289,
+      309,
+      294,
+      293,
+      171,
+      271,
+      245,
+      252,
+      268,
+      348,
+      291,
+      241,
+      300,
+      264,
+      310,
+      277,
+      285,
+      260,
+      198,
+      287,
+      308,
+      254,
+      307,
+      270,
+      261,
+      183,
+      303,
+      295,
+      335,
+      312,
+      262,
+      237,
+      156,
+      235,
+      257,
+      273,
+      253,
+      305,
+      301,
+      185,
+      267,
+      302,
+      307,
+      274,
+      311,
+      341,
+      216,
+      336,
+      303,
+      317,
+      227,
+      294,
+      328,
+      227
+    ],
+    "peak": [
+      322,
+      652,
+      982,
+      386,
+      666,
+      672,
+      511,
+      718,
+      1007,
+      826,
+      498,
+      710,
+      631,
+      589,
+      282,
+      668,
+      644,
+      678,
+      573,
+      635,
+      412,
+      552,
+      516,
+      765,
+      340,
+      529,
+      504,
+      685,
+      666,
+      713,
+      615,
+      377,
+      549,
+      574,
+      588,
+      329,
+      380,
+      677,
+      554,
+      701,
+      446,
+      566,
+      501,
+      728,
+      754,
+      408,
+      596,
+      726,
+      603,
+      452,
+      500,
+      1127,
+      602,
+      709,
+      450,
+      599,
+      687,
+      609,
+      947,
+      536,
+      777,
+      493,
+      444,
+      478,
+      479,
+      922,
+      394,
+      777,
+      733,
+      604,
+      770,
+      526,
+      933,
+      926,
+      624,
+      784,
+      644,
+      405,
+      320,
+      370,
+      371,
+      714,
+      491,
+      545,
+      465,
+      460,
+      637,
+      585,
+      581,
+      683,
+      493,
+      548,
+      481,
+      783,
+      483,
+      486,
+      467,
+      721,
+      402,
+      645,
+      555,
+      527,
+      531,
+      524,
+      491,
+      529,
+      402,
+      440,
+      518,
+      455,
+      316,
+      651,
+      364,
+      558,
+      575,
+      264,
+      468,
+      557,
+      587,
+      599,
+      527,
+      521,
+      322,
+      788,
+      488,
+      627,
+      470,
+      471,
+      443,
+      443,
+      286,
+      284,
+      447,
+      378,
+      410,
+      686,
+      324,
+      308,
+      513,
+      680,
+      543,
+      573,
+      828,
+      684,
+      633,
+      646,
+      616,
+      419,
+      592,
+      947,
+      444
+    ]
+  }
+}

data/processed/offenders.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ecb4d5fa48b4a710454fa6afa3355e4d6a771c03be4d20101a8cd1cb73bc3d8
+size 20041

data/processed/trends.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9e4e3d2ba5eaeb71beaf3da62eab97479f3591fff1be16c16b82c41af10a1bff
+size 5847

data/processed/trends_byday.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cae90c7bc913a452e66d3098ceb8002d1fdf4db0804186eede01006a740d9c62
+size 15406

docs/methodology.md

@@ -0,0 +1,63 @@
+# Methodology — Congestion Impact Index (CII)
+
+## Problem framing
+The brief asks us to *detect illegal-parking hotspots and quantify their impact
+on traffic flow*. The dataset contains 298k+ parking-enforcement records with
+location, time, and violation type, but **no direct traffic-speed/volume
+measurement**. Rather than claim a flow metric we do not have, we build a
+**transparent proxy** for flow impact, derived only from enforcement data, with
+every weight exposed and defensible.
+
+## Pipeline
+1. **Clean** — keep records inside the Bengaluru bounding box with valid
+   timestamps; parse the multi-label `violation_type`; keep only parking-
+   relevant violations.
+2. **Spatial unit** — index every record to an **H3 resolution-9 hexagon**
+   (~174 m edge ≈ a block / deployable patrol zone). Deterministic and
+   map-friendly.
+3. **Per-cell statistics** — severity-weighted volume, active-day persistence,
+   peak-hour concentration, junction proximity.
+4. **CII** — combine the components (below).
+5. **Forecast** — a LightGBM model predicts next-day intensity per cell.
+
+## Severity weighting
+Each violation type is weighted by how much it physically blocks *moving*
+traffic (not legal severity):
+
+| Violation | Weight | Why |
+|---|---|---|
+| Parking in a main road | 1.00 | blocks the carriageway |
+| Near road crossing / traffic light | 0.90 | blocks turning / sightlines |
+| Double parking | 0.85 | removes a live lane |
+| Near bus-stop / school / hospital | 0.70 | high-churn frontage |
+| On footpath | 0.50 | pushes pedestrians into the road |
+| Wrong parking | 0.50 | partial obstruction |
+| No parking | 0.40 | designated-clear zone |
+
+A record's severity is the **max** weight across its violations.
+
+## The index
+For each cell, with rank-normalised components in [0, 1]:
+
+```
+base = 0.45·volume + 0.30·persistence + 0.25·peak_concentration
+CII  = base × (1 + 0.50·junction_share)          # then scaled to 0–100
+```
+
+- **Volume** — total severity-weighted violations (how bad, weighted).
+- **Persistence** — active days ÷ total days. Separates a *chronic* daily
+  bottleneck from a one-off spike. (In this data the worst cells are active
+  ~149/151 days.)
+- **Peak concentration** — share of violations in commute windows (08–11,
+  17–20). A blockage that happens exactly at rush hour hurts flow more.
+- **Junction proximity** — amplifies cells near junctions, where a blockage
+  cascades upstream.
+
+All weights live in `src/config.py` and can be re-tuned in seconds.
+
+## Forecast model
+LightGBM regression on a (cell × day) panel. Features: cell location + junction
+share, calendar (day-of-week, month, weekend), and **lag/rolling** features
+(1/7/14/28-day lags, 7/28-day rolling mean & max). Target: next-day
+severity-weighted intensity. Validated on the final 21 days, compared against a
+naive "same weekday last week" baseline.

experiments/mae_objectives.py

@@ -0,0 +1,38 @@
+"""Quick check: is any other objective better than L1 on MAE? (same split)"""
+import warnings, numpy as np, pandas as pd, lightgbm as lgb
+from src import config
+from src.data_prep import load_clean
+from src.features import add_h3
+from src.model import build_panel, FEATURES
+warnings.filterwarnings("ignore")
+
+df = add_h3(load_clean())
+panel, _, all_dates = build_panel(df)
+m = panel.dropna(subset=[f"lag_{max(config.LAGS)}"]).copy()
+cut = all_dates.max() - pd.Timedelta(days=config.VALID_DAYS)
+tr, va = m[m.date <= cut], m[m.date > cut]
+yv = va["y"].values
+base = float(np.mean(np.abs(va["lag_7"].values - yv)))
+print(f"baseline MAE {base:.3f}\n")
+
+def run(obj, label, extra=None):
+    p = dict(metric="mae", learning_rate=0.05, num_leaves=63, min_data_in_leaf=50,
+             feature_fraction=0.8, bagging_fraction=0.8, bagging_freq=1,
+             seed=config.RANDOM_STATE, verbose=-1, objective=obj)
+    if extra: p.update(extra)
+    d = lgb.Dataset(tr[FEATURES], tr["y"])
+    dv = lgb.Dataset(va[FEATURES], va["y"], reference=d)
+    mdl = lgb.train(p, d, 1500, valid_sets=[dv],
+                    callbacks=[lgb.early_stopping(80), lgb.log_evaluation(0)])
+    pred = np.clip(mdl.predict(va[FEATURES], num_iteration=mdl.best_iteration), 0, None)
+    mae = float(np.mean(np.abs(pred - yv)))
+    print(f"  {label:<34} MAE={mae:.3f}  ({100*(base-mae)/base:+.1f}%)")
+    return mae
+
+run("regression_l1", "L1 / MAE  [CURRENT]")
+run("huber", "Huber")
+run("poisson", "Poisson")
+for vp in (1.1, 1.3, 1.5):
+    run("tweedie", f"Tweedie (variance_power={vp})", {"tweedie_variance_power": vp})
+run("regression_l1", "L1 + tuned (leaves 31, lr .03)",
+    {"num_leaves": 31, "learning_rate": 0.03, "min_data_in_leaf": 100, "lambda_l2": 2.0})

experiments/mae_tuning.py

@@ -0,0 +1,103 @@
+"""Offline experiment: can we lower validation MAE without breaking the pipeline?
+
+Tests objective choices and extra features on the SAME time-split as production,
+so the comparison is apples-to-apples. Prints a table; ships nothing.
+"""
+import warnings
+import numpy as np
+import pandas as pd
+import lightgbm as lgb
+
+from src import config
+from src.data_prep import load_clean
+from src.features import add_h3
+from src.model import build_panel, FEATURES as BASE_FEATURES
+
+warnings.filterwarnings("ignore")
+np.random.seed(config.RANDOM_STATE)
+
+print("Loading + indexing data ...")
+df = add_h3(load_clean())
+panel, keep_cells, all_dates = build_panel(df)
+
+# ---- add candidate features on top of the production panel ----
+panel = panel.sort_values(["h3", "date"]).reset_index(drop=True)
+g = panel.groupby("h3")["y"]
+yshift = g.shift(1)
+# extra short/seasonal lags
+for L in [2, 3, 21]:
+    panel[f"lag_{L}"] = g.shift(L)
+# rolling std (volatility) + a mid window mean
+for W in [7, 14, 28]:
+    panel[f"roll_std_{W}"] = (yshift.groupby(panel["h3"]).rolling(W, min_periods=2)
+                              .std().reset_index(level=0, drop=True))
+panel["roll_mean_14"] = (yshift.groupby(panel["h3"]).rolling(14, min_periods=1)
+                         .mean().reset_index(level=0, drop=True))
+# EWMA (recency-weighted level)
+panel["ewm_7"] = (yshift.groupby(panel["h3"]).ewm(span=7, min_periods=1)
+                  .mean().reset_index(level=0, drop=True))
+# same-weekday mean over the last 4 occurrences (weekly seasonality, no leak)
+sd = panel.groupby(["h3", "dow"])["y"].shift(1)
+panel["samedow_mean4"] = (sd.groupby([panel["h3"], panel["dow"]])
+                          .rolling(4, min_periods=1).mean()
+                          .reset_index(level=[0, 1], drop=True))
+# expanding cell mean (shifted -> no leak)
+panel["cell_expmean"] = (g.apply(lambda s: s.shift(1).expanding().mean())
+                         .reset_index(level=0, drop=True))
+
+panel["roll_std_7"] = panel["roll_std_7"].fillna(0)
+panel["roll_std_14"] = panel["roll_std_14"].fillna(0)
+panel["roll_std_28"] = panel["roll_std_28"].fillna(0)
+
+EXTRA = ["lag_2", "lag_3", "lag_21", "roll_std_7", "roll_std_14", "roll_std_28",
+         "roll_mean_14", "ewm_7", "samedow_mean4", "cell_expmean"]
+
+model_df = panel.dropna(subset=[f"lag_{max(config.LAGS)}"]).copy()
+cutoff = all_dates.max() - pd.Timedelta(days=config.VALID_DAYS)
+train = model_df[model_df["date"] <= cutoff]
+valid = model_df[model_df["date"] > cutoff]
+yv = valid["y"].values
+base_mae = float(np.mean(np.abs(valid["lag_7"].values - yv)))
+print(f"rows train/valid: {len(train):,}/{len(valid):,} | "
+      f"same-weekday baseline MAE: {base_mae:.3f}\n")
+
+
+def run(feats, objective, label, log=False, extra_params=None):
+    p = dict(metric="mae", learning_rate=0.05, num_leaves=63, min_data_in_leaf=50,
+             feature_fraction=0.8, bagging_fraction=0.8, bagging_freq=1,
+             seed=config.RANDOM_STATE, verbose=-1, objective=objective)
+    if extra_params:
+        p.update(extra_params)
+    ytr = np.log1p(train["y"]) if log else train["y"]
+    dtr = lgb.Dataset(train[feats], ytr)
+    dva = lgb.Dataset(valid[feats], (np.log1p(valid["y"]) if log else valid["y"]),
+                      reference=dtr)
+    m = lgb.train(p, dtr, num_boost_round=1200, valid_sets=[dva],
+                  callbacks=[lgb.early_stopping(80), lgb.log_evaluation(0)])
+    pred = m.predict(valid[feats], num_iteration=m.best_iteration)
+    if log:
+        pred = np.expm1(pred)
+    mae = float(np.mean(np.abs(np.clip(pred, 0, None) - yv)))
+    imp = 100 * (base_mae - mae) / base_mae
+    print(f"  {label:<46} MAE={mae:.3f}  ({imp:+.1f}% vs baseline)  it={m.best_iteration}")
+    return mae
+
+
+print("=== production config (reproduce) ===")
+run(BASE_FEATURES, "regression", "L2 objective, base features  [CURRENT]")
+print("\n=== change the training objective only (base features) ===")
+run(BASE_FEATURES, "regression_l1", "L1/MAE objective")
+run(BASE_FEATURES, "huber", "Huber objective")
+run(BASE_FEATURES, "fair", "Fair objective")
+print("\n=== add features ===")
+run(BASE_FEATURES + EXTRA, "regression", "L2 + extra features")
+run(BASE_FEATURES + EXTRA, "regression_l1", "L1 + extra features")
+run(BASE_FEATURES + EXTRA, "huber", "Huber + extra features")
+print("\n=== best combo + mild regularization ===")
+run(BASE_FEATURES + EXTRA, "regression_l1", "L1 + extra + L2 reg + smaller leaves",
+    extra_params=dict(lambda_l2=1.0, num_leaves=48, min_data_in_leaf=80))
+run(BASE_FEATURES + EXTRA, "huber", "Huber + extra + reg",
+    extra_params=dict(lambda_l2=1.0, num_leaves=48, min_data_in_leaf=80))
+print("\n=== log1p target variants ===")
+run(BASE_FEATURES + EXTRA, "regression", "log1p + L2 + extra", log=True)
+run(BASE_FEATURES + EXTRA, "regression_l1", "log1p + L1 + extra", log=True)

hash.py

@@ -0,0 +1,20 @@
+"""Generate a bcrypt hash for a password, to paste into auth_config.yaml.
+
+Usage:
+    python hash.py
+    > Password to hash: ********
+    <prints the hash>
+
+Then replace the plain-text `password:` value in auth_config.yaml with the hash.
+"""
+import getpass
+
+import streamlit_authenticator as stauth
+
+if __name__ == "__main__":
+    pw = getpass.getpass("Password to hash: ")
+    try:
+        hashed = stauth.Hasher([pw]).generate()[0]      # older API
+    except Exception:
+        hashed = stauth.Hasher.hash(pw)                 # newer API
+    print(hashed)

requirements.txt

@@ -0,0 +1,16 @@
+streamlit>=1.46
+pandas>=2.0
+numpy>=1.24
+pyarrow>=14.0
+h3>=4.0
+lightgbm>=4.0
+pydeck>=0.9
+streamlit-mic-recorder>=0.0.8
+indic-transliteration>=2.3
+streamlit-autorefresh>=1.0
+streamlit-option-menu>=0.3.6
+gTTS>=2.5
+plotly>=5.20
+# --- optional login add-on (see src/auth.py) ---
+streamlit-authenticator>=0.3.2
+PyYAML>=6.0

src/auth.py

@@ -0,0 +1,55 @@
+"""OPTIONAL login wrapper (streamlit-authenticator).
+
+This is NOT wired into app.py by default, so the core demo always runs. To turn
+it on, add these two lines at the top of app.py (right after the imports):
+
+    from src.auth import require_login
+    name, username, roles = require_login()
+
+Security notes:
+  * Passwords are bcrypt-hashed by the library (auto_hash=True). For real
+    security, pre-hash with `python hash.py` and store ONLY the hash in
+    auth_config.yaml — never commit plain-text passwords to a public repo.
+  * The login version's `login()` signature has changed across releases; this
+    reads auth state from st.session_state (the stable pattern). Pin your
+    installed version and test the flow locally.
+"""
+import yaml
+from yaml.loader import SafeLoader
+
+import streamlit as st
+import streamlit_authenticator as stauth
+
+
+def get_authenticator(path="auth_config.yaml"):
+    with open(path) as f:
+        config = yaml.load(f, Loader=SafeLoader)
+    return stauth.Authenticate(
+        config["credentials"],
+        config["cookie"]["name"],
+        config["cookie"]["key"],
+        config["cookie"]["expiry_days"],
+        auto_hash=True,
+    )
+
+
+def require_login(path="auth_config.yaml"):
+    """Render the login widget; stop the app unless the user is authenticated.
+
+    Returns (name, username, roles) once logged in.
+    """
+    authenticator = get_authenticator(path)
+    authenticator.login(location="main")
+
+    status = st.session_state.get("authentication_status")
+    if status is False:
+        st.error("Invalid username or password.")
+        st.stop()
+    if status is None:
+        st.info("Please log in to continue.")
+        st.stop()
+
+    authenticator.logout("Logout", "sidebar")
+    return (st.session_state.get("name"),
+            st.session_state.get("username"),
+            st.session_state.get("roles") or [])

src/build_artifacts.py

@@ -0,0 +1,87 @@
+"""Run the full offline pipeline: raw CSV -> small artifacts the app serves.
+
+    python -m src.build_artifacts        # run from the repo root
+
+Outputs:
+    data/processed/hotspots.parquet      per-cell stats + CII
+    data/processed/forecast.parquet      next-day predicted intensity per cell
+    data/processed/meta.json             config, date range, model metrics
+    models/lgbm_intensity.txt            saved LightGBM model
+"""
+import json
+
+from src import config
+from src.data_prep import load_clean
+from src.features import add_h3
+from src.hotspots import build_cell_stats
+from src.impact_index import add_cii
+from src.model import train_and_forecast
+from src.offenders import build_offender_stats, offender_summary
+from src.trends import build_trends, build_byday
+
+
+def main():
+    config.DATA_PROCESSED.mkdir(parents=True, exist_ok=True)
+    config.MODELS_DIR.mkdir(parents=True, exist_ok=True)
+
+    print("[1/4] Loading & cleaning ...")
+    df = load_clean()
+    print(f"      clean parking records: {len(df):,}")
+
+    df = add_h3(df)
+    total_days = (df["ts"].dt.date.max() - df["ts"].dt.date.min()).days + 1
+
+    print("[2/4] Building hotspot stats & CII ...")
+    stats = add_cii(build_cell_stats(df, total_days))
+    stats.to_parquet(config.HOTSPOTS_PARQUET, index=False)
+    print(f"      {len(stats):,} cells -> {config.HOTSPOTS_PARQUET.name}")
+
+    print("[2b] Repeat-offender intelligence ...")
+    offenders = build_offender_stats(df, top_n=500)
+    offenders.to_parquet(config.OFFENDERS_PARQUET, index=False)
+    off_summary = offender_summary(df)
+    print(f"      {len(offenders):,} offenders -> {config.OFFENDERS_PARQUET.name} | {off_summary}")
+
+    print("[2c] Trend aggregates ...")
+    build_trends(df).to_parquet(config.TRENDS_PARQUET, index=False)
+    build_byday(df).to_parquet(config.TRENDS_BYDAY_PARQUET, index=False)
+    print(f"      -> {config.TRENDS_PARQUET.name}, {config.TRENDS_BYDAY_PARQUET.name}")
+
+    print("[3/4] Training LightGBM & forecasting ...")
+    model, forecast, metrics = train_and_forecast(df)
+    model.save_model(str(config.MODEL_PATH))
+    forecast.to_parquet(config.FORECAST_PARQUET, index=False)
+    print(f"      {len(forecast):,} cells -> {config.FORECAST_PARQUET.name}")
+    print(f"      metrics: {metrics}")
+
+    print("[4/4] Writing meta.json ...")
+    # small real daily series for the KPI sparklines
+    dord = sorted(df["date"].unique())
+    gd = df.groupby("date")
+    kpi_sparks = dict(
+        violations=gd["id"].size().reindex(dord, fill_value=0).astype(int).tolist(),
+        zones=gd["h3"].nunique().reindex(dord, fill_value=0).astype(int).tolist(),
+        peak=(df[df["is_peak"]].groupby("date")["id"].size()
+              .reindex(dord, fill_value=0).astype(int).tolist()),
+    )
+    meta = dict(
+        date_range=[df["ts"].dt.date.min().isoformat(),
+                    df["ts"].dt.date.max().isoformat()],
+        total_days=total_days,
+        n_records=int(len(df)),
+        n_cells=int(len(stats)),
+        h3_res=config.H3_RES,
+        severity_weights=config.PARKING_SEVERITY,
+        cii_weights=config.CII_WEIGHTS,
+        cii_junction_alpha=config.CII_JUNCTION_ALPHA,
+        offender_summary=off_summary,
+        model_metrics=metrics,
+        kpi_sparks=kpi_sparks,
+    )
+    config.META_JSON.write_text(json.dumps(meta, indent=2))
+    print(f"      -> {config.META_JSON.name}")
+    print("Done. You can now run:  streamlit run app.py")
+
+
+if __name__ == "__main__":
+    main()

src/config.py

@@ -0,0 +1,55 @@
+"""Central configuration for the parking congestion-impact pipeline.
+
+Every tunable knob lives here so the rest of the code stays declarative and
+the choices are transparent (useful when you defend the design to judges).
+"""
+from pathlib import Path
+
+# ---- Paths -----------------------------------------------------------------
+ROOT = Path(__file__).resolve().parents[1]
+DATA_RAW = ROOT / "data" / "raw" / "violations.csv"
+DATA_PROCESSED = ROOT / "data" / "processed"
+MODELS_DIR = ROOT / "models"
+HOTSPOTS_PARQUET = DATA_PROCESSED / "hotspots.parquet"
+FORECAST_PARQUET = DATA_PROCESSED / "forecast.parquet"
+OFFENDERS_PARQUET = DATA_PROCESSED / "offenders.parquet"
+TRENDS_PARQUET = DATA_PROCESSED / "trends.parquet"
+TRENDS_BYDAY_PARQUET = DATA_PROCESSED / "trends_byday.parquet"
+META_JSON = DATA_PROCESSED / "meta.json"
+MODEL_PATH = MODELS_DIR / "lgbm_intensity.txt"
+
+# ---- Geography (Bengaluru bounding box, for sanity filtering) --------------
+LAT_MIN, LAT_MAX = 12.70, 13.40
+LON_MIN, LON_MAX = 77.30, 77.90
+H3_RES = 9            # ~174 m edge hexagons ~ a block / deployable patrol zone
+
+# ---- Time ------------------------------------------------------------------
+TZ = "Asia/Kolkata"
+PEAK_WINDOWS = [(8, 11), (17, 20)]   # morning & evening commute hours (IST)
+
+# ---- Severity weights: how much each violation blocks MOVING traffic -------
+# Tied to physical flow disruption, not legal severity. Tune and justify.
+PARKING_SEVERITY = {
+    "PARKING IN A MAIN ROAD": 1.00,                 # blocks carriageway
+    "PARKING NEAR ROAD CROSSING": 0.90,
+    "PARKING NEAR TRAFFIC LIGHT OR ZEBRA CROSS": 0.90,
+    "DOUBLE PARKING": 0.85,                          # blocks a lane
+    "PARKING NEAR BUSTOP/SCHOOL/HOSPITAL ETC": 0.70,
+    "PARKING OPPOSITE TO ANOTHER PARKED VEHICLE": 0.60,
+    "PARKING ON FOOTPATH": 0.50,                     # pushes pedestrians to road
+    "WRONG PARKING": 0.50,
+    "PARKING OTHER THAN BUS STOP": 0.45,
+    "NO PARKING": 0.40,
+}
+# Any violation not in this map contributes 0 (non-parking, e.g. number plate).
+
+# ---- Congestion Impact Index (CII) -----------------------------------------
+CII_WEIGHTS = {"volume": 0.45, "persistence": 0.30, "peak": 0.25}  # sum = 1
+CII_JUNCTION_ALPHA = 0.50    # junction-proximity amplification strength
+
+# ---- Modelling -------------------------------------------------------------
+MIN_CELL_VIOLATIONS = 20     # only model cells with >= this many records
+LAGS = [1, 7, 14, 28]        # day lags for the intensity forecast
+ROLL_WINDOWS = [7, 28]       # rolling-window features
+VALID_DAYS = 21              # last N days held out for validation
+RANDOM_STATE = 42

src/data_prep.py

@@ -0,0 +1,71 @@
+"""Load and clean the raw violation data into a tidy parking-records frame."""
+import ast
+import json
+
+import pandas as pd
+
+from src import config
+
+
+def _parse_list(x):
+    """`violation_type` arrives as a JSON-ish string like ["NO PARKING"]."""
+    if isinstance(x, list):
+        return x
+    if not isinstance(x, str) or not x.strip():
+        return []
+    try:
+        return json.loads(x)
+    except Exception:
+        try:
+            return ast.literal_eval(x)
+        except Exception:
+            return []
+
+
+def record_severity(violations):
+    """Max flow-disruption weight across a record's violations (0 if none parking)."""
+    return max((config.PARKING_SEVERITY.get(v, 0.0) for v in violations), default=0.0)
+
+
+def _is_peak(hour):
+    return any(lo <= hour < hi for lo, hi in config.PEAK_WINDOWS)
+
+
+def load_clean():
+    """Return one row per parking violation with engineered time/severity fields."""
+    df = pd.read_csv(config.DATA_RAW, low_memory=False)
+
+    # --- coordinates: drop missing / out-of-Bengaluru ---
+    df = df.dropna(subset=["latitude", "longitude"])
+    df = df[df["latitude"].between(config.LAT_MIN, config.LAT_MAX)
+            & df["longitude"].between(config.LON_MIN, config.LON_MAX)].copy()
+
+    # --- timestamps -> IST ---
+    df["created_dt"] = pd.to_datetime(df["created_datetime"], errors="coerce", utc=True)
+    df = df.dropna(subset=["created_dt"]).copy()
+    df["ts"] = df["created_dt"].dt.tz_convert(config.TZ)
+    df["date"] = df["ts"].dt.date
+    df["hour"] = df["ts"].dt.hour
+    df["dow"] = df["ts"].dt.dayofweek
+    df["month"] = df["ts"].dt.month
+    df["is_peak"] = df["hour"].apply(_is_peak)
+
+    # --- violations & severity ---
+    df["violations"] = df["violation_type"].apply(_parse_list)
+    df["severity"] = df["violations"].apply(record_severity)
+    df = df[df["severity"] > 0].copy()          # keep only parking-relevant records
+
+    # --- junction presence ---
+    df["junction_name"] = df["junction_name"].fillna("No Junction")
+    df["has_junction"] = (df["junction_name"].str.strip().str.lower() != "no junction")
+
+    keep = ["id", "latitude", "longitude", "location", "police_station",
+            "junction_name", "has_junction", "vehicle_type", "vehicle_number", "violations",
+            "severity", "ts", "date", "hour", "dow", "month", "is_peak"]
+    return df[keep].reset_index(drop=True)
+
+
+if __name__ == "__main__":
+    d = load_clean()
+    print(d.shape)
+    print(d.head())

src/features.py

@@ -0,0 +1,23 @@
+"""Spatial (H3) indexing helpers, version-robust across h3 v3 and v4."""
+import h3
+
+from src import config
+
+
+def latlng_to_cell(lat, lng, res=config.H3_RES):
+    if hasattr(h3, "latlng_to_cell"):          # h3 v4
+        return h3.latlng_to_cell(lat, lng, res)
+    return h3.geo_to_h3(lat, lng, res)         # h3 v3
+
+
+def cell_to_latlng(cell):
+    if hasattr(h3, "cell_to_latlng"):          # h3 v4
+        return tuple(h3.cell_to_latlng(cell))
+    return tuple(h3.h3_to_geo(cell))           # h3 v3
+
+
+def add_h3(df):
+    """Attach an H3 cell id to every record (the unit we aggregate hotspots over)."""
+    df = df.copy()
+    df["h3"] = [latlng_to_cell(la, lo) for la, lo in zip(df["latitude"], df["longitude"])]
+    return df

src/hotspots.py

@@ -0,0 +1,50 @@
+"""Aggregate cleaned records into per-H3-cell hotspot statistics."""
+from collections import Counter
+
+import pandas as pd
+
+from src import config
+from src.features import cell_to_latlng
+
+
+def _mode_or_blank(series):
+    s = series.dropna()
+    return s.mode().iat[0] if not s.empty else ""
+
+
+def _main_junction(series):
+    s = series.fillna("No Junction")
+    s = s[s.str.strip().str.lower() != "no junction"]
+    return s.mode().iat[0] if not s.empty else ""
+
+
+def _top_violation(series):
+    c = Counter(v for lst in series for v in lst if v in config.PARKING_SEVERITY)
+    return c.most_common(1)[0][0] if c else ""
+
+
+def build_cell_stats(df, total_days):
+    """One row per H3 cell with the components the CII is built from."""
+    g = df.groupby("h3")
+    stats = g.agg(
+        n_violations=("id", "size"),
+        weighted_volume=("severity", "sum"),
+        active_days=("date", "nunique"),
+        peak_violations=("is_peak", "sum"),
+        junction_share=("has_junction", "mean"),
+    )
+    stats["persistence"] = stats["active_days"] / float(total_days)
+    stats["peak_share"] = stats["peak_violations"] / stats["n_violations"]
+
+    # representative centroid for each hexagon (for map centring / scatter)
+    centroids = {c: cell_to_latlng(c) for c in stats.index}
+    stats["lat"] = [centroids[c][0] for c in stats.index]
+    stats["lon"] = [centroids[c][1] for c in stats.index]
+
+    # human-readable context
+    stats["location"] = g["location"].agg(_mode_or_blank)
+    stats["police_station"] = g["police_station"].agg(_mode_or_blank)
+    stats["junction_name"] = g["junction_name"].agg(_main_junction)
+    stats["top_violation"] = g["violations"].agg(_top_violation)
+
+    return stats.reset_index()

src/i18n.py

@@ -0,0 +1,135 @@
+"""Light i18n layer.
+
+Two jobs:
+  1. UI string translations for English / Kannada / Hindi.
+  2. Resolve a native-script (Kannada/Hindi) place query to the English place
+     names in the data, via transliteration + fuzzy matching.
+
+NOTE: the Kannada/Hindi UI strings are standard civic terms but should be
+sanity-checked by a native speaker before the finale.
+"""
+import re
+import difflib
+import unicodedata
+
+from indic_transliteration import sanscript
+from indic_transliteration.sanscript import transliterate
+
+# label -> code, and code -> Web Speech API locale
+LANGS = {"English": "en", "ಕನ್ನಡ": "kn", "हिन्दी": "hi"}
+SPEECH_LANG = {"en": "en-IN", "kn": "kn-IN", "hi": "hi-IN"}
+
+STRINGS = {
+    "title": {
+        "en": "ParkSight — Parking-Induced Congestion Intelligence",
+        "kn": "ಪಾರ್ಕ್‌ಸೈಟ್ — ಪಾರ್ಕಿಂಗ್ ದಟ್ಟಣೆ ವಿಶ್ಲೇಷಣೆ",
+        "hi": "पार्कसाइट — पार्किंग जनित भीड़ विश्लेषण"},
+    "kpi_violations": {"en": "Parking violations", "kn": "ಪಾರ್ಕಿಂಗ್ ಉಲ್ಲಂಘನೆಗಳು",
+                       "hi": "पार्किंग उल्लंघन"},
+    "kpi_zones": {"en": "Impact zones", "kn": "ಪ್ರಭಾವ ವಲಯಗಳು", "hi": "प्रभाव क्षेत्र"},
+    "kpi_high": {"en": "High-impact (CII ≥ 70)", "kn": "ಹೆಚ್ಚು-ಪ್ರಭಾವ (CII ≥ 70)",
+                 "hi": "उच्च-प्रभाव (CII ≥ 70)"},
+    "kpi_mae": {"en": "Forecast MAE", "kn": "ಮುನ್ಸೂಚನೆ MAE", "hi": "पूर्वानुमान MAE"},
+    "voice_nav": {"en": "Voice / command navigation", "kn": "ಧ್ವನಿ / ಆದೇಶ ಸಂಚಲನೆ",
+                  "hi": "वॉइस / कमांड नेविगेशन"},
+    "ask": {"en": "Ask in plain language", "kn": "ಕನ್ನಡದಲ್ಲಿ ಹುಡುಕಿ", "hi": "हिंदी में खोजें"},
+    "placeholder": {"en": "e.g. 'show worst zones in Shivaji Nagar'  ·  'read top 5'",
+                    "kn": "ಉದಾ: 'ಶಿವಾಜಿನಗರದ ಕೆಟ್ಟ ವಲಯಗಳು'",
+                    "hi": "उदा: 'शिवाजी नगर के सबसे खराब क्षेत्र'"},
+    "speak": {"en": "🎤 Speak", "kn": "🎤 ಮಾತನಾಡಿ", "hi": "🎤 बोलें"},
+    "stop": {"en": "⏹ Stop", "kn": "⏹ ನಿಲ್ಲಿಸಿ", "hi": "⏹ रोकें"},
+    "understood": {"en": "Understood", "kn": "ಅರ್ಥವಾಯಿತು", "hi": "समझ गया"},
+    "tab_map": {"en": "🗺️  Impact map", "kn": "🗺️  ಪ್ರಭಾವ ನಕ್ಷೆ", "hi": "🗺️  प्रभाव नक्शा"},
+    "tab_ops": {"en": "🚨  Live alerts", "kn": "🚨  ಲೈವ್ ಎಚ್ಚರಿಕೆ", "hi": "🚨  लाइव अलर्ट"},
+    "tab_rank": {"en": "📋  Enforcement priorities", "kn": "📋  ಜಾರಿ ಆದ್ಯತೆಗಳು",
+                 "hi": "📋  प्रवर्तन प्राथमिकताएँ"},
+    "tab_off": {"en": "🚨  Repeat offenders", "kn": "🚨  ಪುನರಾವರ್ತಿತ ಅಪರಾಧಿಗಳು",
+                "hi": "🚨  बार-बार उल्लंघनकर्ता"},
+    "tab_fc": {"en": "🔮  Tomorrow's forecast", "kn": "🔮  ನಾಳಿನ ಮುನ್ಸೂಚನೆ",
+               "hi": "🔮  कल का पूर्वानुमान"},
+    "min_cii": {"en": "Minimum CII to display", "kn": "ಪ್ರದರ್ಶಿಸಲು ಕನಿಷ್ಠ CII",
+                "hi": "दिखाने हेतु न्यूनतम CII"},
+    "top_n_zones": {"en": "Show top N zones", "kn": "ಮೇಲಿನ N ವಲಯಗಳನ್ನು ತೋರಿಸಿ",
+                    "hi": "शीर्ष N क्षेत्र दिखाएँ"},
+    "dl_priorities": {"en": "⬇️  Download enforcement priorities (CSV)",
+                      "kn": "⬇️  ಜಾರಿ ಆದ್ಯತೆಗಳನ್ನು ಡೌನ್‌ಲೋಡ್ ಮಾಡಿ (CSV)",
+                      "hi": "⬇️  प्रवर्तन प्राथमिकताएँ डाउनलोड करें (CSV)"},
+    "repeat_offenders": {"en": "Repeat offenders", "kn": "ಪುನರಾವರ್ತಿತ ಅಪರಾಧಿಗಳು",
+                         "hi": "बार-बार उल्लंघनकर्ता"},
+    "share_violations": {"en": "Share of all violations", "kn": "ಎಲ್ಲಾ ಉಲ್ಲಂಘನೆಗಳ ಪಾಲು",
+                         "hi": "कुल उल्लंघनों में हिस्सा"},
+    "worst_vehicle": {"en": "Worst single vehicle", "kn": "ಅತಿ ಕೆಟ್ಟ ಏಕೈಕ ವಾಹನ",
+                      "hi": "सबसे खराब एकल वाहन"},
+    "search_vehicle": {"en": "Search a vehicle ID or area",
+                       "kn": "ವಾಹನ ID ಅಥವಾ ಪ್ರದೇಶ ಹುಡುಕಿ", "hi": "वाहन ID या क्षेत्र खोजें"},
+    "top_n_off": {"en": "Show top N offenders", "kn": "ಮೇಲಿನ N ಅಪರಾಧಿಗಳನ್ನು ತೋರಿಸಿ",
+                  "hi": "शीर्ष N उल्लंघनकर्ता दिखाएँ"},
+    "dl_offenders": {"en": "⬇️  Download offender watchlist (CSV)",
+                     "kn": "⬇️  ಅಪರಾಧಿಗಳ ಪಟ್ಟಿ ಡೌನ್‌ಲೋಡ್ ಮಾಡಿ (CSV)",
+                     "hi": "⬇️  उल्लंघनकर्ता सूची डाउनलोड करें (CSV)"},
+    "language": {"en": "Language", "kn": "ಭಾಷೆ", "hi": "भाषा"},
+    "theme": {"en": "Theme", "kn": "ಥೀಮ್", "hi": "थीम"},
+    "dark": {"en": "🌙 Dark", "kn": "🌙 ಕಪ್ಪು", "hi": "🌙 डार्क"},
+    "light": {"en": "☀️ Light", "kn": "☀️ ಬೆಳಕು", "hi": "☀️ लाइट"},
+    "history": {"en": "🕘 Your searches this session", "kn": "🕘 ಈ ಅವಧಿಯ ಹುಡುಕಾಟಗಳು",
+                "hi": "🕘 इस सत्र की खोजें"},
+    "clear_history": {"en": "Clear history", "kn": "ಇತಿಹಾಸ ಅಳಿಸಿ", "hi": "इतिहास साफ़ करें"},
+    "no_history": {"en": "No searches yet.", "kn": "ಇನ್ನೂ ಹುಡುಕಾಟಗಳಿಲ್ಲ.",
+                   "hi": "अभी तक कोई खोज नहीं।"},
+    "tab_trends": {"en": "📈  Trends", "kn": "📈  ಪ್ರವೃತ್ತಿಗಳು", "hi": "📈  रुझान"},
+    "t_daily": {"en": "Daily violations", "kn": "ದೈನಂದಿನ ಉಲ್ಲಂಘನೆಗಳು", "hi": "दैनिक उल्लंघन"},
+    "t_hourly": {"en": "By hour of day", "kn": "ಗಂಟೆಯ ಪ್ರಕಾರ", "hi": "घंटे के अनुसार"},
+    "t_vehicle": {"en": "By vehicle type", "kn": "ವಾಹನ ಪ್ರಕಾರ", "hi": "वाहन प्रकार के अनुसार"},
+    "t_vtype": {"en": "By violation type", "kn": "ಉಲ್ಲಂಘನೆ ಪ್ರಕಾರ", "hi": "उल्लंघन प्रकार के अनुसार"},
+    "t_dow": {"en": "By day of week", "kn": "ವಾರದ ದಿನದ ಪ್ರಕಾರ", "hi": "सप्ताह के दिन अनुसार"},
+    "t_gauge": {"en": "Top-100 zones · share of all violations",
+                "kn": "ಮೇಲಿನ 100 ವಲಯಗಳ ಪಾಲು", "hi": "शीर्ष 100 क्षेत्रों का हिस्सा"},
+    "live_replay": {"en": "▶ Live replay (simulated from historical data)",
+                    "kn": "▶ ಲೈವ್ ರಿಪ್ಲೇ (ಐತಿಹಾಸಿಕ ದತ್ತಾಂಶದಿಂದ)",
+                    "hi": "▶ लाइव रीप्ले (ऐतिहासिक डेटा से)"},
+}
+
+
+def t(key, lang):
+    """Translate a UI string key into the chosen language (falls back to English)."""
+    return STRINGS.get(key, {}).get(lang) or STRINGS.get(key, {}).get("en", key)
+
+
+def _norm(s):
+    s = unicodedata.normalize("NFKD", s).encode("ascii", "ignore").decode()
+    s = re.sub(r"[^a-z]", "", s.lower())
+    s = re.sub(r"([a-z])\1+", r"\1", s)          # collapse doubled letters
+    return s.replace("nagara", "nagar")
+
+
+def romanize(text, lang):
+    scr = {"kn": sanscript.KANNADA, "hi": sanscript.DEVANAGARI}.get(lang)
+    if scr is None:
+        return text
+    try:
+        return transliterate(text, scr, sanscript.IAST)
+    except Exception:
+        return text
+
+
+def build_area_vocab(hot):
+    """Distinct locality names from the hotspot location strings."""
+    areas = set()
+    for loc in hot["location"].dropna():
+        for p in [x.strip() for x in str(loc).split(",")][1:4]:
+            pl = p.lower()
+            if p and "bengaluru" not in pl and "karnataka" not in pl and "pin" not in pl:
+                areas.add(p)
+    return sorted(areas)
+
+
+def resolve_area(query, lang, area_vocab):
+    """Map a (possibly Kannada/Hindi) place query to an English locality name."""
+    has_native = any(ord(c) > 127 for c in query)
+    rom = romanize(query, lang) if (has_native or lang != "en") else query
+    key = _norm(rom)
+    if not key:
+        return None
+    norm_map = {_norm(a): a for a in area_vocab}
+    best = difflib.get_close_matches(key, list(norm_map.keys()), n=1, cutoff=0.55)
+    return norm_map[best[0]] if best else None

src/impact_index.py

@@ -0,0 +1,37 @@
+"""Compute the Congestion Impact Index (CII) per hotspot cell.
+
+CII is a transparent, rank-normalised blend of four ideas:
+  - severity-weighted VOLUME   (how much weighted illegal parking happens here)
+  - PERSISTENCE                (chronic every-day spot vs one-off spike)
+  - PEAK-hour concentration    (bad exactly when the road is busiest)
+  - junction proximity         (blocking near junctions cascades downstream)
+
+It is explicitly a *proxy* for traffic-flow impact, derived only from
+enforcement data, with every weight exposed in config.py.
+"""
+from src import config
+
+
+def _norm(series):
+    """Rank-based normalisation to [0, 1] (robust to heavy-tailed counts)."""
+    return series.rank(method="average", pct=True).fillna(0.0)
+
+
+def add_cii(stats):
+    stats = stats.copy()
+    w = config.CII_WEIGHTS
+
+    v = _norm(stats["weighted_volume"])
+    p = _norm(stats["persistence"])
+    k = _norm(stats["peak_share"])
+
+    base = w["volume"] * v + w["persistence"] * p + w["peak"] * k
+    junction = stats["junction_share"].clip(0, 1)
+    cii = base * (1 + config.CII_JUNCTION_ALPHA * junction)
+
+    # scale to a friendly 0-100
+    cii = (cii - cii.min()) / (cii.max() - cii.min() + 1e-9) * 100
+    stats["cii"] = cii.round(1)
+    stats["cii_rank"] = stats["cii"].rank(ascending=False, method="min").astype(int)
+
+    return stats.sort_values("cii", ascending=False).reset_index(drop=True)

src/model.py

@@ -0,0 +1,111 @@
+"""LightGBM model: forecast next-day severity-weighted violation intensity
+per hotspot cell. Turns the project from descriptive ("where it's bad now")
+into predictive ("where it will be bad tomorrow").
+"""
+import numpy as np
+import pandas as pd
+import lightgbm as lgb
+
+from src import config
+
+FEATURES = (
+    ["lat", "lon", "junction", "dow", "month", "day", "is_weekend"]
+    + [f"lag_{L}" for L in config.LAGS]
+    + [f"roll_mean_{W}" for W in config.ROLL_WINDOWS]
+    + [f"roll_max_{W}" for W in config.ROLL_WINDOWS]
+)
+
+
+def build_panel(df):
+    """Build a (cell x day) panel of weighted-violation intensity with lags."""
+    counts = df.groupby("h3")["id"].size()
+    keep_cells = counts[counts >= config.MIN_CELL_VIOLATIONS].index
+    d = df[df["h3"].isin(keep_cells)].copy()
+
+    daily = (d.groupby(["h3", "date"])
+               .agg(y=("severity", "sum"), n=("id", "size"))
+               .reset_index())
+    daily["date"] = pd.to_datetime(daily["date"])
+
+    # complete the grid so quiet days become explicit zeros
+    all_dates = pd.date_range(daily["date"].min(), daily["date"].max(), freq="D")
+    idx = pd.MultiIndex.from_product([keep_cells, all_dates], names=["h3", "date"])
+    panel = daily.set_index(["h3", "date"]).reindex(idx).reset_index()
+    panel["y"] = panel["y"].fillna(0.0)
+    panel["n"] = panel["n"].fillna(0.0)
+
+    # cell-static features
+    cell_meta = (d.groupby("h3")
+                   .agg(lat=("latitude", "mean"),
+                        lon=("longitude", "mean"),
+                        junction=("has_junction", "mean"))
+                   .reset_index())
+    panel = panel.merge(cell_meta, on="h3", how="left")
+
+    # calendar features
+    panel["dow"] = panel["date"].dt.dayofweek
+    panel["month"] = panel["date"].dt.month
+    panel["day"] = panel["date"].dt.day
+    panel["is_weekend"] = (panel["dow"] >= 5).astype(int)
+
+    # lag & rolling features, strictly per cell and time-ordered
+    panel = panel.sort_values(["h3", "date"]).reset_index(drop=True)
+    for L in config.LAGS:
+        panel[f"lag_{L}"] = panel.groupby("h3")["y"].shift(L)
+    panel["_yshift"] = panel.groupby("h3")["y"].shift(1)
+    for W in config.ROLL_WINDOWS:
+        panel[f"roll_mean_{W}"] = (panel.groupby("h3")["_yshift"]
+                                   .rolling(W, min_periods=1).mean()
+                                   .reset_index(level=0, drop=True))
+        panel[f"roll_max_{W}"] = (panel.groupby("h3")["_yshift"]
+                                  .rolling(W, min_periods=1).max()
+                                  .reset_index(level=0, drop=True))
+    panel = panel.drop(columns="_yshift")
+    return panel, keep_cells, all_dates
+
+
+def train_and_forecast(df):
+    panel, keep_cells, all_dates = build_panel(df)
+    model_df = panel.dropna(subset=[f"lag_{max(config.LAGS)}"]).copy()
+
+    cutoff = all_dates.max() - pd.Timedelta(days=config.VALID_DAYS)
+    train = model_df[model_df["date"] <= cutoff]
+    valid = model_df[model_df["date"] > cutoff]
+
+    # objective=regression_l1 (MAE) matches the metric and is far better on the
+    # right-skewed daily counts than L2 (which chases rare high-count days).
+    params = dict(objective="regression_l1", metric="mae",
+                  learning_rate=0.05, num_leaves=63, min_data_in_leaf=50,
+                  feature_fraction=0.8, bagging_fraction=0.8, bagging_freq=1,
+                  seed=config.RANDOM_STATE, verbose=-1)
+    dtrain = lgb.Dataset(train[FEATURES], train["y"])
+    dvalid = lgb.Dataset(valid[FEATURES], valid["y"], reference=dtrain)
+    model = lgb.train(params, dtrain, num_boost_round=800,
+                      valid_sets=[dvalid],
+                      callbacks=[lgb.early_stopping(60), lgb.log_evaluation(0)])
+
+    # --- validation metrics vs a naive "same as last week" baseline ---
+    pred_v = model.predict(valid[FEATURES], num_iteration=model.best_iteration)
+    yv = valid["y"].values
+    mae = float(np.mean(np.abs(pred_v - yv)))
+    rmse = float(np.sqrt(np.mean((pred_v - yv) ** 2)))
+    base_mae = float(np.mean(np.abs(valid["lag_7"].values - yv)))
+
+    # --- next-day forecast: most recent row per cell ---
+    last_rows = model_df.sort_values("date").groupby("h3").tail(1).copy()
+    fc = model.predict(last_rows[FEATURES], num_iteration=model.best_iteration)
+    forecast = last_rows[["h3", "lat", "lon"]].copy()
+    forecast["pred_intensity"] = np.clip(fc, 0, None).round(2)
+    forecast["forecast_for"] = (all_dates.max() + pd.Timedelta(days=1)).date().isoformat()
+    forecast = forecast.sort_values("pred_intensity", ascending=False).reset_index(drop=True)
+    forecast["risk_rank"] = forecast.index + 1
+
+    metrics = dict(
+        valid_mae=round(mae, 3),
+        valid_rmse=round(rmse, 3),
+        baseline_lag7_mae=round(base_mae, 3),
+        improvement_pct=round(100 * (base_mae - mae) / base_mae, 1) if base_mae else None,
+        n_modeled_cells=int(len(keep_cells)),
+        best_iteration=int(model.best_iteration),
+    )
+    return model, forecast, metrics

src/offenders.py

@@ -0,0 +1,53 @@
+"""Repeat-offender intelligence from the (anonymised) `vehicle_number` column.
+
+This is the honest, data-grounded reframe of "license plate recognition": the
+plate is already present in the records, so instead of OCR-from-images we surface
+*chronic* offenders across time and space — something a single-snapshot CV
+pipeline structurally cannot do. All IDs are anonymised, so this is privacy-safe.
+"""
+import pandas as pd
+
+
+def _clean_plates(df):
+    v = df.dropna(subset=["vehicle_number"]).copy()
+    v = v[~v["vehicle_number"].astype(str).str.lower().isin(["nan", "none", ""])]
+    return v
+
+
+def _mode(series):
+    s = series.dropna()
+    return s.mode().iat[0] if not s.empty else ""
+
+
+def build_offender_stats(df, top_n=500):
+    """Top repeat offenders with where/what/when context."""
+    v = _clean_plates(df)
+    g = v.groupby("vehicle_number")
+    stats = g.agg(
+        n_violations=("id", "size"),
+        weighted_severity=("severity", "sum"),
+        n_zones=("h3", "nunique"),
+        vehicle_type=("vehicle_type", _mode),
+        top_location=("location", _mode),
+        first_seen=("ts", "min"),
+        last_seen=("ts", "max"),
+    ).reset_index()
+    stats["first_seen"] = stats["first_seen"].dt.date.astype(str)
+    stats["last_seen"] = stats["last_seen"].dt.date.astype(str)
+    stats["weighted_severity"] = stats["weighted_severity"].round(1)
+    stats = stats.sort_values("n_violations", ascending=False).reset_index(drop=True)
+    stats["rank"] = stats.index + 1
+    return stats.head(top_n)
+
+
+def offender_summary(df):
+    """Headline KPIs about repeat offending."""
+    v = _clean_plates(df)
+    counts = v["vehicle_number"].value_counts()
+    repeat = counts[counts >= 2]
+    return dict(
+        distinct_vehicles=int(counts.size),
+        repeat_offenders=int(repeat.size),
+        repeat_share_pct=round(100 * repeat.sum() / len(v), 1),
+        worst_count=int(counts.max()),
+    )

src/streamlit_app.py

@@ -0,0 +1,40 @@
+import altair as alt
+import numpy as np
+import pandas as pd
+import streamlit as st
+
+"""
+# Welcome to Streamlit!
+
+Edit `/streamlit_app.py` to customize this app to your heart's desire :heart:.
+If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
+forums](https://discuss.streamlit.io).
+
+In the meantime, below is an example of what you can do with just a few lines of code:
+"""
+
+num_points = st.slider("Number of points in spiral", 1, 10000, 1100)
+num_turns = st.slider("Number of turns in spiral", 1, 300, 31)
+
+indices = np.linspace(0, 1, num_points)
+theta = 2 * np.pi * num_turns * indices
+radius = indices
+
+x = radius * np.cos(theta)
+y = radius * np.sin(theta)
+
+df = pd.DataFrame({
+    "x": x,
+    "y": y,
+    "idx": indices,
+    "rand": np.random.randn(num_points),
+})
+
+st.altair_chart(alt.Chart(df, height=700, width=700)
+    .mark_point(filled=True)
+    .encode(
+        x=alt.X("x", axis=None),
+        y=alt.Y("y", axis=None),
+        color=alt.Color("idx", legend=None, scale=alt.Scale()),
+        size=alt.Size("rand", legend=None, scale=alt.Scale(range=[1, 150])),
+    ))

src/trends.py

@@ -0,0 +1,64 @@
+"""Precompute small aggregates for the dashboard charts.
+
+Long format -> one tiny trends.parquet the app loads for line/bar/donut charts:
+  kind   ∈ {daily, hourly, vehicle, dow, vtype}
+  label  the x-axis label
+  value  the count
+  order  sort key
+"""
+from collections import Counter
+
+import pandas as pd
+
+from src import config
+
+DOW = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+
+def build_trends(df):
+    rows = []
+
+    # daily time series (for the line chart)
+    daily = df.groupby("date").size().reset_index(name="value").sort_values("date")
+    for i, (d, v) in enumerate(zip(daily["date"], daily["value"])):
+        rows.append(("daily", str(d), int(v), i))
+
+    # hourly profile (bar)
+    hourly = df.groupby("hour").size()
+    for h in range(24):
+        rows.append(("hourly", f"{h:02d}", int(hourly.get(h, 0)), h))
+
+    # by vehicle type (top 10 bar)
+    for i, (k, v) in enumerate(df["vehicle_type"].value_counts().head(10).items()):
+        rows.append(("vehicle", str(k), int(v), i))
+
+    # by day-of-week (bar)
+    dow = df.groupby("dow").size()
+    for i in range(7):
+        rows.append(("dow", DOW[i], int(dow.get(i, 0)), i))
+
+    # by violation type (donut) — only parking-relevant labels
+    vt = Counter()
+    for lst in df["violations"]:
+        for v in lst:
+            if v in config.PARKING_SEVERITY:
+                vt[v] += 1
+    for i, (k, c) in enumerate(vt.most_common(8)):
+        rows.append(("vtype", str(k).title(), int(c), i))
+
+    return pd.DataFrame(rows, columns=["kind", "label", "value", "order"])
+
+
+def build_byday(df):
+    """Per-day aggregates so charts can animate cumulatively during replay.
+
+    Long format: date, dim ∈ {hour, vehicle}, key, value.
+    """
+    rows = []
+    h = df.groupby(["date", "hour"]).size().reset_index(name="value")
+    for _, r in h.iterrows():
+        rows.append((str(r["date"]), "hour", f'{int(r["hour"]):02d}', int(r["value"])))
+    v = df.groupby(["date", "vehicle_type"]).size().reset_index(name="value")
+    for _, r in v.iterrows():
+        rows.append((str(r["date"]), "vehicle", str(r["vehicle_type"]), int(r["value"])))
+    return pd.DataFrame(rows, columns=["date", "dim", "key", "value"])