🏛️ CivicPulse AI (v2.0)

An open-source multilingual civic decision intelligence layer that transforms citizen voices across Indian states into traceable, evidence-backed civic investment priorities.

Public administration systems across India process millions of fragmented citizen complaints across diverse regional scripts (Hindi, Telugu, Tamil, Marathi, Punjabi, Bengali, Kannada, Gujarati, Malayalam, Odia, Urdu, English). Traditional municipal systems process complaints in isolated silos—leading to unaddressed infrastructure bottlenecks, misallocated capital investments, and a disconnect between citizen demand signals and municipal budget allocation.

Beyond collection, there is a second critical failure: fake closures. Municipal authorities often mark grievances as "resolved" without any genuine fix, with no mechanism for the reporting citizen to verify or contest the closure. This systemic dishonesty erodes public trust in civic institutions.

CivicPulse AI is an open-source decision-support platform built as a Digital Public Good. It bridges citizen feedback and municipal public investment planning by transforming unstructured citizen signals into geographic demand intelligence, cross-referencing demographic census data, infrastructure deficit indices, and existing investment allocations to generate transparent, explainable priority scores and actionable evidence cards for decision-makers.

The Citizen-Verified Resolution Loop ensures that no grievance can be permanently closed by authorities without genuine citizen verification. This is enforced by an AI guardrail.

OPEN
  │  (staff submits resolution notes + optional photo)
  ▼
RESOLVED_PENDING_VERIFICATION
  │  (citizen clicks "Confirm Resolution")
  ├──► AI Confidence ≥ 60/100 ──► VERIFIED_CLOSED ✅
  ├──► AI Confidence < 60/100 ──► SUSPICIOUS_CLOSURE ⚠️ (citizen prompted)
  └──► (citizen clicks "Reject & Reopen") ──► REJECTED_REOPENED 🔄
           │  (staff re-submits improved evidence)
           └──► RESOLVED_PENDING_VERIFICATION (retry loop)

The closure_validation_service.py runs a two-tier validation:

1. Gemini LLM Analysis (primary): Evaluates whether the staff resolution notes genuinely address the original complaint category, contain specific action verbs (repaired, installed, replaced), and are adequately detailed. Photographic evidence provides a strong positive signal.
2. Deterministic Rule-Based Fallback (when Gemini is unavailable): Scores based on note length, keyword overlap between complaint and resolution, presence of positive action verbs, and generic phrase detection.

Confidence Score Thresholds:

CivicPulse AI ships with 5 professionally curated themes, switchable instantly from the navbar.

Implementation: CSS custom properties (--bg, --surface, --text-primary, --accent) are toggled by setting theme-{id} class on document.documentElement. This means zero React re-renders on theme switch — pure CSS propagation down the entire DOM tree.

graph TD
    A[Citizen Input / Voice / SMS / Web] --> B[React Decision Cockpit & Copilot View]
    B --> C[FastAPI REST Gateway /api/v1/copilot/chat]
    C --> D[Copilot Intelligence & Controlled Retrieval Engine]
    D --> E[Data Loader & Scoring Services]
    E -->|Grounded Context| F[Google Gemini / Fallback Provider]
    F --> G[Validated Markdown Answer + Evidence Links]
    B2[Citizen Verification UI] --> C2[POST /issues/id/verify-closure]
    C2 --> AI[closure_validation_service.py — AI Guardrail]
    AI --> SM[State Machine: VERIFIED_CLOSED / SUSPICIOUS_CLOSURE / REJECTED_REOPENED]

To ensure strict accountability in public governance, CivicPulse AI enforces a strict boundary between AI natural language processing and deterministic calculation logic:

+-------------------------------------------------------+
|            GOOGLE GEMINI AI RESPONSIBILITIES          |
|  - Regional Script & Multilingual Detection           |
|  - Text Translation & Intent Classification           |
|  - Entity & Urgency Extraction                        |
|  - Multilingual Policymaker Summaries (EN, HI, TE)    |
|  - Closure Authenticity Validation (0-100 score)      |
+-------------------------------------------------------+
                           ↓ (Structured JSON Signals)
+-------------------------------------------------------+
|          DETERMINISTIC APPLICATION CODE LOGIC         |
|  - Per-Capita Population Normalization (100k)         |
|  - 30-Day Temporal Demand Velocity Momentum           |
|  - Infrastructure Capacity Deficit Scoring            |
|  - Demographic Census Vulnerability Indexing          |
|  - Capital Investment Overlap & Duplicate Penalty     |
|  - Priority Score Calculation & Ranking (Engine V2)   |
|  - Counterfactual What-If Policy Simulations          |
|  - Grievance State Machine Transitions                |
+-------------------------------------------------------+

Every priority recommendation generated by CivicPulse AI is backed by a machine-readable 6-step evidence chain:

$$\text{Priority Score} = 0.35 \cdot S_{\text{demand}} + 0.25 \cdot I_{\text{gap}} + 0.20 \cdot V_{\text{demographic}} + 0.20 \cdot O_{\text{investment}}$$

01 CITIZEN DEMAND → 02 DEMAND MOMENTUM → 03 INFRASTRUCTURE GAP → 04 DEMOGRAPHIC NEED → 05 INVESTMENT OVERLAP → 06 PRIORITY RECOMMENDATION

Policymakers can inspect individual factor contributions and switch language briefs (EN / HI / TE) directly inside the Evidence Explorer.

For detailed documentation on specific components, see:

• Backend Documentation - API setup, models, and FastAPI architecture.
• Frontend Documentation - React UI, Vite build, and Tailwind styling.

• Python: 3.10+ (Python 3.12 recommended)
• Node.js: v18+ (Node 20/22 recommended)

cd backend
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

cd frontend
npm install
npm run dev

• Dashboard Cockpit: http://localhost:5173
• API OpenAPI Docs: http://localhost:8000/docs

CivicPulse AI is configured for dual-service production deployment on Render via the repository-native render.yaml Blueprint:

• Service 1 (Backend): civicpulse-ai-backend — Python FastAPI Web Service bound to 0.0.0.0:$PORT with health checks on /api/v1/health.
• Service 2 (Frontend): civicpulse-ai-frontend — React Static Site built via npm ci && npm run build publishing ./frontend/dist.

1. Connect your GitHub repository to Render.
2. Click New + → Blueprint and select render.yaml.
3. Configure Backend Environment Secret: GEMINI_API_KEY (stored securely in Render dashboard).
4. Set Backend ALLOWED_CORS_ORIGINS to https://<YOUR-FRONTEND-URL>.onrender.com.
5. Set Frontend VITE_API_BASE_URL to https://<YOUR-BACKEND-URL>.onrender.com.
6. Verify backend health check endpoint at /api/v1/health and open the public frontend URL.

Run the complete stack via Docker Compose:

docker compose build
docker compose up -d

• Frontend Cockpit: http://localhost:5173 (or http://localhost:80)
• Backend API: http://localhost:8000
• Health Check: http://localhost:8000/api/v1/health

Run the automated full-system verification script:

./scripts/verify_project.sh

Or run test suites individually:

• Backend Pytest Suite: cd backend && .venv/bin/pytest
• Backend Ruff Linter: cd backend && .venv/bin/ruff check .
• Frontend ESLint & Build: cd frontend && npm run lint && npx tsc --noEmit && npm run build

Distributed under the MIT License. Built as an open-source Digital Public Good for public governance. See CONTRIBUTING.md and SECURITY.md for guidelines.