# cmavro/gnn-rag architecture

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

- Interactive diagram: https://gitdiagram.com/cmavro/gnn-rag
- Repository: https://github.com/cmavro/gnn-rag

## Overview

##### Project Type & Purpose
- A research‐oriented KGQA system combining:
- GNN pipeline (“gnn/”) to retrieve answer nodes & reasoning paths over a knowledge graph
- RAG pipeline (“llm/”) to verbalize paths and query LLMs for final answers

##### File Structure Overview
- gnn/: data loading, model definitions (GraftNet, NSM, ReaRev), training/evaluation scripts
- llm/: prompt templates, results storage, scripts, and a modular Python package:
– align_kg, joint_training, qa_prediction, llms (language model abstractions), utils

##### Key Architectural Patterns
- Pipeline pattern: sequential stages from data → GNN inference → prompt construction → LLM call → evaluation
- Modular design: clear separation of GNN vs. LLM concerns; pluggable encoders & GNN variants; abstract LLM interface

##### Main Components
- Data Loader (KG + QA dataset)
- GNN Engine
- Submodules: question encoder, KG reasoner, model zoo
- Retrieval Output (answer nodes + paths)
- Verbalizer / Prompt Builder
- LLM Client
- pluggable backends (ChatGPT, LLaMA, Flan‐T5, etc.)
- Evaluator & Results Store

##### Relationships & Data Flow
- Optional branches: training vs. inference; joint_training/align_kg sub-pipelines

##### Technologies & Frameworks
- Python, PyTorch (GNNs), HuggingFace transformers, FastChat API
- Shell scripts for orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion"
        DL["Data Loader"]:::gnn
    end

    subgraph "GNN Engine"
        GE["GNN Engine"]:::gnn
        subgraph "Question Encoder"
            Enc1["Base Encoder"]:::gnn
            Enc2["BERT Encoder"]:::gnn
            Enc3["LSTM Encoder"]:::gnn
        end
        subgraph "KG Reasoner"
            Reasoner1["Base GNN"]:::gnn
            Reasoner2["Graft GNN"]:::gnn
            Reasoner3["NSM GNN"]:::gnn
            Reasoner4["ReaRev GNN"]:::gnn
        end
        subgraph "Model Zoo"
            M1["GraftNet"]:::gnn
            M2["NSM"]:::gnn
            M3["ReaRev"]:::gnn
            M4["Base Model"]:::gnn
        end
    end

    RO["Retrieval Output"]:::gnn
    PV["Prompt Builder"]:::llm
    LLM["LLM Client"]:::llm
    Eval["Evaluator & Results Store"]:::llm

    DL -->|"kg+qa data"| GE
    GE -->|"nodes+paths"| RO
    RO -->|"paths"| PV
    PV -->|"prompt"| LLM
    LLM -->|"predictions"| Eval

    click DL "https://github.com/cmavro/gnn-rag/blob/main/gnn/dataset_load.py"
    click DL "https://github.com/cmavro/gnn-rag/blob/main/gnn/dataset_load_graft.py"
    click DL "https://github.com/cmavro/gnn-rag/blob/main/llm/src/align_kg/data_loader.py"
    click GE "https://github.com/cmavro/gnn-rag/blob/main/gnn/main.py"
    click GE "https://github.com/cmavro/gnn-rag/blob/main/gnn/train_model.py"
    click Enc1 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/question_encoding/base_encoder.py"
    click Enc2 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/question_encoding/bert_encoder.py"
    click Enc3 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/question_encoding/lstm_encoder.py"
    click Reasoner1 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/kg_reasoning/base_gnn.py"
    click Reasoner2 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/kg_reasoning/graft_gnn.py"
    click Reasoner3 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/kg_reasoning/nsm_gnn.py"
    click Reasoner4 "https://github.com/cmavro/gnn-rag/blob/main/gnn/modules/kg_reasoning/reasongnn.py"
    click M1 "https://github.com/cmavro/gnn-rag/blob/main/gnn/models/GraftNet/graftnet.py"
    click M2 "https://github.com/cmavro/gnn-rag/blob/main/gnn/models/NSM/nsm.py"
    click M3 "https://github.com/cmavro/gnn-rag/blob/main/gnn/models/ReaRev/rearev.py"
    click M4 "https://github.com/cmavro/gnn-rag/blob/main/gnn/models/base_model.py"
    click RO "https://github.com/cmavro/gnn-rag/blob/main/gnn/evaluate.py"
    click RO "https://github.com/cmavro/gnn-rag/blob/main/gnn/utils.py"
    click PV "https://github.com/cmavro/gnn-rag/blob/main/llm/prompts/alpaca.txt"
    click PV "https://github.com/cmavro/gnn-rag/blob/main/llm/prompts/general_prompt.txt"
    click PV "https://github.com/cmavro/gnn-rag/blob/main/llm/prompts/llama2.txt"
    click PV "https://github.com/cmavro/gnn-rag/blob/main/llm/prompts/llama2_predict.txt"
    click PV "https://github.com/cmavro/gnn-rag/blob/main/llm/src/qa_prediction/build_qa_input.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/llm_proxy.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/start_fastchat_api.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/language_models/base_language_model.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/language_models/chatgpt.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/language_models/llama.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/language_models/flan_t5.py"
    click LLM "https://github.com/cmavro/gnn-rag/blob/main/llm/src/llms/language_models/alpaca.py"
    click LLM "https://github.com/cmavro/gnn-rag/tree/main/llm/src/llms/language_models/longchat/"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/qa_prediction/predict_answer.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/qa_prediction/gen_rule_path.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/qa_prediction/evaluate_multi_hop.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/qa_prediction/evaluate_results.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/align_kg/build_align_qa_dataset.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/joint_training/joint_finetuning.py"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/src/joint_training/generate_explanation_results.py"
    click Eval "https://github.com/cmavro/gnn-rag/tree/main/llm/results/"
    click Eval "https://github.com/cmavro/gnn-rag/blob/main/llm/scripts/evaluate_multi_hop.sh"

    classDef gnn fill:#B3CDE3,stroke:#03396c,color:#03396c
    classDef llm fill:#FBB4AE,stroke:#b10026,color:#b10026
```
