🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

KAVAL answering a jurisdiction-clamped question with context chips, provenance, and an audit hash

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

🛡️ KAVAL _{ಕಾವಲು}

Intelligent Conversational AI for the Karnataka State Police Crime Database

Every police officer in Karnataka gets a crime analyst in their pocket — one that speaks Kannada, shows its work, and never invents a number.

KSP Datathon 2026 — Challenge 01 · Full PRD · W1 Spike

Running against an empty database: a jurisdiction-clamped answer with context chips, compiled-SQL provenance, and a tamper-evident audit hash — every app feature works before a single crime record is ingested.

Why KAVAL is different


🔒 Numeric Firewall	The LLM architecturally cannot state a statistic that didn't come from an executed query. On the common path the model emits a validated JSON `FilterSpec` — our code writes the SQL. Hallucinated numbers are impossible by construction, not by prompting.
🗺️ Generative Analytics Canvas	Answers materialize as live, interactive widgets — hotspot maps, criminal-network graphs, trend charts — inline in the chat, not text walls.
📜 Court-ready provenance	Every answer carries its SQL, source tables, row counts, officer identity, and a tamper-evident hash-chained audit trail. PDF exports are case-file annexures, not chat logs.
🗣️ Kannada-first, voice-enabled	Ask in English, Kannada, or code-switched Kanglish — by voice or text — and get answers back the same way.
🌅 Morning Brief	KAVAL speaks first: an auto-generated daily situational brief per station/district with anomalies and early warnings.
⚖️ IPC ↔ BNS bridge	Seamless querying across the 2024 IPC → Bharatiya Nyaya Sanhita transition — built into the data model.
📜 BSA §63 certificates	PDF exports ship with an auto-generated court-admissibility certificate under §63, Bharatiya Sakshya Adhiniyam 2023 (successor to IEA §65B).
🔌 Sovereign Mode	One toggle swaps the cloud LLM for an on-prem model — fully functional air-gapped. Crime data never has to leave the building.
📈 Measured, not claimed	A published failure-mode page, live accuracy scoreboard, and a timestamped eval history showing the accuracy growth curve.
🔬 Evidence-backed analytics	Crime-concentration views, near-repeat radar, aoristic time-of-day analysis, repeat-victim flags — each module grounded in replicated criminology research.

Architecture (PRD §8 / §11)

question (en/kn, voice/text)
│
▼
Planner (LLM) ──► FilterSpec JSON ──► deterministic SQL compiler ◄── 80% path
│ (Pydantic-validated — the LLM never writes SQL here)
└─ long tail ──► guarded text-to-SQL (sqlglot AST gate: SELECT-only,
table allowlist, single statement) ◄── 20% path
▼
Executor (read-only, row-capped) ──► Postgres 16 + PostGIS + pgvector
▼
Narrative w/ injected values (Numeric Firewall) + Widget DSL
▼
Provenance + hash-chained audit event ──► React canvas

Quickstart

Option A — everything in Docker

copy .env.example .env # add ANTHROPIC_API_KEY for the LLM planner
docker compose up --build

→ web http://localhost:5173 · API docs http://localhost:8000/docs

Option B — local, zero Docker (SQLite)

# backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload # http://localhost:8000# frontend (new terminal)
cd frontend
npm install
npm run dev # http://localhost:5173

No API key? It still works — an offline rule-based planner handles the demo phrasings (English and Kannada) so the full pipeline runs keyless. With ANTHROPIC_API_KEY set, the real LLM planner takes over.

No dataset? Also fine — the app boots against an empty database: all tables self-create and demo users auto-seed on startup. This repo ships no crime data, real or synthetic — ingestion adapters get written only after we see the organizer's actual data format (see data/README.md).

Deployment (submission target)

Deployment via Zoho Catalyst is mandatory for all datathon submissions (confirmed 11 Jun). Target: AppSail custom OCI runtime for this repo's Docker API image, Web Client Hosting for the frontend — full service-by-service mapping in PRD §11.5. Local compose stays as the dev environment and the air-gapped Sovereign-Mode build.

Demo logins (password: `kaval123`)

User	Role	Scope
`constable_blr`	CONSTABLE	Bengaluru City only (queries auto-clamped; cross-district asks refused + logged)
`io_mysuru`	INVESTIGATOR	Mysuru only
`sp_command`	COMMAND	State-wide + Audit Trail
`auditor`	ADMIN	Audit Trail only — no case data (separation of duties)

Run the W1 spike (Gate G1)

python spike/run_spike.py --offline # deterministic path — must be 12/12 (no data or key needed)
python spike/run_spike.py # LLM planner vs golden set

Tests

cd backend
pytest tests -q

Real dataset (when the organizers release it)

Drop the files into data/raw/ — that directory is gitignored on purpose; real crime data never goes to GitHub (see data/README.md). Then profile it before writing any ingestion code:

cd backend
python scripts/profile_dataset.py ..\data\raw\*# -> data/profile_report.md: rows, nulls, date spans, geo/key candidates per file

The ingestion adapter (real columns → app/schema.py) is written after profiling — we don't guess the format before seeing it.

Repo map

PRD.md ← the contract: features, milestones, demo script
backend/
app/
engine/ ← the crown jewel: FilterSpec → compiler → guarded SQL
routers/ ← auth · chat · meta · audit · export (PDF)
audit.py ← tamper-evident hash chain
auth.py ← JWT + bcrypt + 4-role RBAC
pdf.py ← court-ready export w/ §63 certificate
schema.py ← canonical data model (app + crime tables)
scripts/profile_dataset.py ← Day-1 profiler for the real dataset
tests/ ← compiler + SQL-guard + API tests (executed, not string-matched)
spike/ ← W1 NL→SQL de-risking harness + golden set
frontend/ ← React 18 + TS + Tailwind v4 command-center UI
db/ ← PostGIS + pgvector image, init SQL
data/ ← gitignored landing zone for the real dataset (local only)

Roadmap (PRD §12)

W1 — scaffold, spike harness, golden set v0, dataset profiler
W1.5 — dataset-independent architecture complete: JWT auth + 4-role RBAC with jurisdiction clamping, server-side sessions + context memory (filter chips), tamper-evident audit viewer with live chain verification, PDF export with §63-style certificate, voice input (en/kn), Sovereign-Mode planner switch, rate limiting, degraded-mode banner
W1 — Gate G1: LLM spike ≥70% · ✅ Catalyst decision answered 11 Jun: deployment via Catalyst is mandatory — target AppSail (custom OCI/Docker) for the API, Slate/Web Client Hosting for the frontend
W2 — Catalyst onboarding (credits, AppSail hello-deploy, Data Store ZCQL spike → DB decision), QuickML LLM wired via LiteLLM, real dataset ingestion, semantic views
W3 — guarded-SQL path live, Widget DSL, network graph (Gate G2: ≥70%)
W4 — Kannada voice quality tier (Sarvam/Bhashini), hotspots, near-repeat
W5 — forecasts, Morning Brief, cold-start suggestions (Gate G3: ≥85%)
W6 — hardening to ≥90%, demo video, submission 24 Jul

Team

Built by Team KAVAL for the Karnataka State Police Datathon 2026 — Challenge 01: Intelligent Conversational AI for KSP Crime Database.

⚠️ This repository contains no crime data — real or synthetic. The data/ directory is gitignored by design; the organizer-provided dataset stays local-only, behind auth. No real crime records, persons, or PII are present here, ever.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
data		data
db		db
docs		docs
frontend		frontend
spike		spike
.catalystrc		.catalystrc
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
PRD.md		PRD.md
README.md		README.md
catalyst.json		catalyst.json
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

🛡️ KAVAL ಕಾವಲು

Intelligent Conversational AI for the Karnataka State Police Crime Database

Why KAVAL is different

Architecture (PRD §8 / §11)

Quickstart

Option A — everything in Docker

Option B — local, zero Docker (SQLite)

Deployment (submission target)

Demo logins (password: kaval123)

Run the W1 spike (Gate G1)

Tests

Real dataset (when the organizers release it)

Repo map

Roadmap (PRD §12)

Team

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🛡️ KAVAL ಕಾವಲು

Intelligent Conversational AI for the Karnataka State Police Crime Database

Why KAVAL is different

Architecture (PRD §8 / §11)

Quickstart

Option A — everything in Docker

Option B — local, zero Docker (SQLite)

Deployment (submission target)

Demo logins (password: kaval123)

Run the W1 spike (Gate G1)

Tests

Real dataset (when the organizers release it)

Repo map

Roadmap (PRD §12)

Team

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🛡️ KAVAL ಕಾವಲು

Intelligent Conversational AI for the Karnataka State Police Crime Database

Why KAVAL is different

Architecture (PRD §8 / §11)

Quickstart

Option A — everything in Docker

Option B — local, zero Docker (SQLite)

Deployment (submission target)

Demo logins (password: kaval123)

Run the W1 spike (Gate G1)

Tests

Real dataset (when the organizers release it)

Repo map

Roadmap (PRD §12)

Team

License

🛡️ KAVAL _{ಕಾವಲು}

Demo logins (password: `kaval123`)

🛡️ KAVAL _{ಕಾವಲು}

Demo logins (password: `kaval123`)

🛡️ KAVAL _{ಕಾವಲು}

Demo logins (password: `kaval123`)

🛡️ KAVAL _{ಕಾವಲು}

Demo logins (password: `kaval123`)

🛡️ KAVAL _{ಕಾವಲು}

Demo logins (password: `kaval123`)