rishiraj1994/utilityflowai

Purpose and entry points

UtilityFlow AI is a Python/Streamlit copilot for querying UK utility regulations, MHHS artefacts, D-Flows, and Excel mappings with grounded RAG responses. The interactive entry point is app.py; offline knowledge-base ingestion is driven by build_knowledge_base.py. Its source corpus is local PDFs and spreadsheets under data/pdfs/ and data/excel/.

UI and copilot orchestration

The application layer accepts user questions, maintains conversational interaction, and presents formatted answers with source attribution. modules/chatbot.py and modules/copilot.py are the central application-facing orchestration layer, while modules/conversation_state.py holds session/history state and modules/response_formatter.py shapes the final response.

Query understanding and routing

Questions are parsed for utility-specific entities such as D-Flows, methods, DES documents, and REC references, then classified/routed to the appropriate retrieval or agent path. Key boundaries are modules/query_parser.py, modules/intent_classifier.py, and modules/query_router.py. Entity normalization and document-type recognition are handled by modules/entity_resolver.py and modules/document_classifier.py.

Knowledge-base ingestion

The batch build path loads heterogeneous regulatory sources, extracts/chunks content, generates embeddings, and persists searchable representations. PDFs enter through modules/pdf_loader.py; spreadsheets through modules/excel_loader.py; chunking is centralized in modules/chunker.py. Embedding/vector persistence is represented by modules/embeddings.py and modules/vector_store.py.

Hybrid retrieval pipeline

A question is expanded or rewritten as needed, then searched across PDF semantic content and structured Excel content. modules/retrieval_orchestrator.py coordinates this flow; modules/retrieval/pdf_retriever.py and modules/retrieval/excel_retriever.py form the source-specific retrieval boundary. Results are combined and ranked through modules/retrieval/result_merger.py, modules/reranker.py, and the higher-level modules/retrieval_engine.py.

Context generation and LLM boundary

Retrieved evidence is transformed into constrained prompt context before answer generation, separating source retrieval from model output. modules/context_builder.py assembles supporting passages, modules/prompt_builder.py creates the model prompt, and modules/llm.py encapsulates the OpenAI/Azure OpenAI-facing generation integration. The stated runtime stack includes Python 3.11, Streamlit, LangChain, ChromaDB, HuggingFace embeddings, and Pandas.

Graph and specialist-agent capabilities

The repository also contains a utility relationship-graph path for dependency/impact exploration, plus specialist agents for D-Flows, Excel, regulations, comparisons, and graph questions. Graph construction, persistence, and querying reside in modules/graph/graph_builder.py, modules/graph/graph_loader.py, and modules/graph/graph_search.py, with a serialized graph at graph_db/utility_graph.pkl. Agent coordination is centered on modules/agents/coordinator.py, with domain handlers such as modules/agents/dflow_agent.py and modules/agents/graph_agent.py.