# nicoladisabato/multiagenticrag architecture

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

- Interactive diagram: https://gitdiagram.com/nicoladisabato/multiagenticrag
- Repository: https://github.com/nicoladisabato/multiagenticrag

## Overview

1. **Overall purpose**
   - This repository implements a **multi-agent RAG system** for answering questions from a specific source document: the Google 2024 environmental report PDF.
   - The architecture is centered on **LangGraph**, so the system is organized as a set of small stateful workflows rather than a single monolithic chat loop.

2. **Two-phase workflow**
   - The repo has a clear split between:
     - **Offline document ingestion/indexing**
     - **Online question answering**
   - First, the PDF is processed and loaded into a retrieval store.
   - Then the application runs a graph-based agent pipeline that retrieves relevant evidence and generates answers.

3. **Entry points**
   - `retriever/retriever.py` is the ingestion entry point. It loads the PDF, chunks/processes it, and writes it into the retrieval layer.
   - `app.py` is the runtime entry point for the interactive QA application.
   - `config.yaml` controls behavior such as whether documents should be loaded into the index.

4. **Retrieval subsystem**
   - The `retriever/` package contains the source document and the ingestion logic.
   - Its role is to convert the PDF into retrievable units, likely embedding them and storing them in a vector-backed index used later by the graph.
   - This is a prerequisite step before the app can answer questions reliably.

5. **Main orchestration graph**
   - `main_graph/` contains the top-level LangGraph workflow that coordinates the full RAG process.
   - `main_graph/graph_builder.py` likely defines the nodes, edges, and routing logic for the primary agent loop.
   - `main_graph/graph_states.py` defines the shared state object passed through the workflow, which is how intermediate results move between steps.

6. **Subgraph for specialized reasoning**
   - `subgraph/` is a second LangGraph workflow used as a nested or delegated component.
   - `subgraph/graph_builder.py` and `subgraph/graph_states.py` suggest a reusable focused agent flow for a narrower task such as retrieval refinement, verification, or correction.
   - This structure indicates the project uses **hierarchical agent composition** rather than a single flat pipeline.

7. **Utility layer**
   - `utils/` contains shared support code.
   - `utils/prompt.py` likely stores prompt templates for the different agents and graph nodes.
   - `utils/utils.py` probably holds helper functions for formatting, document handling, retrieval calls, or graph support logic.
   - This keeps prompt logic and shared helpers separate from orchestration code.

8. **Quality-control behavior**
   - The README says the system includes **error correction and hallucination checks**.
   - Architecturally, that means the answer path is not just “retrieve then generate”; it includes validation or feedback steps that can revise outputs before returning them.
   - That makes the graph more like a controlled reasoning pipeline than a simple RAG chain.

9. **Data flow**
   - The data flow is: **PDF source → retriever ingestion → indexed document store → query enters app → main graph routes the task → retrieval happens → subgraph or verification step may refine results → final answer returned to the user**.
   - The key boundary is between offline document preparation and online runtime inference.

10. **Primary architectural boundaries**
   - **Source data boundary:** the environmental report PDF.
   - **Indexing boundary:** retrieval/index creation in `retriever/`.
   - **Orchestration boundary:** top-level reasoning in `main_graph/`.
   - **Specialized reasoning boundary:** nested workflow in `subgraph/`.
   - **Shared configuration/prompt boundary:** `config.yaml` and `utils/`.

11. **Runtime and tooling**
   - The project is Python-based and depends on the packages in `requirements.txt`.
   - LangGraph is the core orchestration technology.
   - The workflow is designed to run locally: preprocess once, then launch the app and query the indexed report.

12. **How to draw the architecture**
   - A good diagram would show:
     - A **document ingestion lane** on the left
     - A **retrieval/index store** in the middle
     - A **graph-based agent runtime** on the right
     - A **nested subgraph** inside the runtime for specialized checking or refinement
     - Shared **prompt/config utilities** feeding both ingestion and runtime where needed
   - The central design idea is a **multi-agent, stateful, retrieval-augmented pipeline** built around one report and optimized for trustworthy answers.

Main entry points: [`main_graph/graph_builder.py`](https://github.com/nicoladisabato/multiagenticrag/blob/main/main_graph/graph_builder.py) (Main Graph), [`subgraph/graph_builder.py`](https://github.com/nicoladisabato/multiagenticrag/blob/main/subgraph/graph_builder.py) (Subgraph), [`retriever/retriever.py`](https://github.com/nicoladisabato/multiagenticrag/blob/main/retriever/retriever.py) (Ingestor), [`utils/utils.py`](https://github.com/nicoladisabato/multiagenticrag/blob/main/utils/utils.py) (Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source & Ingestion"]
  node_retriever_pdf["Report PDF<br/>source document"]
  node_retriever_entry["Ingestor<br/>ingestion pipeline<br/>[retriever.py]"]
  node_index_store[("Index Store<br/>retrieval index")]
end

subgraph group_runtime["QA Runtime"]
  node_app_entry["App Entry<br/>runtime entrypoint<br/>[app.py]"]
  node_main_builder{{"Main Graph<br/>LangGraph workflow<br/>[graph_builder.py]"}}
  node_main_state["Main State<br/>workflow state<br/>[graph_states.py]"]
  node_sub_builder{{"Subgraph<br/>nested workflow<br/>[graph_builder.py]"}}
  node_sub_state["Sub State<br/>workflow state<br/>[graph_states.py]"]
end

subgraph group_shared["Shared Support"]
  node_config["Config<br/>[config.yaml]"]
  node_prompt_utils["Prompts<br/>prompt templates<br/>[prompt.py]"]
  node_helper_utils["Helpers<br/>shared utilities<br/>[utils.py]"]
end

node_config -->|"enable load"| node_retriever_entry
node_retriever_pdf -->|"source text"| node_retriever_entry
node_retriever_entry -->|"build index"| node_index_store
node_config -->|"configure runtime"| node_app_entry
node_app_entry -->|"start graph"| node_main_builder
node_main_builder -->|"uses state"| node_main_state
node_main_builder -->|"retrieve evidence"| node_index_store
node_main_builder -->|"delegate step"| node_sub_builder
node_sub_builder -->|"uses state"| node_sub_state
node_sub_builder -->|"helper logic"| node_helper_utils
node_main_builder -->|"prompts"| node_prompt_utils
node_sub_builder -->|"prompts"| node_prompt_utils
node_main_builder -->|"helpers"| node_helper_utils
node_retriever_entry -->|"preprocess"| node_helper_utils

click node_retriever_pdf "https://github.com/nicoladisabato/multiagenticrag/blob/main/retriever/google-2024-environmental-report.pdf"
click node_retriever_entry "https://github.com/nicoladisabato/multiagenticrag/blob/main/retriever/retriever.py"
click node_app_entry "https://github.com/nicoladisabato/multiagenticrag/blob/main/app.py"
click node_main_builder "https://github.com/nicoladisabato/multiagenticrag/blob/main/main_graph/graph_builder.py"
click node_main_state "https://github.com/nicoladisabato/multiagenticrag/blob/main/main_graph/graph_states.py"
click node_sub_builder "https://github.com/nicoladisabato/multiagenticrag/blob/main/subgraph/graph_builder.py"
click node_sub_state "https://github.com/nicoladisabato/multiagenticrag/blob/main/subgraph/graph_states.py"
click node_config "https://github.com/nicoladisabato/multiagenticrag/blob/main/config.yaml"
click node_prompt_utils "https://github.com/nicoladisabato/multiagenticrag/blob/main/utils/prompt.py"
click node_helper_utils "https://github.com/nicoladisabato/multiagenticrag/blob/main/utils/utils.py"

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_retriever_pdf,node_retriever_entry,node_index_store toneBlue
class node_app_entry,node_main_builder,node_main_state,node_sub_builder,node_sub_state toneAmber
class node_config,node_prompt_utils,node_helper_utils toneMint
```

## Components

### Source & Ingestion

Document source and offline indexing flow.

- [Report PDF](https://github.com/nicoladisabato/multiagenticrag/blob/main/retriever/google-2024-environmental-report.pdf): source document · The Google 2024 environmental report that is indexed and queried. · `retriever/google-2024-environmental-report.pdf`
- [Ingestor](https://github.com/nicoladisabato/multiagenticrag/blob/main/retriever/retriever.py): ingestion pipeline · Loads, chunks, and writes the report into the retrieval layer. · `retriever/retriever.py`
- **Index Store**: retrieval index · Persistent retrieval-backed document store used at query time.

### QA Runtime

Interactive question-answering and graph orchestration.

- [App Entry](https://github.com/nicoladisabato/multiagenticrag/blob/main/app.py): runtime entrypoint · Launches the interactive QA application. · `app.py`
- [Main Graph](https://github.com/nicoladisabato/multiagenticrag/blob/main/main_graph/graph_builder.py): LangGraph workflow · Top-level orchestration graph for retrieval, reasoning, and answer generation. · `main_graph/graph_builder.py`
- [Main State](https://github.com/nicoladisabato/multiagenticrag/blob/main/main_graph/graph_states.py): workflow state · Shared state object passed through the main graph. · `main_graph/graph_states.py`
- [Subgraph](https://github.com/nicoladisabato/multiagenticrag/blob/main/subgraph/graph_builder.py): nested workflow · Specialized delegated LangGraph flow for refinement or validation. · `subgraph/graph_builder.py`
- [Sub State](https://github.com/nicoladisabato/multiagenticrag/blob/main/subgraph/graph_states.py): workflow state · Shared state object for the nested subgraph. · `subgraph/graph_states.py`

### Shared Support

Configuration, prompts, and reusable helpers.

- [Config](https://github.com/nicoladisabato/multiagenticrag/blob/main/config.yaml): runtime config · Controls loading and runtime behavior such as indexing mode. · `config.yaml`
- [Prompts](https://github.com/nicoladisabato/multiagenticrag/blob/main/utils/prompt.py): prompt templates · Prompt templates used by agents and graph nodes. · `utils/prompt.py`
- [Helpers](https://github.com/nicoladisabato/multiagenticrag/blob/main/utils/utils.py): shared utilities · Common helper functions for formatting, retrieval, and graph support. · `utils/utils.py`

## Connections

- Config → Ingestor: enable load · Controls whether documents are ingested into the index.
- Report PDF → Ingestor: source text · The report is the raw input to offline ingestion.
- Ingestor → Index Store: build index · Creates or updates the retrieval layer.
- Config → App Entry: configure runtime · Provides runtime settings for the QA application.
- App Entry → Main Graph: start graph · Launches the main LangGraph workflow.
- Main Graph → Main State: uses state · The main workflow reads and updates shared state.
- Main Graph → Index Store: retrieve evidence · Queries the indexed report for supporting passages.
- Main Graph → Subgraph: delegate step · Routes specialized reasoning to the nested subgraph.
- Subgraph → Sub State: uses state · The subgraph maintains its own workflow state.
- Subgraph → Helpers: helper logic · Reuses shared utility functions during refinement.
- Main Graph → Prompts: prompts · Consumes prompt templates for agent behavior.
- Subgraph → Prompts: prompts · Uses shared prompts for specialized reasoning.
- Main Graph → Helpers: helpers · Uses shared support functions in the orchestration flow.
- Ingestor → Helpers: preprocess · May use shared helpers for document preparation.