Masvingo Civic Query Assistant is a prototype designed to improve transparency and accessibility of local government services. Built on a Retrieval-Augmented Generation (RAG) pipeline, it ingests council documents such as by-laws, water billing procedures, licensing forms, and public notices, then retrieves relevant information through semantic search. A language model generates grounded responses, while a lightweight Flask frontend provides residents with an intuitive interface. By reducing information gaps and minimizing hallucination, the assistant demonstrates how AI can empower communities to access accurate civic information and engage more effectively with council services.
The Council Query Assistant is implemented through a modular Retrieval-Augmented Generation (RAG) pipeline designed to minimize hallucination and ensure civic accuracy. The methodology consists of the following stages:
Document Ingestion – Official council documents (by-laws, water billing procedures, licensing forms, and public notices) are collected and stored in the data/ directory. This ensures the assistant is grounded in verified civic information.
Text Chunking – Documents are split into semantically coherent chunks using a custom parser. Chunking improves retrieval granularity, allowing the system to return precise sections of text rather than entire files.
Embedding & Vector Storage – Each chunk is embedded using a transformer-based model (e.g., sentence-transformers). The embeddings are stored in ChromaDB, a vector database chosen for its speed and scalability in similarity search.
Semantic Retrieval – User queries are converted into embeddings and matched against stored vectors. The system retrieves the most relevant chunks, ensuring that responses are contextually aligned with council documents.
Answer Generation – Retrieved context is passed to a language model (Groq or OpenAI). The model generates natural language responses that remain grounded in the retrieved civic data, reducing the risk of misinformation.
Frontend Integration – A lightweight Flask frontend provides an intuitive interface for residents. It includes a query input field, real-time display of answers, and an optional debug view showing retrieved chunks. Flask was chosen for its simplicity, rapid deployment, and accessibility to non-technical users.
This methodology ensures that the assistant delivers accurate, document-grounded answers while remaining modular and extensible for future enhancements, such as multi-agent orchestration and API integration.
This section assumes that you have basic knowledge of Python programming language and you have run some few scripts, if you are a beginner I will be hosting this application on the internet so that it's easy to use so don't worry
The first step toward installing this Query Assistant is by first opening clone the repository via your terminal opened in your preferred location and ran this command:
# Clone the repository git clone https://github.com/wakura-mitchell/Council-Query-Assistant.git cd Council-Query-Assistant
The cloned repository requires you to create and activate a virtual environment that we will use and install our dependences
we first create our environment using
# creating your virtual environment python -m venv your_environment_name
then we activate it using
# Activate the virtual environment python -m venv venv source venv/bin/activate # for Linux/Mac # OR venv\Scripts\activate # for Windows
You will find a requirement txt file in the repository which contains all the required library to run this system, to install them run:
# installing system requirents pip install -r requirements.txt
Place council .txt files (by-laws, licensing procedures, water billing, notices) in the data/ directory.
Ensure the .env file contains any required configuration (e.g., model provider, database path, Flask port).
This step embeds civic documents you have added above and stores them in ChromaDB for retrieval, here is the code to do that:
python build_index.py
The first step toward using this Query Assistant is by first opening in your Integrated Development Environment (IDE) open your terminal and run this command:
# Run the Flask application python app.py
Open your browser at: http://localhost:5000
Enter queries such as:
The assistant returns grounded answers based on council documents.
Debug mode (optional) shows retrieved chunks from ChromaDB.
Licensing: Guides users through shop licence applications.
Billing: Provides water bill payment procedures.
By-laws: Explains statutory regulations in plain language.
# Rerun the build index function in your terminal python build_index.py
Initial testing of the Council Query Assistant demonstrates strong alignment between user queries and retrieved civic content. The system consistently produces grounded responses with minimal hallucination, validating the effectiveness of the RAG pipeline.
Key Outcomes:
Licensing Workflows: The assistant successfully guides users through shop licence applications, referencing official council forms and procedures.
Water Billing Queries: Residents can check payment procedures and balances, with accurate retrieval from billing documents.
Incident Reporting: Queries about pipe bursts and service disruptions are logged and contextualized using council notices.
By-law Interpretation: The assistant provides clear explanations of statutory by-laws, improving public understanding of regulations.
Health Services: Access to information about council clinics and digital health records is supported through retrieved documentation.
Evidence of Performance:
Screenshots of the Flask frontend show real-time query handling (e.g., water billing, licensing, and by-law queries).
Welcome Screen – Masvingo RAG Assistant
System Prompt and Query Response
Multi-turn conversations demonstrate contextual relevance, where follow-up questions are answered accurately without losing context.
Query Example – Water Billing and Payments
Retrieval logs confirm that the system consistently selects the most relevant chunks from ChromaDB.
By making civic information searchable, conversational, and accessible, the assistant improves engagement between residents and council services. These results highlight the potential of AI-driven systems to reduce information gaps and empower communities. Future iterations will extend these capabilities into a multi-agent framework with specialized agents and tool integrations.
