Welfare Eligibility Engine

Production-grade FastAPI service for checking citizen eligibility against government welfare schemes.

Architecture

app/
├── main.py              # FastAPI application and endpoints
├── db.py                # Database connection and session management
├── models.py            # SQLAlchemy ORM models
├── schemas.py           # Pydantic request/response schemas
└── services/
    └── eligibility.py   # Core eligibility logic

Prerequisites

• Python 3.9+
• PostgreSQL 14+ with welfare_schemes database
• Database populated with schemes (see Part 2)

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Database

Create .env file (copy from .env.example):

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/welfare_schemes

Or set environment variable:

$env:DATABASE_URL="postgresql://postgres:postgres@localhost:5432/welfare_schemes"

3. Verify Database Connection

Ensure PostgreSQL is running and the schemes table exists with data:

psql -U postgres -d welfare_schemes -c "SELECT COUNT(*) FROM schemes;"

Expected output: 5 (from Part 2)

Running the Service

Start FastAPI Server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Server will start at: http://localhost:8000

Verify Health

curl http://localhost:8000/

Expected response:

{
  "status": "online",
  "service": "Welfare Eligibility Engine",
  "version": "1.0.0"
}

Check Database Health

curl http://localhost:8000/health/db

Expected response:

{
  "status": "healthy",
  "schemes_in_database": 5
}

API Usage

Endpoint: POST /eligibility/check

Check citizen eligibility against all schemes.

Request

curl -X POST http://localhost:8000/eligibility/check `
  -H "Content-Type: application/json" `
  -d '{
    "age": 45,
    "gender": "female",
    "state": "Karnataka",
    "income": 180000,
    "category": "General"
  }'

Response

{
  "eligible_schemes": [
    {
      "name": "Ayushman Bharat PMJAY",
      "state": "All India",
      "benefit": "₹5 lakh per family per year",
      "reason": "Central scheme available nationwide and No age restriction and No income restriction"
    },
    {
      "name": "Gruha Lakshmi Scheme",
      "state": "Karnataka",
      "benefit": "₹2000 per month",
      "reason": "State matches (Karnataka) and No age restriction and Income below limit (₹200,000) and Gender matches (Female)"
    }
  ],
  "count": 2
}

Test Cases

Test 1: Female from Karnataka with low income

curl -X POST http://localhost:8000/eligibility/check `
  -H "Content-Type: application/json" `
  -d '{
    "age": 35,
    "gender": "female",
    "state": "Karnataka",
    "income": 150000,
    "category": "General"
  }'

Expected: Gruha Lakshmi + Central schemes

Test 2: Male farmer from any state

curl -X POST http://localhost:8000/eligibility/check `
  -H "Content-Type: application/json" `
  -d '{
    "age": 50,
    "gender": "male",
    "state": "Punjab",
    "income": 100000,
    "category": "Farmer"
  }'

Expected: PM-KISAN + PMJAY

Test 3: Female from Maharashtra, age 30, income 200000

curl -X POST http://localhost:8000/eligibility/check `
  -H "Content-Type: application/json" `
  -d '{
    "age": 30,
    "gender": "female",
    "state": "Maharashtra",
    "income": 200000,
    "category": "General"
  }'

Expected: Majhi Ladki Bahin (age 21-65, income ≤2.5L) + Central schemes

Test 4: Female from Tamil Nadu, age 25, income 150000

curl -X POST http://localhost:8000/eligibility/check `
  -H "Content-Type: application/json" `
  -d '{
    "age": 25,
    "gender": "female",
    "state": "Tamil Nadu",
    "income": 150000,
    "category": "General"
  }'

Expected: Kalaignar Magalir Urimai Thittam + Central schemes

Eligibility Rules

A scheme is eligible if ALL these conditions are met:

1. State: Citizen's state matches scheme state OR scheme is "All India"
2. Age:
   • If min_age is set: citizen age ≥ min_age
   • If max_age is set: citizen age ≤ max_age
   • If NULL: no restriction
3. Income:
   • If max_income is set: citizen income ≤ max_income
   • If NULL: no restriction
4. Gender:
   • If gender_constraint is set: must match citizen gender
   • If NULL: no restriction
5. Category:
   • If category_scope is set: must match citizen category
   • If NULL or "All": no restriction

API Documentation

Interactive API docs available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Error Handling

• Invalid input → 422 Unprocessable Entity
• Database connection failure → 500 Internal Server Error
• No eligible schemes → 200 OK with empty list