# petergriffinjin/graph-cot architecture

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

- Interactive diagram: https://gitdiagram.com/petergriffinjin/graph-cot
- Repository: https://github.com/petergriffinjin/graph-cot

## Overview

##### Project type and purpose
- This is a research‐oriented, model‐centric codebase for “Graph Chain-of-Thought” (Graph-CoT), which augments large language models (LLMs) by letting them iteratively reason over graph-structured knowledge.
- It also provides baseline pipelines for off-the-shelf LLMs (in `LLM/`) and GPT models (in `GPT/`), plus data preprocessing (`data/`) and evaluation (`eval.*`).

##### File structure
- Top‐level folders:
- GPT/ – scripts & code to run GPT models (zero-shot, RAG).
- LLM/ – scripts & code to run open-source LLMs (zero-shot, RAG).
- Graph-CoT/ – core Graph-CoT framework: agent, prompts, tools, run script.
- data/ – raw and processed graph datasets plus notebooks for data prep.
- eval.* – evaluation harness integrating EM, BLEU, ROUGE, GPT-4.
- fig/ – static figures for README.
- Within Graph-CoT:
- code/GraphAgent.py – orchestrates reasoning-interaction-execution loop.
- code/graph_prompts.py, graph_fewshots.py – few-shot examples & prompt templates.
- code/tools/ – graph access functions (neighbor lookups, retriever).
- scripts/run_GraphCoT.sh – entrypoint for experiments.
- Presence of shell scripts in each module indicates a CLI-style invocation.

##### README for additional insights
- Graph-CoT is iterative: each iteration has
a) Reasoning by LLM → b) generate graph queries → c) execute queries on graph → repeat.
- Data flows from `data/processed_data/{domain}/data.json` into the retriever and agent.

##### Detail
- Sub-components: GraphAgent vs. graph_prompts vs. tool modules.
- Two variants under LLM Backend (GPT vs. open-source).
- Shell script entrypoints and environment setup (conda env, requirements.txt).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation Pipeline
    subgraph "Data Preparation Pipeline"
        direction TB
        RawData["Raw Data (notebooks)"]:::data
        Preprocess["Preprocessing Notebooks"]:::data
        Processed["Processed Graphs (JSON)"]:::storage
        RawData --> Preprocess --> Processed
    end
    click RawData "https://github.com/petergriffinjin/graph-cot/tree/main/data/raw_data/"
    click Processed "https://github.com/petergriffinjin/graph-cot/tree/main/data/processed_data/"

    %% Graph Knowledge Store
    subgraph "Graph Knowledge Store"
        direction TB
        GraphJSON[(Graph JSON)]:::storage
        FAISS[(FAISS Index)]:::storage
        GraphJSON --> FAISS
    end
    click GraphJSON "https://github.com/petergriffinjin/graph-cot/blob/main/data/processed_data/amazon/data.json"

    %% Graph-CoT Agent
    subgraph "Graph-CoT Agent"
        direction TB
        Agent["GraphAgent"]:::agent
        Prompts["Prompt Engine"]:::agent
        Fewshots["Few-shot Templates"]:::agent
        Interact["Interaction Generator"]:::agent
        Exec["Execution Layer"]:::agent
        Agent --> Prompts --> Fewshots --> Interact --> Exec --> Agent
    end
    click Agent "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/code/GraphAgent.py"
    click Prompts "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/code/graph_prompts.py"
    click Fewshots "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/code/graph_fewshots.py"
    click Exec "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/code/tools/graph_funcs.py"
    click Exec "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/code/tools/retriever.py"
    click Exec "https://github.com/petergriffinjin/graph-cot/blob/main/Graph-CoT/scripts/run_GraphCoT.sh"

    %% LLM Backends
    subgraph "LLM Backend" 
        direction TB
        subgraph "Open-Source LLM"
            direction TB
            OSS["run_llm.py"]:::llm
            OSS_RAG["run_llm_rag.py"]:::llm
            OSS_Retr["retriever.py"]:::llm
            OSS --> OSS_RAG
        end
        subgraph "GPT Models"
            direction TB
            GPTPsi["run_GPT.py"]:::llm
            GPT_RAG["run_GPT_rag.py"]:::llm
            GPT_Retr["retriever.py"]:::llm
            GPTPsi --> GPT_RAG
        end
    end
    click OSS "https://github.com/petergriffinjin/graph-cot/blob/main/LLM/code/run_llm.py"
    click OSS_RAG "https://github.com/petergriffinjin/graph-cot/blob/main/LLM/code/run_llm_rag.py"
    click OSS_Retr "https://github.com/petergriffinjin/graph-cot/blob/main/LLM/code/retriever.py"
    click GPTPsi "https://github.com/petergriffinjin/graph-cot/blob/main/GPT/code/run_GPT.py"
    click GPT_RAG "https://github.com/petergriffinjin/graph-cot/blob/main/GPT/code/run_GPT_rag.py"
    click GPT_Retr "https://github.com/petergriffinjin/graph-cot/blob/main/GPT/code/retriever.py"

    %% Evaluation Module
    subgraph "Evaluation Module"
        direction TB
        EvalScript["eval.py"]:::eval
        EvalShell["eval.sh"]:::eval
        EvalScript --> EvalShell
    end
    click EvalScript "https://github.com/petergriffinjin/graph-cot/blob/main/eval.py"
    click EvalShell "https://github.com/petergriffinjin/graph-cot/blob/main/eval.sh"

    %% Baseline Pipelines
    subgraph "Baseline Pipelines"
        direction TB
        Processed --> OSS
        Processed --> GPTPsi
        OSS -->|response| EvalScript
        GPTPsi -->|response| EvalScript
    end

    %% Graph-CoT Loop Flow
    Processed -->|load graphs| GraphJSON
    GraphJSON -->|provide| Agent
    Agent -->|prompt| OSS
    Agent -->|prompt| GPTPsi
    OSS -->|response| Agent
    GPTPsi -->|response| Agent
    Agent -->|graph query| GraphJSON
    GraphJSON -->|subgraph info| Agent
    Agent -->|final answer| EvalScript

    %% Styles
    classDef data fill:#a8d0e6,stroke:#05668d,color:#05668d;
    classDef storage fill:#d0e6f0,stroke:#034f84,color:#034f84,stroke-dasharray: 5 5;
    classDef agent fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef llm fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef eval fill:#e1bee7,stroke:#6a1b9a,color:#4a148c;
```
