🏛️ SAHAY 2.0

Universal Civic Navigator & Crisis Assistance Engine

AI-Powered Public-Service Discovery, Deterministic Eligibility Evaluation & Real-Time Location Intelligence

Find the help you need. Know what to do next. Fast, verified, and safe.

🚀 Live Demo Application • 💻 GitHub Repository • 📚 Swagger API Docs • 🏗️ Architecture Specification

🌐 1. Live Production Deployment & Quick Links

Resource	Verified Production Link	Description
🌐 Live Web Application	sahay-cyan.vercel.app	Unified full-stack production deployment on Vercel
📚 Interactive API Docs	/api/docs	Interactive Swagger UI API documentation
📄 OpenAPI Specification	/api/openapi.json	Raw OpenAPI 3.1 JSON schema specification
❤️ API Health Check	/api/health	Live system health status endpoint (`HTTP 200 OK`)
💻 Source Code	github.com/mrashish18/sahay	Public GitHub repository

🚨 2. The Problem

Citizens seeking public assistance or emergency disaster aid face severe administrative and cognitive friction:

Fragmented Public Services: Welfare schemes and disaster helplines are scattered across hundreds of municipal, state, and national portals.
Dense Legal Jargon: Complex administrative terminology creates confusion for citizens searching in natural language (e.g. searching for "ration for my children" instead of scheme IDs).
Probabilistic Hallucination Risk: Generative AI tools often fabricate non-existent government benefits or misinterpret strict statutory eligibility criteria.
Dangerous Emergency Delays: Generic chatbots treat life-threatening flood or fire crises like routine paperwork inquiries, delaying life-saving evacuation guidance.

💡 3. The SAHAY Solution

SAHAY 2.0 is an AI-powered public-service decision-support engine designed to connect citizens to verified government benefits, code-evaluated eligibility, actionable document checklists, and safety-first crisis routing.

💡 Core Design Philosophy: Natural language interprets citizen context; deterministic Python code evaluates legal eligibility; safety-first crisis routing intercepts emergency distress above administrative paperwork.

✨ 4. Key Capabilities

🥫 Public Service Discovery: Matches conversational queries in English, Hindi, or Hinglish to official government welfare schemes with required document checklists and verified portal links.
⚖️ Deterministic Eligibility Evaluation: Executes statutory qualification criteria in Python code outside probabilistic language model text generation.
🚨 First-Class Crisis Routing: Unconditionally prioritizes physical safety guidance, evacuation protocols, and emergency helplines during disasters.
🌦️ Universal Location Intelligence: Resolves misspellings, historical aliases, abbreviations, and global locations for real-time weather and civic forecasts.
🌐 Jurisdiction Isolation: Enforces strict containment between Indian (IN) and US (US) welfare databases.
🔐 Sandboxed Tool Execution (TTE): Protects tool proposals through AST static analysis (ast.parse) safety controls.

📸 5. Product Showcase

🏠 Civic Assistance & Public Trust

Natural-language public-service discovery paired with verified source traceability & legal disclaimers

🚨 Crisis & Safety Routing

First-Class Crisis Routing — Physical evacuation steps & priority helplines surface above paperwork

🌦️ Real-Time Intelligence & Weather Integration

Universal location resolution paired with real-time Open-Meteo weather forecasts

⚙️ System Workflow & Tool Execution

End-to-end request processing flow paired with Sandboxed Tool Execution Engine (TTE) controls

🎯 6. Judge Examples — Try These Live

Try Sahay directly with natural-language questions in the live demo. The examples below cover the core capabilities demonstrated in the live production system.

🌦️ Weather & Location Intelligence

Will tomorrow rain in Patna?

Will today rain in Chennai?

Will day after tomorrow rain in Triveniganj?

Will day after tomorrow rain in UP?

Will day after tomorrow rain in MADRAS?

Will day after tomorrow rain in Darbhangha?

Verified Location Alias Resolution

User Input	Resolved Location	Administrative Region	Country
`UP`	Uttar Pradesh	Representative forecast (`Lucknow region`)	India
`MADRAS`	Chennai	Tamil Nadu	India
`Darbhangha`	Darbhanga	Bihar	India
`Bombay`	Mumbai	Maharashtra	India
`Calcutta`	Kolkata	West Bengal	India
`Bangalore`	Bengaluru	Karnataka	India

🏛️ Public Services & Government Assistance

I need food assistance in Bihar.

I need help finding government assistance.

What government support is available for my family?

I need help with a government scheme.

✅ Eligibility Evaluation

Am I eligible for food assistance?

What are the eligibility requirements?

Can you check whether I qualify?

What information do you need to check my eligibility?

📄 Documents & Requirements

What documents do I need?

What documents are required for this service?

What should I prepare before applying?

🚨 Crisis & Emergency Assistance

There is a flood near me. What should I do?

My house was damaged by flooding in Bihar and we have nowhere to stay tonight.

Where can I get emergency help?

What should I do after being displaced by a disaster?

💬 Multi-Turn Conversational Sequences

Use these queries sequentially in the same conversation session to test Sahay's context retention and topic state handling:

Sequence A — Weather Context & Location Switching

Will tomorrow rain in Chennai?

What about tomorrow?

Will today rain in Chennai?

How about Patna?

Demonstrates location switching, temporal updates, and contextual follow-up handling.

Sequence B — Public Service & Eligibility Follow-Up

I need food assistance in Bihar.

Am I eligible?

What documents do I need?

Demonstrates topic-scoped context across eligibility and document follow-ups.

🛡️ Transparent Fallback & Safe Failure

Will day after tomorrow rain in Xyzabc12345?

When a location cannot be confidently resolved, Sahay asks for clarification (validation_status = "FAILED") or returns a transparent failure message rather than silently inheriting a stale previous location.

💡 Judge Tip: Start with a weather question, switch the location, change the requested date, and then try a public-service or crisis question in the same session to see Sahay's contextual decision pipeline in action.

🏗️ 7. Technical Architecture

SAHAY is built as a high-performance full-stack application. The React + Vite frontend is served alongside a FastAPI backend via same-origin /api/* serverless routes on Vercel.

               User Query (English / Hindi / Hinglish)
                                 │
                                 ▼
                 [ Semantic NLU Understanding ]
         (Extracts Intent, Facts, Location & Jurisdiction)
                                 │
             ┌───────────────────┴───────────────────┐
             ▼                                       ▼
    [ Crisis Safety Route ]               [ Standard Civic Route ]
  (Evacuation & Helplines)               (Knowledge Base Retrieval)
             │                                       │
             └───────────────────┬───────────────────┘
                                 ▼
                [ Universal Location Intelligence ]
              (Extraction → Alias Normalization → Geocoding)
                                 │
                                 ▼
             [ Real-Time Open-Meteo Integration ]
                                 │
                                 ▼
              [ Deterministic Eligibility Engine ]
           (Code-Verified Criteria Evaluation)
                                 │
                                 ▼
            Structured SahayResponse JSON Payload

🧠 8. Conversational Intelligence & Pipeline

The backend orchestrates queries through modular, decoupled services:

Service Component	File Location	Core Responsibility
AI Orchestrator	`ai_orchestrator.py`	End-to-end request orchestration and decision routing
Semantic NLU	`semantic_understanding.py`	Fact extraction, intent classification, pronoun resolution, and location parsing
Crisis Navigator	`crisis_navigator.py`	Emergency safety intercept, physical evacuation guidance, and helpline dispatch
Eligibility Engine	`eligibility_engine.py`	Deterministic Python evaluation of statutory criteria
Knowledge Base	`knowledge_base.py`	Hybrid RAG retrieval over verified government scheme datasets
Conversation Memory	`conversation_memory.py`	Topic-scoped multi-turn context retention and active scheme state tracking
Web Search Service	`web_search_service.py`	Real-time Open-Meteo weather forecasting and location resolution
TTE Engine	`tte_engine.py`	Sandboxed tool proposal engine with AST static analysis security

🌍 9. Universal Location Intelligence

Supports arbitrary geographic entities through extraction, normalization, geocoding, candidate ranking, and clarification fallback, subject to the coverage of the underlying geographic data provider.

Resolution Pipeline:

Extraction: Preposition matching (in <location>), explicit parameters, and composite location parsing (Madras, Oregon).
Normalization & Aliasing: Translates abbreviations (UP → Uttar Pradesh) and historical names (MADRAS → Chennai, Tamil Nadu, Bombay → Mumbai, Calcutta → Kolkata, Bangalore → Bengaluru) without hardcoding massive dictionaries.
Phonetic & Misspelling Correction: Resolves typos (e.g., Darbhangha → Darbhanga, Bihar).
Geocoding & Candidate Ranking: Queries Open-Meteo Geocoding API with multi-candidate scoring based on population, admin region, and country context.
State/UT Representative Policy: State or Union Territory forecasts render an honest representative header using the regional capital (e.g., "Representative forecast for Uttar Pradesh (Lucknow region)").
Transparent Fallback: If a location cannot be resolved, SAHAY asks for clarification (validation_status = "FAILED") without inheriting stale locations from context.

🛡️ 10. Security & Trust Engineering

Production Secret Validation: Enforces strict validation of SECRET_KEY and production configuration.
Deterministic Legal Rules: Statutory eligibility logic runs exclusively in Python code, preventing LLM hallucination of benefits.
TTE AST Security Linter: Dynamic tool proposals are validated via ast.parse, blocking dangerous operations (os, sys, subprocess) or arbitrary execution.
Prompt Injection Defense: Input text is sanitized and wrapped before reaching language model context windows.
Tool-Result Validation: All tool outputs undergo structural validation before integration into user responses.
Jurisdiction Containment: Enforces strict isolation between Indian (IN) and US (US) welfare datasets.
No Chain-of-Thought Exposure: Internal reasoning traces remain internal and are never exposed to end users.

✅ 11. Verification & Quality Assurance

All engineering benchmarks have been empirically verified:

Benchmark Check	Result	Details
Backend Test Suite	120 / 120 Passed	100% pass rate across unit, integration, and scenario tests
Frontend Vite Build	Passed	Clean TypeScript compilation and bundle generation in 2.9s
Service Synchronization	100% Identical	Byte-for-byte MD5 hash match between backend and frontend service modules
Production Health API	HTTP 200 OK	Verified at `https://sahay-cyan.vercel.app/api/health`
Production OpenAPI	HTTP 200 OK	Validated OpenAPI 3.1 JSON schema at `https://sahay-cyan.vercel.app/api/openapi.json`
Location Matrix Smoke Test	10 / 10 Passed	Live production verification of aliases, states, misspellings, and global locations

📁 12. Project Structure

sahay/
├── api/
│   └── index.py               # Vercel serverless API entrypoint
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI application initialization & routes
│   │   ├── models/            # Pydantic data schemas & response models
│   │   └── services/          # Core intelligence, NLU, eligibility & search services
│   └── tests/                 # 120 Pytest verification test scripts
├── docs/                      # Technical architecture, security & evaluation specs
├── frontend/
│   ├── app/                   # Frontend service mirror for unified deployment
│   ├── src/                   # React 18 + TypeScript + Vite UI components
│   └── package.json           # Frontend dependencies & build scripts
├── screenshots/               # Application UI demonstration assets
├── pyproject.toml             # Python configuration & test settings
├── vercel.json                # Vercel full-stack deployment configuration
└── README.md                  # System documentation

⚡ 13. Local Setup & Installation

Prerequisites

Python 3.12
Node.js 18+

1. Clone & Setup Environment

git clone https://github.com/mrashish18/sahay.git
cd sahay
cp .env.example .env

2. Backend Setup

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

3. Frontend Setup

cd frontend
npm install
npm run dev

Access the application locally at http://localhost:5173.

🔌 14. API Reference

Primary Chat Endpoint: `POST /api/v1/chat`

Request Payload:

{
  "message": "will day after tomorrow rain in UP",
  "conversation_id": "user_session_123",
  "user_context": {
    "state": "Uttar Pradesh"
  }
}

Response Payload:

{
  "response": "🌧️ Day after tomorrow Representative forecast for Uttar Pradesh (Lucknow region)\n\nDaily forecast (24-hour total):\n• Rain Probability: 94%\n• Temperature Range: 26°C – 32°C\n• Conditions: Thunderstorm with slight hail ⛈️",
  "flow": "WEB_SEARCH_REQUIRED",
  "situation": {
    "summary": "🌧️ Day after tomorrow Representative forecast for Uttar Pradesh (Lucknow region)",
    "weather_data": {
      "city": "Uttar Pradesh",
      "entity_type": "STATE",
      "admin_region": "Uttar Pradesh",
      "country": "India"
    }
  }
}

🏆 15. Hackathon Highlights

🎯 High Social Impact: Direct assistance for underprivileged citizens navigating public welfare and emergency crises.
⚡ Zero Hallucination Eligibility: Deterministic Python rule evaluation eliminates false promises of government benefits.
🛡️ Safety-First Crisis Routing: Emergency disaster handling prioritizes human life above paperwork.
🌦️ Robust Location Resolution: Gracefully handles abbreviations, regional state names, historical aliases, and typos without hardcoding giant databases.
🚀 Full-Stack Production Ready: Deployed live on Vercel with same-origin serverless API routes and zero localhost dependencies.

🔭 16. Future Scope

🌍 Expanded Welfare Schemes: Integrate additional state-level schemes across India and global municipal jurisdictions.
🗣️ Voice & Regional NLU: Add speech-to-text and multi-lingual voice interaction in regional Indian languages.
🔌 Direct Portal Submissions: Connect with official government service APIs where public submission endpoints exist.
📡 Offline/Low-Bandwidth Mode: Progressive Web App (PWA) offline caching for low-connectivity rural regions.

SAHAY 2.0 — Universal Civic Navigator

Bridging the gap between citizen need and verified public support.

Built for civic empowerment • Designed for trust • Engineered for impact

Name		Name	Last commit message	Last commit date
api		api
backend		backend
data		data
docs		docs
evaluations/datasets		evaluations/datasets
frontend		frontend
screenshots		screenshots
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
render.yaml		render.yaml
requirements.txt		requirements.txt
uv.lock		uv.lock
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation