# huiel/grag architecture

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

- Interactive diagram: https://gitdiagram.com/huiel/grag
- Repository: https://github.com/huiel/grag

## Overview

##### File structure
- Top-level scripts and orchestration:
- train.py / inference.py / run.sh
- requirements.txt / LICENSE.txt
- Data layer:
- dataset/ (raw TSVs & WebQSP data + preprocessing)
- src/dataset/ (data loaders, preprocess modules for expla_graphs and webqsp)
- Model layer:
- src/model/gnn.py (graph encoder / retrieval model)
- src/model/graph_llm.py (Graph-LLM integration)
- src/model/llm.py (vanilla LLM wrapper and LoRA fine-tuning)
- Utilities:
- src/utils/ (checkpointing, config parsing, collate functions, evaluation, split-generation, retrieval helpers, scheduling, seeding, text-to-graph conversion)

##### README for additional insights
- Describes two main stages:
- Reference figures: “intro.png” (motivation) and “flow.png” (pipeline).

##### Main components & relationships
a. **Dataset & Preprocessing**
- Raw data (expla_graphs.tsv, WebQSP JSON/TSV) → Preprocessing modules → Serialized graph+text pairs
b. **Graph Retrieval Engine**
c. **Language Model Module**
- Optionally LoRA adapter for fine-tuning
d. **Training Orchestrator**
- Batches from DataLoader → Forward through GNN retriever & LLM → Loss calculation → Optimizer & LR scheduler → Checkpointing
e. **Inference Pipeline**
- Query input → Graph Retrieval → LLM generation → Output answer
f. **Supporting Utilities**
- Configuration loader, checkpoint manager, evaluator, collate & sampler, seed management, training split generator

##### Architectural patterns / design principles
- Strict separation of concerns (dataset vs. model vs. utils)
- Modular pipeline stages (preprocess → retrieve → generate → evaluate)
- Pluggable LLM backends (frozen vs. fine-tuned via LoRA)
- Decoupled retrieval (GNN) and generation (LLM) components

##### Detail
- Every essential module (all src/dataset/*, src/model/*, src/utils/*)
- How train.py ties everything together via config files and run.sh
- Evaluation and checkpoint paths back into the storage layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData["Dataset (Raw Data)"]:::data
        Preprocessing["Preprocessing Modules"]:::data
        DataLoader["DataLoader & Dataset Interface"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        GNN["GNN Retriever (src/model/gnn.py)"]:::model
        GraphLLM["Graph-LLM Integration (src/model/graph_llm.py)"]:::model
        LLM["LLM Wrapper & LoRA (src/model/llm.py)"]:::model
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Config["Config Loader (src/utils/config.py)"]:::util
        Ckpt["Checkpoint Manager (src/utils/ckpt.py)"]:::util
        Collate["Batch Collation (src/utils/collate.py)"]:::util
        Sampler["Data Sampler (src/utils/sampler.py)"]:::util
        LRScheduler["LR Scheduler (src/utils/lr_schedule.py)"]:::util
        Seed["Seed Management (src/utils/seed.py)"]:::util
        SplitGen["Split Generator (src/utils/generate_split.py)"]:::util
        Evaluate["Evaluation (src/utils/evaluate.py)"]:::util
        GraphRetrieval["Retrieval Helpers (src/utils/graph_retrieval.py)"]:::util
        TextGraph["Text-Graph Conversion (src/utils/text_graph.py)"]:::util
        LMModeling["LM Modeling Utils (src/utils/lm_modeling.py)"]:::util
    end

    %% Orchestration Scripts
    subgraph "Orchestration"
        direction TB
        Train["train.py"]:::orch
        Run["run.sh"]:::orch
        Inference["inference.py"]:::orch
        QueryInput["Query Input"]:::orch
        Output["Answer Output"]:::orch
    end

    %% Data Flow
    RawData -->|"raw TSV/JSON"| Preprocessing
    Preprocessing -->|"serialized graph+text"| DataLoader
    DataLoader -->|"batches"| GNN
    GNN -->|"top-k subgraphs"| GraphLLM
    GraphLLM -->|"graph-aware prompt"| LLM

    %% Training Flow
    Train -->|uses| DataLoader
    Train -->|uses| GNN
    Train -->|uses| LLM
    Train -->|loads| Config
    Train -->|saves| Ckpt
    Train -->|uses| Collate
    Train -->|uses| Sampler
    Train -->|uses| LRScheduler
    Train -->|uses| Seed
    Train -->|uses| SplitGen
    Train -->|evaluates| Evaluate

    %% Inference Flow
    QueryInput -->|"query"| GNN
    GNN -->|"subgraphs"| GraphLLM
    GraphLLM -->|"prompt"| LLM
    LLM -->|"answer"| Output
    Inference -->|invokes| QueryInput
    Inference -->|produces| Output
    Inference -->|uses| Config
    Inference -->|uses| Ckpt
    Inference -->|uses| GraphRetrieval
    Inference -->|uses| TextGraph
    Inference -->|uses| LMModeling

    %% Script orchestration
    Run -->|runs| Train
    Run -->|runs| Inference

    %% Click Events
    click RawData "https://github.com/huiel/grag/tree/main/dataset/"
    click Preprocessing "https://github.com/huiel/grag/tree/main/src/dataset/"
    click DataLoader "https://github.com/huiel/grag/blob/main/src/dataset/__init__.py"
    click GNN "https://github.com/huiel/grag/blob/main/src/model/gnn.py"
    click GraphLLM "https://github.com/huiel/grag/blob/main/src/model/graph_llm.py"
    click LLM "https://github.com/huiel/grag/blob/main/src/model/llm.py"
    click Train "https://github.com/huiel/grag/blob/main/train.py"
    click Run "https://github.com/huiel/grag/blob/main/run.sh"
    click Inference "https://github.com/huiel/grag/blob/main/inference.py"
    click Config "https://github.com/huiel/grag/blob/main/src/utils/config.py"
    click Ckpt "https://github.com/huiel/grag/blob/main/src/utils/ckpt.py"
    click Collate "https://github.com/huiel/grag/blob/main/src/utils/collate.py"
    click Sampler "https://github.com/huiel/grag/blob/main/src/utils/sampler.py"
    click LRScheduler "https://github.com/huiel/grag/blob/main/src/utils/lr_schedule.py"
    click Seed "https://github.com/huiel/grag/blob/main/src/utils/seed.py"
    click SplitGen "https://github.com/huiel/grag/blob/main/src/utils/generate_split.py"
    click Evaluate "https://github.com/huiel/grag/blob/main/src/utils/evaluate.py"
    click GraphRetrieval "https://github.com/huiel/grag/blob/main/src/utils/graph_retrieval.py"
    click TextGraph "https://github.com/huiel/grag/blob/main/src/utils/text_graph.py"
    click LMModeling "https://github.com/huiel/grag/blob/main/src/utils/lm_modeling.py"

    %% Styles
    classDef data fill:#a2fca8,stroke:#333,stroke-width:1px
    classDef model fill:#85adff,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef orch fill:#ffc47c,stroke:#333,stroke-width:1px
```
