# rishiraj1994/utilityflowai architecture

> Architecture diagram of the GitHub repository rishiraj1994/utilityflowai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rishiraj1994/utilityflowai
- Repository: https://github.com/rishiraj1994/utilityflowai

## Overview

#### 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`.

Main entry points: [`modules/chatbot.py`](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/chatbot.py) (Chat interface), [`modules/query_router.py`](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/query_router.py) (Query router), [`modules/retrieval/pdf_retriever.py`](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval/pdf_retriever.py) (PDF & Excel retrievers), [`modules/agents/coordinator.py`](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/agents/coordinator.py) (Specialist coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_ui["Streamlit app<br/>interactive entry point<br/>[app.py]"]
  node_copilot["Copilot orchestration<br/>application orchestrator<br/>[copilot.py]"]
  node_chatbot["Chat interface<br/>conversation handler<br/>[chatbot.py]"]
  node_conversation["Conversation state<br/>session state"]
  node_formatter["Response formatter<br/>presentation layer"]
end

subgraph group_ingestion["Knowledge Build"]
  node_build["Knowledge-base build<br/>batch entry point"]
  node_corpus["Regulatory source corpus<br/>PDF and spreadsheet files"]
  node_loaders["PDF &amp; Excel loaders<br/>source extraction<br/>[pdf_loader.py]"]
  node_chunker["Content chunker<br/>chunking pipeline<br/>[chunker.py]"]
  node_embeddings["Embeddings<br/>vector encoder<br/>[embeddings.py]"]
  node_vectors[("Vector store<br/>ChromaDB persistence<br/>[vector_store.py]")]
end

subgraph group_retrieval["Retrieval &amp; Generation"]
  node_query["Query understanding<br/>parse and classify<br/>[query_parser.py]"]
  node_router["Query router<br/>path router<br/>[query_router.py]"]
  node_retrieval["Retrieval orchestrator<br/>hybrid search coordinator"]
  node_source_retrievers["PDF &amp; Excel retrievers<br/>source retrieval<br/>[pdf_retriever.py]"]
  node_ranking["Merge &amp; rerank<br/>evidence ranking<br/>[result_merger.py]"]
  node_context["Context &amp; prompt builder<br/>grounded prompt assembly<br/>[context_builder.py]"]
  node_llm{{"LLM integration<br/>OpenAI/Azure boundary<br/>[llm.py]"}}
end

subgraph group_specialists["Graph &amp; Agents"]
  node_agents["Specialist coordinator<br/>agent dispatcher<br/>[coordinator.py]"]
  node_graph[("Utility relationship graph<br/>dependency graph search<br/>[graph_search.py]")]
  node_graph_data[("Serialized utility graph<br/>graph persistence<br/>[utility_graph.pkl]")]
end

node_ui -->|"questions"| node_chatbot
node_chatbot -->|"history"| node_conversation
node_chatbot -->|"requests"| node_copilot
node_copilot -->|"analyzes"| node_query
node_query -->|"intent and entities"| node_router
node_router -->|"retrieval path"| node_retrieval
node_router -->|"specialist path"| node_agents
node_retrieval -->|"hybrid search"| node_source_retrievers
node_source_retrievers -->|"semantic lookup"| node_vectors
node_source_retrievers -->|"evidence"| node_ranking
node_ranking -->|"ranked passages"| node_context
node_context -->|"grounded prompt"| node_llm
node_agents -->|"graph questions"| node_graph
node_graph -->|"loads"| node_graph_data
node_llm -->|"answer"| node_formatter
node_agents -->|"specialist result"| node_formatter
node_formatter -->|"formatted response"| node_ui
node_build -->|"ingests"| node_corpus
node_corpus -->|"PDFs and spreadsheets"| node_loaders
node_loaders -->|"extracted content"| node_chunker
node_chunker -->|"chunks"| node_embeddings
node_embeddings -->|"indexed vectors"| node_vectors

click node_ui "https://github.com/rishiraj1994/utilityflowai/blob/main/app.py"
click node_copilot "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/copilot.py"
click node_chatbot "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/chatbot.py"
click node_conversation "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/conversation_state.py"
click node_formatter "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/response_formatter.py"
click node_build "https://github.com/rishiraj1994/utilityflowai/blob/main/build_knowledge_base.py"
click node_loaders "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/pdf_loader.py"
click node_chunker "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/chunker.py"
click node_embeddings "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/embeddings.py"
click node_vectors "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/vector_store.py"
click node_query "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/query_parser.py"
click node_router "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/query_router.py"
click node_retrieval "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval_orchestrator.py"
click node_source_retrievers "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval/pdf_retriever.py"
click node_ranking "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval/result_merger.py"
click node_context "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/context_builder.py"
click node_llm "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/llm.py"
click node_agents "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/agents/coordinator.py"
click node_graph "https://github.com/rishiraj1994/utilityflowai/blob/main/modules/graph/graph_search.py"
click node_graph_data "https://github.com/rishiraj1994/utilityflowai/blob/main/graph_db/utility_graph.pkl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_copilot,node_chatbot,node_conversation,node_formatter toneBlue
class node_build,node_corpus,node_loaders,node_chunker,node_embeddings,node_vectors toneAmber
class node_query,node_router,node_retrieval,node_source_retrievers,node_ranking,node_context,node_llm toneMint
class node_agents,node_graph,node_graph_data toneRose
```

## Components

### Application

- [Streamlit app](https://github.com/rishiraj1994/utilityflowai/blob/main/app.py): interactive entry point · Accepts questions and renders attributed answers. · `app.py`
- [Copilot orchestration](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/copilot.py): application orchestrator · `modules/copilot.py`
- [Chat interface](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/chatbot.py): conversation handler · `modules/chatbot.py`
- [Conversation state](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/conversation_state.py): session state · `modules/conversation_state.py`
- [Response formatter](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/response_formatter.py): presentation layer · `modules/response_formatter.py`

### Knowledge Build

- [Knowledge-base build](https://github.com/rishiraj1994/utilityflowai/blob/main/build_knowledge_base.py): batch entry point · `build_knowledge_base.py`
- **Regulatory source corpus**: PDF and spreadsheet files
- [PDF & Excel loaders](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/pdf_loader.py): source extraction · `modules/pdf_loader.py`
- [Content chunker](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/chunker.py): chunking pipeline · `modules/chunker.py`
- [Embeddings](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/embeddings.py): vector encoder · `modules/embeddings.py`
- [Vector store](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/vector_store.py): ChromaDB persistence · `modules/vector_store.py`

### Retrieval & Generation

- [Query understanding](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/query_parser.py): parse and classify · Extracts utility entities and selects an intent. · `modules/query_parser.py`
- [Query router](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/query_router.py): path router · `modules/query_router.py`
- [Retrieval orchestrator](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval_orchestrator.py): hybrid search coordinator · `modules/retrieval_orchestrator.py`
- [PDF & Excel retrievers](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval/pdf_retriever.py): source retrieval · `modules/retrieval/pdf_retriever.py`
- [Merge & rerank](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/retrieval/result_merger.py): evidence ranking · `modules/retrieval/result_merger.py`
- [Context & prompt builder](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/context_builder.py): grounded prompt assembly · `modules/context_builder.py`
- [LLM integration](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/llm.py): OpenAI/Azure boundary · `modules/llm.py`

### Graph & Agents

- [Specialist coordinator](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/agents/coordinator.py): agent dispatcher · Coordinates D-Flow, Excel, regulation, comparison, and graph agents. · `modules/agents/coordinator.py`
- [Utility relationship graph](https://github.com/rishiraj1994/utilityflowai/blob/main/modules/graph/graph_search.py): dependency graph search · Persistent graph for relationship and impact exploration. · `modules/graph/graph_search.py`
- [Serialized utility graph](https://github.com/rishiraj1994/utilityflowai/blob/main/graph_db/utility_graph.pkl): graph persistence · `graph_db/utility_graph.pkl`

## Connections

- Streamlit app → Chat interface: questions
- Chat interface → Conversation state: history
- Chat interface → Copilot orchestration: requests
- Copilot orchestration → Query understanding: analyzes
- Query understanding → Query router: intent and entities
- Query router → Retrieval orchestrator: retrieval path
- Query router → Specialist coordinator: specialist path
- Retrieval orchestrator → PDF & Excel retrievers: hybrid search
- PDF & Excel retrievers → Vector store: semantic lookup
- PDF & Excel retrievers → Merge & rerank: evidence
- Merge & rerank → Context & prompt builder: ranked passages
- Context & prompt builder → LLM integration: grounded prompt
- Specialist coordinator → Utility relationship graph: graph questions
- Utility relationship graph → Serialized utility graph: loads
- LLM integration → Response formatter: answer
- Specialist coordinator → Response formatter: specialist result
- Response formatter → Streamlit app: formatted response
- Knowledge-base build → Regulatory source corpus: ingests
- Regulatory source corpus → PDF & Excel loaders: PDFs and spreadsheets
- PDF & Excel loaders → Content chunker: extracted content
- Content chunker → Embeddings: chunks
- Embeddings → Vector store: indexed vectors