Skip to content
BranchesTags

Repository files navigation

🏛️ ShikayatAI

  ███████╗██╗  ██╗██╗██╗  ██╗ █████╗ ██╗   ██╗ █████╗ ████████╗ █████╗ ██╗
  ██╔════╝██║  ██║██║██║ ██╔╝██╔══██╗╚██╗ ██╔╝██╔══██╗╚══██╔══╝██╔══██╗██║ 
  ███████╗███████║██║█████╔╝ ███████║ ╚████╔╝ ███████║   ██║   ███████║██║
  ╚════██║██╔══██║██║██╔═██╗ ██╔══██║  ╚██╔╝  ██╔══██║   ██║   ██╔══██║██║
  ███████║██║  ██║██║██║  ██╗██║  ██║   ██║   ██║  ██║   ██║   ██║  ██║██║
  ╚══════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝
          AI-Powered Civic Complaint Resolution System for Karachi

Python FastAPI Next.js License Groq Tailwind CSS

🏙️ What is ShikayatAI?

ShikayatAI is a bilingual (Urdu & English) civic complaint resolution platform engineered specifically for the citizens of Karachi, Pakistan. Built for the Google x Kaggle AI Agents: Intensive Vibe Coding Capstone Project, it leverages a multi-agent AI pipeline built on Google's ADK and the Groq Llama 3.3 70B model to instantly categorize, route, and draft formal civic complaints based on natural language input.

Instead of citizens navigating complex bureaucracy or figuring out which department handles their specific issue (e.g., KWSB for water, KE for electricity, SSMB for garbage), ShikayatAI acts as a single intelligent portal. A user simply types their problem in plain Urdu, Roman Urdu, or English. The AI pipeline runs a safety pre-check, dynamically researches live contact info for the correct authority via Google Search, and drafts formal, reference-tracked complaint letters in both languages, ready for submission.

🌐 Live Demo

Service URL
Frontend (Cloud Run) https://shikayatai-web-941068767562.asia-south1.run.app
Backend API (Cloud Run) https://shikayatai-api-941068767562.asia-south1.run.app
Backend Health Check https://shikayatai-api-941068767562.asia-south1.run.app/api/health

✨ Feature List

🧠 Multi-Agent AI Pipeline

  • Built using the Google Agent Development Kit (ADK) and SequentialAgent orchestration.
  • Three distinct, specialized agents work in tandem: Classifier, Researcher, and Drafter.

🛡️ Safety & Content Moderation Pre-check

  • Intercepts and rejects medical emergencies, active crimes, political rants, or gibberish.
  • Returns empathetic, bilingual redirection (e.g., advising users to call 15 for police or 1122 for medical).

🔍 Automated Department Routing

  • Maps colloquial Karachi civic issues to official bodies (KWSB, KE, KMC, SSMB, SBCA, PTCL, SSGC).
  • Assesses and assigns priority levels (high, medium, low) to every issue.

🌐 Live Information Researcher

  • Executes real-time Google Searches via tool calling to scrape up-to-date official complaint portals, helplines, and physical addresses of the determined authority.

📝 Bilingual Formal Drafting

  • Uses dynamically generated unique tracking reference numbers (REF-[YEAR]-[ID]) and localized timestamps.
  • Generates highly formal, ready-to-print official complaint letters in both English and Urdu (Nastaliq).

🏗️ Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND                                  │
│                                                                        │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ Next.js 14 Web UI (Tailwind CSS, Urdu Nastaliq Fonts)          │   │
│   │ Single Page App -> POST /api/complaint                         │   │
│   └────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  │ JSON Payload
┌─────────────────────────────────▼──────────────────────────────────────┐
│                              BACKEND API                               │
│                                                                        │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ FastAPI (api/main.py)                                          │   │
│   │  ├─ Global Error Handlers (Bilingual)                          │   │
│   │  └─ Latency & Logging Middlewares                              │   │
│   └─────────────────────────────┬──────────────────────────────────┘   │
│                                 │                                      │
│   ┌─────────────────────────────▼──────────────────────────────────┐   │
│   │ ADK Orchestrator (agents/orchestrator.py)                      │   │
│   │                                                                │   │
│   │  1. Safety Pre-check (Groq Llama 3.3)                          │   │
│   │     If safe, triggers Sequential Pipeline:                     │   │
│   │                                                                │   │
│   │  ┌────────────┐   ┌────────────┐   ┌──────────┐                │   │
│   │  │ Classifier ├──►│ Researcher ├──►│ Drafter  │                │   │
│   │  │ Agent      │   │ Agent      │   │ Agent    │                │   │
│   │  └────────────┘   └─┬──────────┘   └──────────┘                │   │
│   └────────────────────────────────────┼───────────────────────────┘   │
└────────────────────────────────────────┼───────────────────────────────┘

🛠️ Tech Stack

Backend

Technology Role
Python 3.11+ Runtime
FastAPI REST API Framework
Uvicorn ASGI Server
Google ADK Multi-Agent Orchestration
Groq API LLM Engine (llama-3.3-70b-versatile) via LiteLLM

Note on AI Provider: We initially built this system using Google's Gemini API (gemini-2.5-flash-lite), but the free-tier limit of 20 requests per day caused immediate quota exhaustion. To ensure a seamless user experience, we have switched to the Groq API (using llama-3.3-70b-versatile via ADK's LiteLlm wrapper), which provides extremely fast inference and significantly higher free limits!

Frontend

Technology Role
Next.js 14 React Framework (App Router)
TypeScript Type Safety
Tailwind CSS v4 Utility-first styling & theming
CSS/Google Fonts Urdu typography (Noto Nastaliq Urdu)

Infrastructure

Service Purpose
Google Cloud Run Serverless API & Frontend Hosting
Google Cloud Build CI/CD Pipeline
Google Secret Manager Secure API Key Injection

⚙️ How It Works

1. Classifier Agent

Extracts the core issue, assigns the responsible administrative body in Karachi, sets urgency, and returns structured JSON outlining the problem in English and Urdu.

2. Researcher Agent

Receives the target authority (e.g., "KWSB"). Uses a live Google Search tool to find the exact, current complaint portal URL, helpline numbers, and physical address for that authority.

3. Drafter Agent

Uses pre-generated dynamic REF numbers and localized dates to write a highly formal, persuasive letter in English, and a perfectly localized Urdu letter requesting immediate action from the authority.

📁 Project Structure

ShikayatAI/
│
├── agents/                       Google ADK AI Logic
│   ├── orchestrator.py           Pipeline manager & Safety Pre-check
│   ├── classifier.py             Categorization agent
│   ├── researcher.py             Live web search agent
│   └── drafter.py                Letter generation agent
│
├── api/                          Backend Server
│   └── main.py                   FastAPI endpoints & CORS config
│
├── eval/                         Benchmarking
│   └── test_cases.py             15 automated test cases evaluating safety/classification
│
├── frontend/                     Next.js Web Application
│   ├── src/app/
│   │   ├── page.tsx              Main UI, form, state, and results rendering
│   │   ├── layout.tsx            Metadata and font loading
│   │   └── globals.css           Tailwind configuration and custom fonts
│   ├── Dockerfile                Standalone image builder for Cloud Run
│   └── next.config.ts            Standalone output configuration
│
├── cloudbuild.yaml               CI/CD deployment pipeline for GCP
├── smoke_test.py                 Post-deployment verification script
├── Dockerfile                    Backend API Docker image builder
└── requirements.txt              Python dependencies

🚀 Local Setup

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • A Groq API Key

Step 1 — Backend Setup

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate # Mac/Linux

# Install dependencies
pip install -r requirements.txt

# Create environment file
echo GROQ_API_KEY=your_groq_key_here > .env

Step 2 — Start the Backend API

uvicorn api.main:app --reload --port 8000

Verify it's running: curl http://localhost:8000/api/health

Step 3 — Frontend Setup

cd frontend

# Install dependencies
npm install

# Configure environment
echo NEXT_PUBLIC_API_URL=http://localhost:8000 > .env.local

Step 4 — Start the Frontend UI

npm run dev

Open http://localhost:3000 to view the ShikayatAI dashboard.

📡 API Reference

POST /api/complaint

Main inference endpoint. Runs safety check and orchestrator pipeline.

Body:

{
  "complaint": "Teen din se pani nahi aa raha...",
  "location": "PECHS Block 2",
  "user_id": "user_xyz123"
}

GET /api/health

Response:

{
  "status": "ok",
  "model": "groq/llama-3.3-70b-versatile",
  "agents": ["Classifier", "Researcher", "Drafter"]
}

☁️ Deployment (Google Cloud Run)

We deploy both the Python Backend and the Next.js Frontend to Google Cloud Run. For automated CI/CD, use the provided cloudbuild.yaml.

1. Set up Secrets

Add your Groq API Key to Google Cloud Secret Manager:

printf "YOUR_GROQ_API_KEY" | gcloud secrets create shikayatai-groq-api-key --data-file=-

gcloud secrets add-iam-policy-binding shikayatai-groq-api-key \
  --member="serviceAccount:COMPUTE_ENGINE_DEFAULT_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

2. Deploy the Backend API

gcloud run deploy shikayatai-api \
  --source . \
  --region asia-south1 \
  --platform managed \
  --allow-unauthenticated \
  --update-secrets=GROQ_API_KEY=shikayatai-groq-api-key:latest

(Copy the resulting URL for the next step)

3. Deploy the Next.js Web UI

Deploy the web frontend, passing the backend API URL as a build argument:

cd frontend

gcloud run deploy shikayatai-web \
  --source . \
  --region asia-south1 \
  --platform managed \
  --allow-unauthenticated \
  --set-build-env-vars NEXT_PUBLIC_API_URL=https://shikayatai-api-[YOUR_PROJECT].run.app

📄 License

This project is open-source and available for educational and commercial use under the MIT License.

Made with ❤️ by Abdul Hayy Khan

About

Multi-agent AI platform built with Google ADK to resolve civic issues in Karachi.

shikayatai-web-941068767562.asia-south1.run.app/

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages