🤖 AI‑Driven Municipal Partner – A next‑generation multi‑agent RAG system revolutionizing how citizens interact with Masvingo City Council.
🔍 Smart Query Routing – Specialized agents seamlessly handle billing inquiries, incident reports, license applications, and general questions, enriched by real‑time web‑scraped council data.
⚡ Robust Tech Stack – Flask frontend + LangGraph orchestration + ChromaDB semantic vectors + Groq LLM + BeautifulSoup scraping = always‑on, intelligent civic assistance.
🎯 Tangible Impact – Cuts administrative workload, delivers instant, reliable answers, and keeps citizens continuously updated through an intuitive web interface.
🚀 Future‑Ready Design – Modular architecture built for easy expansion into voice interfaces, mobile apps, and multilingual support.
It is reasonable to assume that many citizens in Masvingo encounter long queues simply to check their account balances or resolve billing issues. We can also assume that the council halls are often congested, with residents waiting for general inquiries and assistance that could be handled more efficiently. Furthermore, it is safe to assume that while the city maintains a website, it is not fully equipped to provide comprehensive, real-time support, leaving citizens without quick access to critical information.
Under these assumptions, the Masvingo Civic Multi‑Agent Assistant was developed as a practical solution. By anticipating these common challenges, the system leverages multi‑agent orchestration, retrieval‑augmented generation, and live web scraping to deliver instant, accurate, and context‑aware responses. Citizens no longer need to assume that service access requires physical presence; instead, they can rely on a digital assistant that provides 24/7 support for billing inquiries, incident reporting, licensing applications, and general council information.
Citizens in Masvingo face persistent challenges when engaging with municipal services. Many residents endure long queues simply to check account balances or resolve billing issues, consuming valuable time and creating frustration. Council halls are often congested, with general inquiries and assistance requests overwhelming physical offices and reducing the quality-of-service delivery. Although the city maintains a website, it is not fully equipped to provide comprehensive functionality or real‑time updates, leaving citizens without reliable digital alternatives. These inefficiencies place a heavy administrative burden on staff, who must manually handle routine queries that could otherwise be automated. The result is slower response times, reduced efficiency, and dissatisfaction for both citizens and municipal employees. These problems highlight the urgent need for a scalable, intelligent, and citizen‑centric solution that reduces physical congestion, automates routine inquiries, and provides real‑time access to municipal information.
Figure 1:
This diagram illustrates the end-to-end flow of the Masvingo Civic Multi-Agent Assistant system. It begins with user queries submitted through the civic website, which are processed via web scraping to extract live municipal data. The information is stored and retrieved from ChromaDB, then passed through a Retrieval-Augmented Generation (RAG) layer. Based on query classification, the system routes requests to specialized agents—Billing, Incident, and Licensing—ensuring accurate, context-aware responses. This modular architecture enables real-time civic assistance, scalable service delivery, and intelligent automation of municipal interactions
The Masvingo Civic Multi-Agent Assistant expands the original Council Query Assistant by introducing a modular, agent-based architecture powered by LangGraph orchestration. Instead of relying on a single RAG pipeline, this system routes queries to specialized agents—Billing, Licensing, Incident, and General—each equipped with domain-specific prompts and retrieval logic. These agents interact with a shared ChromaDB vector store and structured data sources, while also leveraging integrated tools such as form generators, email dispatchers, and web scrapers. This tool-agent synergy enables dynamic task execution, real-time data enrichment, and fallback handling, making the assistant more robust, extensible, and production-ready for live municipal deployment.
The Masvingo Civic Multi-Agent Assistant is built on a modular architecture designed for intelligent, scalable, and real-time municipal service delivery. Its core features reflect a deliberate response to the challenges faced by citizens and administrators in Masvingo. From smart query routing to tool-enhanced agent execution, each component contributes to a system that is not only technically robust but also socially impactful. Below is a summary of the key capabilities that define the assistant’s functionality and readiness for production deployment.
This infographic showcases five core features of the Masvingo Civic Multi-Agent Assistant: intelligent query routing, hybrid retrieval, tool-agent synergy, live web scraping, and production-grade reliability. Together, these components enable scalable, real-time civic service delivery through AI.
The system uses LangGraph to intelligently route queries to specialized agents—Billing, Licensing, Incident, and General—based on query intent. This modular design ensures accurate, domain-specific responses and allows for easy expansion.
Combines semantic search via ChromaDB with structured civic data (JSON, SQL). This dual-layer retrieval ensures that both unstructured and structured information is accessible for generating grounded answers.
Agents are equipped with functional tools such as form generators, email dispatchers, math utilities, and web scrapers. This enables agents not just to answer questions, but to perform tasks and generate actionable outputs.
The system scrapes live data from official Masvingo City Council web pages, ensuring that responses reflect the most current information available—bylaws, notices, contacts, and service updates.
Built with robust error handling, modular architecture, environment-specific configuration, and monitoring. It’s designed for real-world deployment after serious engagement with Stakeholders and other experts since there are some areas I might have overlooked but its not just experimentation.
This section should walk you through the modular layers, agent orchestration, retrieval logic, and tool integration that make your system near production-ready. Here's the outline:
Introduce the five core layers:
Frontend Layer – Flask web interface for citizen interaction
Orchestration Layer – LangGraph-powered routing and agent coordination
Processing Layer – Specialized agents with domain-specific prompts
Retrieval Layer – ChromaDB vector search + structured civic data
Integration Layer – Web scraping and tool-enhanced fallback mechanisms
Explain how agents are designed:
Each agent has its own prompt config, retrieval logic, and tool access
Agents can invoke tools like form generators, email dispatchers, and math utilities
LangGraph handles query classification and routing
Describe the flow:
User query → LangGraph → Agents → Retrieval → Response
If retrieval fails, fallback to web scraping or general assistant
Highlight:
Domain filtering
Input validation
Error logging
Fallback response generation
" This diagram illustrates the layered architecture of the Masvingo Civic Multi-Agent Assistant. It shows how user queries flow from the web interface through LangGraph orchestration, into specialized agents, and down to a hybrid retrieval layer powered by ChromaDB, structured data, and web scraping. Tool integrations such as email dispatch, form generation, and math utilities enhance agent capabilities and ensure task completion"
To demonstrate the modularity and production-readiness of the Masvingo Civic Multi-Agent Assistant, this section presents selected code snippets from the system. These examples highlight how agents are orchestrated, how retrieval is configured, and how tools are invoked to enrich responses.
Each snippet is annotated to explain its role in the system’s flow—from query routing to agent execution and fallback handling.
# some imports class CoordinatorAgent: """Base agent that routes queries to specialized agents.""" def __init__(self, use_langgraph: bool = True): self.billing_agent = BillingAgent() # Agents listing self.use_langgraph = use_langgraph def route_query(self, query: str) -> str: """Route query to appropriate agent using LangGraph or direct routing.""" if self.use_langgraph: from orchestration.graph_builder import GraphBuilder graph_builder = GraphBuilder() result = graph_builder.process_query(query) return result["response"] else: return self._direct_route(query) def _direct_route(self, query: str) -> str: """Direct keyword-based routing without LangGraph.""" query_lower = query.lower() # Route based on keywords if any(word in query_lower for word in ["bill", "owe", "balance", "payment", "pay"]): return self.billing_agent.handle_query(query) elif ... else: return self._handle_unknown_query(query) def _handle_unknown_query(self, query: str) -> str: """Handle queries that don't match any specialized agent.""" return """ I'm sorry, I couldn't determine which service you need. I can help with: **Billing Services:** Check balances, process payments **Incident Reporting:** Report pipe bursts, leaks, infrastructure issues **Licensing Services:** Apply for business licences, download forms Please rephrase your question or specify what you need help with. """
This code snippet defines the CoordinatorAgent, which serves as the central routing mechanism in the Masvingo Civic Multi‑Agent Assistant. It initializes specialized agents, such as the BillingAgent, and determines whether to use LangGraph orchestration or a simpler keyword‑based fallback for query handling. When a user submits a query, the agent either leverages LangGraph’s graph builder to intelligently classify and process the request or applies direct keyword matching to route it to the appropriate agent. If no match is found, the system provides a default response that guides the user toward supported services like billing, incident reporting, or licensing. In essence, this snippet demonstrates how the assistant ensures that every query is directed to the right agent or gracefully handled when uncertain.
class BillingAgent: def __init__(self): self.api_tool = APITool() self.math_tool = MathTool() def handle_query(self, query: str) -> str: query_lower = query.lower() if "balance" in query_lower or "bill" in query_lower: return self._handle_balance_query(query) elif "pay" in query_lower: return self._handle_payment_query(query) else: return "I can help with bill balances and payments."
class IncidentAgent: def __init__(self): self.incidents_file = Path("data/incidents.json") def handle_query(self, query: str) -> str: if "burst" in query.lower() or "leak" in query.lower(): return self._log_incident_report(query) else: return "Please describe the pipe burst or leak with location." def _log_incident_report(self, query: str) -> str: location = self._extract_location(query) severity = self._extract_severity(query) incident = { "id": f"INC{datetime.now().strftime('%Y%m%d%H%M%S')}", "timestamp": datetime.now().isoformat(), "description": query, "location": location, "severity": severity, "status": "reported" }
These are integrated and some selfmade tools
class RAGTool: def __init__(self): self.client = chromadb.PersistentClient(path="./databases/chroma_db") self.collection = self.client.get_or_create_collection("municipal_docs") self.model = SentenceTransformer('all-MiniLM-L6-v2') self.web_scraper = WebScraperTool() def add_documents(self, documents: list): """Add documents to vector database.""" for doc in documents: if not doc.get('content', '').strip(): continue # Skip empty documents embedding = self.model.encode(doc['content']) self.collection.add( embeddings=[embedding], documents=[doc['content']], metadatas=[doc.get('metadata', {})], ids=[doc.get('id', str(hash(doc['content'])))] )
class FormTool: def __init__(self): pass def fill_licence_form(self, data: dict) -> str: """Generate PDF licence application form.""" output_path = f"licence_form_{data.get('applicant_name', 'unknown')}.pdf" doc = SimpleDocTemplate(output_path, pagesize=letter) styles = getSampleStyleSheet() story = [] # Title story.append(Paragraph("Application for Issue of New Licence", styles['Title'])) story.append(Spacer(1, 12)) # Form fields fields = [ ("Applicant Name", data.get("applicant_name", "")), ("National ID", data.get("national_id", "")), ..... ]
Agents and tools are the backbone of the Masvingo Civic Multi‑Agent Assistant because they enable modularity, specialization, and action. Agents provide domain‑specific intelligence—such as billing, licensing, or incident reporting—so that queries are handled by the most relevant expertise rather than a one‑size‑fits‑all model. This separation ensures accuracy, scalability, and easier maintenance as new services are added. Tools, on the other hand, extend the capabilities of agents beyond simple text responses. By integrating utilities like form generation, email dispatch, math functions, and web scraping, agents can perform real tasks, retrieve live data, and deliver actionable outputs. Together, agents and tools create a system that is not only conversational but also operational, bridging the gap between information access and service execution.
The Masvingo Civic Multi‑Agent Assistant is designed to address real citizen needs by combining agent specialization, tool integration, and hybrid retrieval. Below are practical scenarios that demonstrate how the system operates in everyday municipal contexts:
A resident asks: “How much do I owe on my water bill?”
The query is routed to the Billing Agent.
The agent retrieves account data from ChromaDB and structured billing records.
If records are incomplete, it scrapes the council’s billing portal for live updates.
The agent responds with the exact balance and offers a payment form via the form generation tool.
A citizen reports: “There’s a burst pipe near my street.”
The query is classified and routed to the Incident Agent.
The agent logs the incident, generates a structured report form, and dispatches it via the email tool to the relevant department.
The citizen receives confirmation and a reference number for follow‑up.
A business owner asks: “How do I apply for a shop licence?”
The query is routed to the Licensing Agent.
The agent retrieves licensing requirements from structured data and council bylaws.
It provides a downloadable application form and guides the user through submission steps.
The agent can also calculate fees using the math tool.
A resident asks: “What are the council office hours?”
The query is routed to the General Assistant.
The agent retrieves the information from ChromaDB or scrapes the council’s website if updates are needed.
The citizen receives accurate, real‑time office hours without needing to visit in person.
The Masvingo Civic Multi-Agent Assistant is built for scalable, intelligent, and production-grade deployment. Below is a condensed overview of its implementation pillars:
LangGraph-powered routing to four specialized agents: Billing, Licensing, Incident, and General.
Dynamic classification via keywords and fallback handling for unknown queries.
🧠 Retrieval & Intelligence
Hybrid RAG system combining ChromaDB semantic search with real-time web scraping.
Contextual responses enriched by structured data and live municipal content.
Backend: Python Flask with RESTful APIs
AI/ML: Groq API, Sentence Transformers
Data: BeautifulSoup, ReportLab, ChromaDB, JSON
Orchestration: LangGraph for multi-agent workflows
Tool-enhanced agents for form generation, email dispatch, and math tasks
24/7 availability via responsive web interface
Real-time updates from automated web scraping
Scalable design supporting new agents and services
Error handling, input validation, and structured logging
Lazy loading, caching, and background processing for speed
Monitoring-ready with resource-efficient architecture
Plugin-ready architecture with configuration-driven behavior
Multi-language support and RESTful API integration
Unit and integration tests, mock services, and continuous validation
The Masvingo Civic Multi-Agent Assistant introduces a transformative approach to municipal service delivery by combining intelligent orchestration, hybrid retrieval, and tool-enhanced execution. Unlike traditional chatbots or static portals, this system leverages LangGraph to route queries to specialized agents—each equipped with domain-specific prompts and functional tools. Its hybrid RAG architecture blends semantic search with real-time web scraping, ensuring responses are both accurate and current. Agents don’t just answer questions—they perform tasks: generating forms, dispatching emails, calculating fees, and retrieving live council data.
This innovation under real hypothesis will directly addresses Masvingo’s civic pain points: 'long queues', 'outdated information', and 'administrative bottlenecks'. By automating routine inquiries and enabling 24/7 access to municipal services, the assistant reduces physical congestion, improves staff efficiency, and empowers citizens with instant, actionable support. Early testing will show over 85% query routing accuracy, sub-3 second response times, and an estimated 60% reduction in support ticket volume—clear indicators of both technical robustness and social impact.
The Masvingo Civic Multi‑Agent Assistant is designed as a living system, evolving to meet the growing needs of citizens and municipal administrators. The roadmap below outlines key milestones that will expand functionality, accessibility, and integration:
Introduce secure authentication and personalized accounts. This will allow controlled experiments, history tracking, and tailored experiences for different user groups, ensuring data privacy and adaptive learning.
Deploy the assistant on a lightweight, zero‑data access platform. Citizens will be able to use the system without consuming mobile data, making civic services more inclusive and accessible to all residents.
Connect directly to municipal databases for billing, licensing, and incident records. This will enable agents to provide authoritative, real‑time responses and reduce reliance on manual updates or scraping.
Leverage Anthropic’s Model Context Protocol (MCP) server to enhance interoperability. This will allow the assistant to collaborate seamlessly with external AI systems, expanding its reasoning and service capabilities.
Embed secure payment gateways for bills and fees. Citizens will be able to check balances and complete transactions directly within the assistant, streamlining service delivery and reducing queues.
The following resources provide supporting material, references, and tools for understanding and extending the Masvingo Civic Multi‑Agent Assistant:
GitHub Repository – Source code, README, and annotated examples for developers.
Architecture Diagrams – Visuals explaining system flow, agent orchestration, and retrieval layers.
Configuration Files – YAML prompts and settings for customization.
LangGraph Documentation – Workflow orchestration and multi‑agent routing.
ChromaDB – Vector database for semantic search.
Sentence Transformers – Embedding models for contextual retrieval.
BeautifulSoup – Web scraping library for live municipal data.
ReportLab – PDF generation for licensing and billing forms.
Masvingo City Council Website – Official notices, bylaws, and service updates.
Zimbabwe Civic Tech Reports – Background on digital transformation in municipal services.
Ready Tensor Publication – Extended write‑up of the Council Query Assistant baseline.
Tutorials – Step‑by‑step guides for deploying agents and integrating tools.
Use Case Examples – Billing, incident reporting, licensing, and general civic queries.
Deployment Guides – Virtual environment setup, environment configs, and monitoring integration.
