The agent service is a Python FastAPI microservice powering all AI-driven features across UrbanFlow. Every feature runs as a stateful, multi-step agent graph built on LangGraph + LangChain, using Google Gemini 2.0 Flash as the underlying model. Each pipeline below is an independent workflow — data flows in, passes through specialised reasoning nodes, and a structured result comes out.
Trigger: POST /reports — citizen submits an image + description + location
Incoming Report
│
▼
[Preflight Validation] ← Checks image relevance; non-civic content is rejected here
│
Pass / Reject
│ (if pass)
▼
[Specialist Agents] ← Domain-specific sub-agents run in parallel
water │ waste │ infrastructure │ electrical │ uncertainty handler
│
▼
[Locality Check] ← Geohash-based deduplication against nearby existing reports
│
▼
[Finalizer] ← Picks the best category, assigns severity & title,
persists report via the backend
│
▼
{ reportId, category, severity, ai_analysis }
Trigger: POST /analyze-post — community post (title + description + images + city)
Incoming Post
│
▼
[Triage & Sentiment] ← Classifies post type (complaint / suggestion / alert)
and computes a sentiment score
│
▼
[RAG Fact-Check] ← Cross-references claims against known civic data
│
▼
[Vectorise & Cluster] ← Embeds the post; assigns it to the nearest cluster
of similar posts
│
▼
{ sentiment, urgency, post_type, is_misinformation, cluster_id }
Bonus: POST /summarize-cluster — takes all posts in a cluster and generates a 5-word headline + 2-sentence insight using the LLM.
Trigger: POST /analyze-pulse — city name + internal post data
City + Internal Posts
│
▼
[Web Scraper Orchestrator] ← Pulls real-time data from relevant public web sources
│
▼
[Correlation & Analysis] ← Cross-references scraped data with internal posts;
identifies trends, spikes, and recurring issues
│
▼
Structured city pulse report (issues, trends, confidence scores)
Trigger: POST /process-job — raw job posting (description + category + location + budget)
Raw Job
│
▼
[Job Enrichment Workflow]
├── Enrich Description → LLM rewrites to a professional, detailed format
├── Extract Skills → Pulls a structured required-skill list
├── Generate Embedding → Vector used for later matching
└── Build Feedback Form → Creates post-job rating questions
│
▼
{ enriched_description, job_embedding, feedback_form, extracted_skills }
Trigger: POST /graph-match — job requirements (skills + location + radius)
Job Requirements
│
▼
[Graph Retrieval] ← Fetches candidate workers from the skill graph
stored as edges in MongoDB
│
▼
[Multi-Dimensional Scorer] ← Each candidate scored across:
vector similarity + graph score + reputation
│
▼
[Trajectory Boost] ← Applies an EWA (Exponentially Weighted Average)
model to reward upward skill growth trends
│
▼
[Contextual Re-ranker] ← Final LLM pass re-ranks candidates against
the full job context
│
▼
Ranked candidate list with scores & trajectory signals
Related endpoints:
POST /graph-writeback— updates the graph post-job (ratings + new skill edges)POST /graph-safety-flag— writes a trust-flag edge on safety incidentsPOST /graph-extract-skills— parses a worker's profile and writeshas_skilledges
Trigger: POST /process-skill-gap — post-job feedback (questions + ratings)
Feedback Ratings
│
▼
[Skill Gap Agent] ← LLM interprets rating patterns into specific
improvement areas for the worker
│
▼
{ skill_gap_summary, skill_gap_embedding }
Trigger: POST /analyze-geoscope-intelligence — module type + region + stats + optional satellite image
Region + Module + Stats + Image
│
▼
[Vision Node] ← Multimodal LLM processes the satellite image
│
▼
[Synthesis Node] ← Combines visual output with statistical summaries
to produce a structured intelligence report
│
▼
Structured report (findings, risk signals, confidence)
Bonus: POST /analyze-geoscope-correlation — a Deep Correlation Agent that cross-references multiple environmental modules (e.g. heat island ↔ flood risk) to surface non-obvious spatial relationships.
Trigger: Internal / Vyom chat routes
User Message
│
▼
[ReAct Loop Agent] ← LLM decides which tool(s) to invoke at each step
general tools │ civic tools │ notification tools │ ...
│
(loops until confident answer)
│
▼
Conversational response
Lightweight, single-purpose agents for real-time safety decisions.
| Endpoint | Purpose |
|---|---|
POST /agent1 |
Multi-model chat safety scoring — sentiment + urgency + severity → SOS trigger decision |
POST /analyze-safety |
Audits a report's chat history for safety violations; returns severity + summary |
POST /analyze-voice |
Transcribes + analyses audio SOS recordings — urgency, pattern detection, action items |
| Endpoint | Purpose |
|---|---|
POST /embed |
Generates a text embedding vector (shared across pipelines) |
POST /resolveWasteReports |
Compares before/after waste report images and returns a resolution confidence score |
| Layer | Technology |
|---|---|
| Framework | FastAPI (Python) |
| Agent Orchestration | LangGraph |
| LLM | Google Gemini 2.0 Flash |
| Embeddings | Google Generative AI Embeddings |
| Graph Database | MongoDB (async) |
| Auth | Auth0 (JWT / RS256) |