yashvi-s/Scheme-Setu

Scheme Setu Agent (योजना सेतु)

Scheme Setu is an AI-powered welfare discovery portal that helps Indian citizens discover government schemes they are eligible for and provides a clear action plan. Built as a capstone project demonstrating agentic reasoning, multi-agent workflows, and Model Context Protocol (MCP) tool use, it operates without collecting sensitive identity credentials.

Architecture Overview

Scheme Setu uses a decoupled, multi-layer architecture to handle frontend presentation, backend APIs, agentic orchestration, and structured data protocol communication.

graph TD
    User([Citizen / User]) -->|Interacts with UI| FE[Frontend: index.html, app.js, style.css]
    FE -->|Voice Search /api/stt| FA[FastAPI Backend: main.py]
    FE -->|Search Request /api/discover| FA
    
    subgraph FastAPI Backend
        FA --> STT[STT Endpoint: Whisper / Gemini Fallback]
        FA --> ORCH[Orchestrator: orchestrator.py]
    end
    
    subgraph Agentic Orchestration
        ORCH -->|Bilingual Toggle| TRANS[Translation Engine: Gemini]
        ORCH -->|Candidate Retrieval| MCP_C[MCP Client: client.py]
        ORCH -->|Demographic Filter| MATCH[Matcher Agent: LLM]
        ORCH -->|Rule Verification| VERIFY[Verifier Agent: LLM]
    end
    
    subgraph Data Protocol Layer
        MCP_C -->|Stdio JSON-RPC| MCP_S[MCP Server: server.py]
        MCP_S --> DB[(Schemes Database: schemes_data.py)]
    end
    
    MATCH -->|Proposes Matches| ORCH
    ORCH -->|Fuzzy ID Mapping| ORCH
    ORCH -->|Retrieve Details| MCP_C
    ORCH -->|Submit Candidates| VERIFY
    VERIFY -->|Final Clean List| TRANS
    TRANS -->|Translate if Hindi| FE

Core Architecture Components

1. 1.Frontend (Presentation):
2. 2.A modern responsive user interface styled with premium glassmorphism in a light pastel sky-blue theme.
3. 3.Built entirely on Vanilla CSS (no Tailwind/inline styles) using solid, accessible high-contrast colors without gradients.
4. 4.Handles localized states and option dropdowns, active chips, microphone triggers, and collapsible checklists.

1. 1.FastAPI Host (Backend):
2. 2.Serves the frontend static files.
3. 3.Exposes /api/discover for search requests and /api/stt for voice transcriptions.
4. 4.Implements early configuration loading (load_dotenv at start) and robust exception routing.

1. 1.Agent Orchestration (Layer 2 & 3):
2. 2.Translator: Lazily translates Hindi input needs to English before processing, and translates final action plans/summaries back to Hindi.
3. 3.Matcher Agent: Analyzes candidates matching demographic guidelines and suggests schemes with confidence levels.
4. 4.Fuzzy ID Mapper: Map-resolves slightly hallucinated LLM IDs (e.g. 'mudra-yojana') back to valid database primary keys (e.g. 'pm-mudra').
5. 5.Verifier Agent: Strictly matches candidate profiles against scheme rules, pruning incorrect matches and outlining required document checklists.

1. 1.Model Context Protocol (MCP):
2. 2.Uses fastmcp to expose JSON-RPC tools (search_schemes, get_scheme_details, get_document_checklist) over stdio.
3. 3.The MCP Client double-decodes JSON responses to handle nested serialization robustly.

Completed Features (Layers 1-4)

Layer 1: Core Agent + MCP Server

• —Seeded with 14 real, high-impact Indian welfare schemes (such as PM-KISAN, PM Mudra, Ayushman Bharat, Sukanya Samriddhi, PMAY-U, and PM SVANidhi) with verified official links.
• —Exposes tools over a Python FastMCP server running via stdio JSON-RPC.
• —Form-based profile collection with zero document uploads or persistent backend storage.

Layer 2: Matcher + Verifier Agentic Split

• —Matcher Agent: Analyzes candidate schemes returned from MCP, ranking and explaining match potential based on demographics.
• —Verifier Agent: Checks the Matcher's claims critically against strict criteria parameters from get_scheme_details, adjusting, confirming, or removing matches.
• —Fuzzy ID Mapping: Automatically aligns proposed matching IDs back to candidate database keys to prevent LLM hallucination errors.
• —Demographic Fallback: Operates robustly with or without the need interest specified (treating the needs field as fully optional).

Layer 3: Hindi Translation

• —Full UI localization (English/Hindi toggle) including states dropdown and UT option group translations.
• —Integrates a translation flow (using Gemini) that translates Hindi search goals internally to English, reasons, and returns the final plan back to Hindi.

Layer 4: Voice Input

• —Native browser audio recording with instant voice transmission.
• —Audio transcribed natively using the Gemini multimodal API, with a robust fallback to catch connection errors and process them gracefully.

Directory Structure

schema-setu/
│
├── mcp_server/
│   ├── schemes_data.py       # Seed dataset of 14 welfare schemes and official links
│   └── server.py             # FastMCP server exposing tools and safe NoneType parser
│
├── agent/
│   ├── client.py             # Stdio MCP client wrapper with JSON double-decoding
│   └── orchestrator.py       # Matcher + Verifier + Translator coordination & ID mapper
│
├── frontend/
│   ├── index.html            # Premium glassmorphism layout
│   ├── style.css             # Light pastel sky-blue theme (no gradients)
│   └── app.js                # Form, mic handlers & dynamic state translation logic
│
├── main.py                   # FastAPI host (API endpoints & static host)
├── .env                      # API keys (gitignored)
└── .gitignore                # Git ignores

Installation & Setup

1. 1.Clone or navigate to the directory: Ensure you are in the project folder.

1. 1.Verify Dependencies: Ensure fastapi, uvicorn, mcp, google-genai, and python-dotenv are installed.

   pip install fastapi uvicorn mcp google-genai python-dotenv

1. 1.Configure Environment: Ensure the GEMINI_API_KEY is present in your environment or specified in a .env file:

   GEMINI_API_KEY=your_actual_gemini_api_key
   HF_API_KEY=your_optional_huggingface_api_key

1. 1.Run the Application: Start the FastAPI server:

   python main.py

1. 1.Access the Portal: Open your browser and navigate to: http://127.0.0.1:8000