What is Alkhidmat Relief Copilot?
Alkhidmat Relief Copilot is an NGO aid desk SaaS (not a chatbot) built for Alibaba Cloud AI Hackathon Pakistan 2026, powered by Qwen via DashScope. Citizens submit needs on a public request page; a LangGraph pipeline runs Intake → Triage → Knowledge → Integrity → Matcher → Dispatch, with a HITL supervisor gate for critical or high-risk cases. Staff sign in to tickets, agent traces, metrics, and PDF export — on FastAPI + Next.js 14 + Postgres/pgvector, live on Google Cloud Run.
Capabilities
- Public request path —
/ sitrep landing → /request guest intake → /status with AKD number + phone (no citizen account)
- Staff ops — JWT roles (desk / supervisor); home
/tickets
- Agent trace — live pipeline + sitrep replay on the landing (replay is local, not an LLM call)
- Integrity — duplicate / risk checks; never skipped on create
- HITL — approve / reject critical or high-risk cases
- Light RAG — SOP retrieval (keyword + pgvector when available)
- Urdu + English — Nastaliq lockup + live intake
- Metrics + PDF — desk dashboard and case export
Quick start
Start Postgres first if you want the product DB (port 5432 must be free):
docker compose up -d db
copy .env.example .env
Backend
cd backend
python -m venv .venv
# Windows:
.venv\Scripts\activate
pip install -r requirements.txt
copy ..\.env.example .env
set LLM_MODE=mock
uvicorn app.main:app --reload --port 8000
No Docker / 5432 busy: in backend/.env set DATABASE_URL=sqlite:///./data/relief.db. Tests do not need Docker:
cd backend
set LLM_MODE=mock
pytest -q
Frontend
cd frontend
npm install
copy .env.local.example .env.local
npm run dev
Open http://localhost:3000/ (public landing). Citizens use /request and /status; staff use /login.
Tests
cd backend
set LLM_MODE=mock
pytest -q
Demo paths
- Urdu/English food request → AKD number + resource match → Check status
- Duplicate phone → HITL pending (still has an AKD number)
- Critical medical → Supervisor approve → dispatched
See docs/DEMO_SCRIPT.md.
Project layout
backend/ FastAPI, LangGraph agents, tools, JWT auth
frontend/ Next.js 14 App Router (public + staff IA)
docs/ Product, architecture, demo, deployment
deploy/gcp/ Cloud Run + Cloud SQL promote scripts
.github/workflows Backend pytest CI
Deploy
Promote checklist and secrets: docs/DEPLOYMENT.md. Local Compose: docker-compose.yml (Postgres/pgvector + api + web).
Docs
Alibaba Cloud
- DashScope / Qwen —
DASHSCOPE_API_KEY and LLM_MODE=qwen
- Qoder — hackathon IDE (Skills / MCP narrative)
Repo
https://github.com/Atif1299/alkhidmat-relief-copilot
