JanMitra AI — Intelligent Welfare & Ration Assistant

An AI-powered citizen assistant for India's Public Distribution System (PDS/ration) and social welfare schemes — built for the Litmus Internship problem statement. Not a simple chatbot: a full dashboard product with a grounded RAG assistant, scheme matching, document checklists, grievance guidance, and an admin analytics console.

Scope note: this repository is a working, extensible MVP of the full spec — real backend, real RAG pipeline, real UI, sample data, Docker, and diagrams — built to be run and demoed today, and deepened from here (see "What's next").

---

1. What's actually implemented

Area	Status
FastAPI backend, JWT auth, SQLite models (Users, Schemes, Documents, FAQs, ChatHistory, Feedback, Analytics)	✅ Working
RAG pipeline: chunking → embeddings (sentence-transformers) → ChromaDB → retrieval	✅ Working
LLM integration (Gemini / OpenAI) with a retrieval-only fallback so the app never hard-fails with no API key	✅ Working
Confidence scoring + source citation on every AI answer	✅ Working
Smart Scheme Finder with explainable rule-based matching	✅ Working
Document checklist generator + PDF export	✅ Working
Ration process explainer (new card, duplicate, address update, add/delete member, migration/ONORC)	✅ Working
Grievance assistant (department routing + escalation path)	✅ Working
Admin analytics (usage, confidence distribution, top questions, low-confidence/missing-knowledge report)	✅ Working
Document upload → auto chunk + embed into the knowledge base	✅ Working
Next.js + Tailwind + Framer Motion UI: landing, dashboard, scheme finder, chat, checklist, grievance, admin	✅ Working
Dark/light mode, glassmorphism, animated citizen-journey timeline	✅ Working
Docker Compose for backend + frontend	✅ Working
Sample datasets (7 schemes, 10 FAQs incl. Hindi)	✅ Working
Multilingual (English / Hindi)	✅ Partial — prompt + fallback support Hindi; full Hinglish detection is a next step
Voice assistant (STT/TTS)	🔜 Not yet implemented — see roadmap
Full production auth flows (refresh tokens, RBAC UI)	🔜 Simplified for MVP

---

2. Architecture

See docs/architecture.md for the full system diagram, ER diagram, sequence diagram, data-pipeline flow diagram, and the reasoning behind each major technical decision.

Stack: Next.js 14 (App Router) + Tailwind + Framer Motion · FastAPI · SQLite (SQLAlchemy) · ChromaDB · sentence-transformers · LangChain-style RAG (hand-rolled retriever for transparency) · JWT auth · Docker.

---

3. Running it

Option A — Docker Compose (recommended)

cp backend/.env.example backend/.env   # optionally add GEMINI_API_KEY or OPENAI_API_KEY
docker compose up --build

• Frontend: http://localhost:3000
• Backend docs (OpenAPI/Swagger): http://localhost:8000/docs

Option B — Run locally

Backend

cd backend
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python -m app.seed        # creates DB, admin user, loads sample data, builds embeddings
uvicorn app.main:app --reload

Default admin login: admin@janmitra.gov.in / Admin@123

Frontend

cd frontend
npm install
npm run dev

---

4. API surface

/auth /chat /schemes /checklist /ration /grievance /upload /admin /analytics

Full interactive documentation is auto-generated by FastAPI at /docs once the backend is running — this is the fastest way to explore every endpoint and try requests live.

---

5. Responsible AI mechanisms (not just a slide)

1. Confidence gating — below MIN_CONFIDENCE_TO_ANSWER (default 0.35), the system returns a retrieval-only summary instead of letting an LLM improvise.
2. Mandatory source citation — every chat response includes the source title/snippet/score it was grounded in.
3. No eligibility claims — the system prompt (app/rag/prompts.py) explicitly forbids confirming eligibility; the UI disclaimer reinforces this on every answer.
4. Admin visibility into gaps — /admin/missing-knowledge surfaces low-confidence queries so real content gaps get filled, rather than papered over by the LLM.

---

6. Project structure

JanMitra-AI/
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI entrypoint
│   │   ├── config.py / database.py / models.py / schemas.py / auth.py
│   │   ├── seed.py            # DB + vector store bootstrap
│   │   ├── routers/           # auth, chat, schemes, checklist, ration, grievance, upload, admin, analytics
│   │   └── rag/                # retriever.py, ingest.py, prompts.py, llm_client.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── app/                   # landing, dashboard, schemes, chat, checklist, grievance, admin
│   ├── components/            # Navbar, SchemeCard, ChatWidget, ConfidenceMeter
│   ├── lib/api.ts
│   └── Dockerfile
├── data/
│   ├── raw/ (source notes)
│   ├── prepared/ (schemes.json, faqs.json)
│   └── metadata/ (ingest_report.json, generated at seed time)
├── database/schema.sql
├── docs/architecture.md       # architecture, ER, sequence, flow diagrams
└── docker-compose.yml

---

7. What's next (roadmap to the full spec)

• Voice assistant: browser Web Speech API on the frontend + a /voice STT/TTS bridge endpoint on the backend.
• Hinglish-aware language detection before routing to the prompt template.
• Real PDF ingestion in /upload (currently accepts .txt; swap in pypdf extraction — the chunking/embedding path is already generic).
• Admin document management UI (list/delete/re-index) on top of the existing /upload/documents endpoint.
• Hallucination-checker pass: a second LLM call that verifies the generated answer's claims are entailed by the retrieved chunks before returning it.
• Migrate SQLite → Postgres + Alembic migrations for a real deployment.