KAVACH

Knowledge-based AI for Verification And Crime Handling. Intelligent Conversational AI for KSP Crime Database

Live demo: https://kavach-vert.vercel.app/ — frontend on Vercel, backend on Render.

See FIXES_README.md for a list of bugs that were found and fixed in this codebase.

Screenshots

Dashboard / quick-action home

Crime map — marker view

Crime map — heatmap view

Project structure

• client — Vite/React frontend source directory
• api_backend — self-contained backend deployment source directory
  • api_backend/server.py — FastAPI app + uvicorn entrypoint
  • api_backend/ksp_ai, api_backend/geo_intelligence — bundled copies of the chatbot/NLP and geospatial modules, used when deploying api_backend/ as a standalone directory
• ksp_ai, geo_intelligence — the same modules again, at the project root; this is where local development/tests should happen (see "Known duplication" in FIXES_README.md)
• scripts — migration and maintenance scripts
• requirements.txt — Python dependencies
• requirements-dev.txt — extra dependencies needed only to run the test suite
• api_backend/requirements.txt — same dependencies, bundled for deployment

1. Install prerequisites

Make sure you have:

• Python 3.11+ installed
• Node.js and npm installed

Install Python dependencies:

pip install -r requirements.txt
# add -r requirements-dev.txt as well if you want to run the test suite

Install frontend dependencies:

cd client
npm install

2. Run locally

Start the backend (binds to 0.0.0.0:8000 by default; set RELOAD=true for autoreload during development):

RELOAD=true python api_backend/server.py

Start the frontend:

cd client
npm run dev

The frontend will usually run on http://localhost:5173 and the backend on http://127.0.0.1:8000.

3. Build the frontend for deployment

cd client
npm run build

This produces static assets in client/dist, which can be served by any static host or CDN (e.g. behind nginx, Netlify, Vercel, S3 + CloudFront, etc).

4. Deploy the backend

api_backend/ is an ordinary FastAPI app served by uvicorn — deploy it however you'd deploy any Python web service (a container/Docker image, a VM with a process manager, a PaaS such as Render/Railway/Fly.io, etc). The entrypoint is api_backend/server.py (or server.py at the project root, which just re-exports the same app object), and it honours the PORT environment variable if your platform assigns one dynamically.

api_backend/runtime.txt pins the Python version to 3.12.7 for platforms that read it (e.g. Render). This matters because pandas==2.2.0 (pinned in requirements.txt) doesn't ship prebuilt wheels for very new Python versions — without the pin, some platforms will default to the newest available Python, pip will try to compile pandas from source, and that source build fails against newer compilers. If you deploy somewhere that doesn't read runtime.txt, set the platform's Python version setting to 3.11 or 3.12 directly instead.

Example with a plain container/VM:

pip install -r api_backend/requirements.txt
python api_backend/server.py

Or directly with uvicorn:

uvicorn api_backend.server:app --host 0.0.0.0 --port 8000

This project's own deployment: backend on Render, frontend on Vercel, live at https://kavach-vert.vercel.app/.

5. Environment variables

Set these in your hosting platform's environment/secret settings rather than hardcoding them:

• ALLOWED_ORIGINS — comma-separated list of the frontend origin(s) allowed to call the API (CORS)
• SESSION_TTL_SECONDS — how long an idle chat session is kept in memory before eviction (default 1800)
• PORT — optional; the port uvicorn binds to (defaults to 8000)
• ANTHROPIC_API_KEY — optional; enables the LLM fallback in the NLU pipeline for ambiguous phrasing (ksp_ai/nlu/llm_fallback.py). If unset, the pipeline falls back to rule-based parsing only.
• CHAT_RATE_LIMIT — optional; per-IP rate limit on /api/v1/chat/stream, in slowapi syntax (default 15/minute). Worth keeping set if ANTHROPIC_API_KEY is set, since that route is the only one that spends API credit.
• ADMIN_API_KEY — optional; if set, POST /api/geo/admin/refresh requires a matching X-Admin-Key header. If unset, that route is open to anyone who can reach it — set this before deploying anywhere the URL could be publicly reachable.

On the frontend, set VITE_API_BASE_URL (in client/.env or your build environment) to the backend's public origin so the built app knows where to send API requests.

6. Troubleshooting

• If Python imports fail, verify that dependencies are installed with pip install -r requirements.txt (and -r requirements-dev.txt if you're running tests).
• If the frontend cannot reach the backend, check VITE_API_BASE_URL in the frontend build/environment and ALLOWED_ORIGINS on the backend — they need to agree on each other's origin.
• If PDF/Excel export requests 500, double check reportlab and openpyxl are installed from requirements.txt — see FIXES_README.md.
• If chat requests start returning 429 Too Many Requests, that's the per-IP rate limit on /api/v1/chat/stream (see CHAT_RATE_LIMIT above), not an error — it's protecting the Anthropic API key from unbounded call volume.
• If /api/geo/admin/refresh returns 401, either omit ADMIN_API_KEY in your environment for local dev, or include a matching X-Admin-Key: <key> header on the request.
• If the build fails while compiling pandas from source (a wall of Cython/ninja/meson errors ending in error: metadata-generation-failed), your platform picked a newer Python version than pandas 2.2.0 has prebuilt wheels for. Pin the Python version — api_backend/runtime.txt does this for Render automatically; on other platforms, set the Python version setting to 3.11 or 3.12.