# supermedintel/medical-graph-rag architecture

> Architecture diagram of the GitHub repository supermedintel/medical-graph-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supermedintel/medical-graph-rag
- Repository: https://github.com/supermedintel/medical-graph-rag

## Overview

##### Project Type and Purpose
- This is a specialized graph Retrieval-Augmented Generation (RAG) system for the medical domain.
- It leverages a multi-agent pipeline (inherited largely from the CAMEL framework) to integrate language models (LLMs) and graph data – specifically, it constructs and queries graphs built on datasets such as MIMIC, MedC-K, and UMLS.
- The project supports two modes: a simple baseline RAG implementation and a full-scale “build from scratch” Graph RAG pipeline that constructs the hierarchy of graphs and augments LLM inference through retrieval.

##### Analyzing the File Structure
- At a high level, the repository contains several standalone scripts (run.py, creat_graph.py, cleangraph.py) and configuration files (medgraphrag.yml, Dockerfile, etc.) used for deployment.
- A very large “camel” directory indicates that the system relies on a robust modular framework. This directory is organized with submodules for agents, configurations, embeddings, interpreters, loaders, memories, models, retrievers, storages, toolkits, and a workforce that orchestrates multi-agent behavior.
- There is also a smaller “nano_graphrag” module that likely provides a simplified or alternative pipeline for graph tasks.
- Other files (MedicalBook.xlsx, git_push.sh, etc.) indicate data sources and deployment automation scripts.

##### Architectural Components to Capture
a. Data Ingestion and Pre-Processing:
- Components: dataloader.py, loaders (in camel/loaders) and data_chunk.py.
- Purpose: Read and pre-process heterogeneous data sources including patient records (MIMIC), medical textbooks, and UMLS–like dictionaries.
b. Graph Construction:
- Components: creat_graph.py, cleangraph.py, nanographrag modules; and parts from storages (especially camel/storages/graph_storages and key_value_storages).
- Purpose: Convert raw text data into structured graph representations, supporting multi-grained levels (top-level, medium-level, and bottom-level).
c. Graph Storage and Database Integration:
- Components: Modules interacting with Neo4j are indicated in the README’s environment variables (NEO4J_URL, etc.), as well as relevant code under storages (e.g., neo4j_graph.py).
- Purpose: Persist and manage the knowledge graphs so they can be queried during inference.
d. Retrieval and Querying:
- Components: Camel retrievers (auto_retriever.py, bm25_retriever.py, vector_retriever.py) and memory blocks (chat_history_block.py, vectordb_block.py).
- Purpose: Efficiently search and extract relevant information from the stored graphs using various retrieval strategies.
e. LLM and Model Inference:
- Components: Modules in camel/models (e.g., openai_model.py, mistral_model.py) and prompt handling via camel/prompts.
- Purpose: Process natural language queries, generate responses, and augment answers using LLMs. The integration with external APIs (OpenAI, ChatGPT, etc.) is also evident.
f. Agent and Multi-Agent Orchestration:
- Components: Many files under camel/agents and workforce (agentic_chunker.py, workforce modules, task_agent.py etc.).
- Purpose: Coordinate different agents that handle task execution, role assignment, search, deduction, and tools orchestration, making the system a dynamic multi-agent pipeline.
g. Toolkits and External Integrations:
- Components: A variety of toolkits (google_maps_toolkit, github_toolkit, search_toolkit, etc.) and open API specs.
- Purpose: Extend the system with external functionalities (e.g., leveraging public APIs or additional tools), which is especially useful when processing or accessing non-local data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Source
    DATA["Raw Medical Data"]:::source

    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        DL["Data Loader"]:::ingestion
        DC["Data Chunk"]:::ingestion
        L["Loaders"]:::ingestion
    end

    %% Graph Construction Layer
    subgraph "Graph Construction Layer"
        GC["Graph Creator"]:::construction
        GCL["Graph Cleaner"]:::construction
        NR["Nano RAG"]:::construction
    end

    %% Graph Storage Layer
    subgraph "Graph Storage Layer"
        NS["Neo4j Storage"]:::storage
        KVS["Key-Value Storage"]:::storage
    end

    %% External Graph Database
    GDB["Graph Database (Neo4j)"]:::external

    %% Retrieval Layer
    subgraph "Retrieval Layer"
        RM["Retriever Modules"]:::retrieval
        RF["Retrieve Function"]:::retrieval
        MB["Memory Blocks"]:::retrieval
    end

    %% LLM Inference Layer
    subgraph "LLM Inference Layer"
        MI["Model Inference"]:::inference
        PH["Prompt Handling"]:::inference
    end

    %% External LLM Service
    LLM["LLM Service"]:::external

    %% Agent Orchestration
    subgraph "Agent Orchestration"
        AM["Agent Modules"]:::agent
        WF["Workforce"]:::agent
    end

    %% Toolkits and External Integrations
    subgraph "Toolkits & External Integrations"
        TK["Toolkits"]:::toolkit
    end

    %% Data Flow Connections
    DATA --> DL
    DL --> DC
    DC --> L

    L --> GC
    GC --> GCL
    GCL --> NR

    NR --> NS
    NS --> KVS
    NS --> RM
    KVS --> RM

    RM --> RF
    RM --> MB
    RF --> MI
    MB --> MI

    MI --> PH
    PH --> LLM

    %% Feedback loop between LLM Inference and Agent Orchestration
    MI --> AM
    MI --> WF
    AM --> MI
    WF --> MI

    %% Integration with Toolkits
    AM --> TK
    WF --> TK

    %% Storage integration with External Graph Database
    NS --> GDB
    GDB --> NS

    %% Click Events
    click DL "https://github.com/supermedintel/medical-graph-rag/blob/main/dataloader.py"
    click DC "https://github.com/supermedintel/medical-graph-rag/blob/main/data_chunk.py"
    click L "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/loaders"
    click GC "https://github.com/supermedintel/medical-graph-rag/blob/main/creat_graph.py"
    click GCL "https://github.com/supermedintel/medical-graph-rag/blob/main/cleangraph.py"
    click NR "https://github.com/supermedintel/medical-graph-rag/tree/main/nano_graphrag"
    click NS "https://github.com/supermedintel/medical-graph-rag/blob/main/camel/storages/graph_storages/neo4j_graph.py"
    click KVS "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/storages/key_value_storages"
    click RM "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/retrievers"
    click RF "https://github.com/supermedintel/medical-graph-rag/blob/main/retrieve.py"
    click MB "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/memories/blocks"
    click MI "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/models"
    click PH "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/prompts"
    click AM "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/agents"
    click WF "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/workforce"
    click TK "https://github.com/supermedintel/medical-graph-rag/tree/main/camel/toolkits"

    %% Class Definitions for colors
    classDef source fill:#FFDDC1,stroke:#333,stroke-width:2px;
    classDef ingestion fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef construction fill:#C1FFC1,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef retrieval fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef inference fill:#E6CCFF,stroke:#333,stroke-width:2px;
    classDef agent fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef toolkit fill:#FCE5CD,stroke:#333,stroke-width:2px;
    classDef external fill:#F8CECC,stroke:#333,stroke-width:2px;
```
