# rsinghlab/k-paths architecture

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

- Interactive diagram: https://gitdiagram.com/rsinghlab/k-paths
- Repository: https://github.com/rsinghlab/k-paths

## Overview

##### Project type and purpose
- This is a research‐oriented ML/AI pipeline for knowledge‐graph–based drug repurposing and interaction prediction.
- It combines:
- A text-based LLM inference branch
- A graph-neural-network (GNN) training & evaluation branch
- Purpose: produce explainable, biologically meaningful reasoning paths from a KG, then use those for zero-shot LLM inference and for GNN prediction.

##### File structure
- Top-level scripts and dirs:
- llm/: zero-shot inference & evaluation of paths with large language models
- requirements.txt, README.md
- k-paths substructure:
- create_augmented_network.py
- get-Kpaths.py → extracts path lists
- utils/ → shared helper modules (path filtering, network utils)
- llm substructure:
- llm_inference.py / v2 → drives LLM calls (Hugging Face, Meta-Llama, etc.)
- evaluate_llm_regex.py / evaluate_llm_bertscore.py
- gnn substructure:
- train.py → RGCN training pipeline
- eval.py → model evaluation
- data_utils.py, train_eval_utils.py → input formatting, metrics, logging

##### Extract architectural insights from README
- Four sequential steps:
1. Download and unpack dataset
2. Create augmented KG
3. Extract K-reasoning paths
- Two parallel “consumers” of the paths:
- Branch A: natural‐language conversion → LLM inference → automatic evaluation (regex, BERTScore)
- External dependencies / services:
- Hugging Face dataset (pre-extracted paths)
- Large language models (Meta-Llama or Tx-Gemma via the Hugging Face Hub)
- Standard Python ML libs (PyTorch, DGL, scikit-learn, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Store
    DataStore["Data Store<br/>(raw KG, pre-extracted paths)"]:::db

    %% Preprocessing Stage
    AugBuilder["Augmented KG Builder<br/>(create_augmented_network.py)"]:::preprocess
    click AugBuilder "https://github.com/rsinghlab/k-paths/blob/main/k-paths/create_augmented_network.py"
    PathExtractor["Path Extractor<br/>(get-Kpaths.py)"]:::preprocess
    click PathExtractor "https://github.com/rsinghlab/k-paths/blob/main/k-paths/get-Kpaths.py"
    SubgraphBuilder["Subgraph Builder<br/>(get-subgraph.py)"]:::preprocess
    click SubgraphBuilder "https://github.com/rsinghlab/k-paths/blob/main/k-paths/get-subgraph.py"

    %% Utilities for k-paths
    subgraph "k-paths/utils" 
        KpathsUtils["Kpaths_utils.py"]:::utils
        AugNetUtils["augmented_network_utils.py"]:::utils
        SubgraphUtils["subgraph_utils.py"]:::utils
        click KpathsUtils "https://github.com/rsinghlab/k-paths/blob/main/k-paths/utils/Kpaths_utils.py"
        click AugNetUtils "https://github.com/rsinghlab/k-paths/blob/main/k-paths/utils/augmented_network_utils.py"
        click SubgraphUtils "https://github.com/rsinghlab/k-paths/blob/main/k-paths/utils/subgraph_utils.py"
    end

    %% LLM Branch
    subgraph "Branch A: LLM Inference" 
        direction TB
        LLMInfer1["LLM Inference v1<br/>(llm_inference.py)"]:::llm
        click LLMInfer1 "https://github.com/rsinghlab/k-paths/blob/main/llm/llm_inference.py"
        LLMInfer2["LLM Inference v2<br/>(llm_inference_v2.py)"]:::llm
        click LLMInfer2 "https://github.com/rsinghlab/k-paths/blob/main/llm/llm_inference_v2.py"
        LLMService["External LLM Service<br/>(Hugging Face Hub)"]:::external
        LLMRegexEval["LLM Evaluation<br/>(evaluate_llm_regex.py)"]:::llm
        click LLMRegexEval "https://github.com/rsinghlab/k-paths/blob/main/llm/evaluate_llm_regex.py"
        LLMBertEval["LLM Evaluation<br/>(evaluate_llm_bertscore.py)"]:::llm
        click LLMBertEval "https://github.com/rsinghlab/k-paths/blob/main/llm/evaluate_llm_bertscore.py"
        LLMOutputs["LLM Outputs"]:::db
    end

    %% GNN Branch
    subgraph "Branch B: GNN Training" 
        direction TB
        SubgraphBuilderNode["Subgraph Builder"]:::preprocess
        GNNTrain["GNN Training<br/>(train.py, model.py)"]:::gnn
        click GNNTrain "https://github.com/rsinghlab/k-paths/blob/main/gnn/train.py"
        click GNNTrain "https://github.com/rsinghlab/k-paths/blob/main/gnn/model.py"
        GNNDataUtils["GNN Data Utils<br/>(data_utils.py)"]:::utils
        click GNNDataUtils "https://github.com/rsinghlab/k-paths/blob/main/gnn/data_utils.py"
        GNNTrainEvalUtils["Train/Eval Utils<br/>(train_eval_utils.py)"]:::utils
        click GNNTrainEvalUtils "https://github.com/rsinghlab/k-paths/blob/main/gnn/train_eval_utils.py"
        GNNEval["GNN Evaluation<br/>(eval.py)"]:::gnn
        click GNNEval "https://github.com/rsinghlab/k-paths/blob/main/gnn/eval.py"
        GNNOutputs["GNN Outputs"]:::db
    end

    %% Documentation and Config
    Requirements["requirements.txt"]:::docs
    click Requirements "https://github.com/rsinghlab/k-paths/blob/main/requirements.txt"
    Readme["README.md"]:::docs
    click Readme "https://github.com/rsinghlab/k-paths/blob/main/README.md"
    Assets["Overview Presentation<br/>(assets/K-Paths-overview.pdf)"]:::docs
    click Assets "https://github.com/rsinghlab/k-paths/blob/main/assets/K-Paths-overview.pdf"

    %% Connections
    DataStore -->|"1. raw KG files"| AugBuilder
    AugBuilder -->|"2. networkx graph"| PathExtractor
    PathExtractor -->|"3a. .json paths"| LLMInfer1
    PathExtractor -->|"3a. .json paths"| LLMInfer2
    LLMInfer1 -->|"API calls"| LLMService
    LLMInfer2 -->|"API calls"| LLMService
    LLMService -->|"text responses"| LLMRegexEval
    LLMService -->|"text responses"| LLMBertEval
    LLMRegexEval --> LLMOutputs
    LLMBertEval --> LLMOutputs

    PathExtractor -->|"3b. .json paths"| SubgraphBuilder
    SubgraphBuilder -->|"4. subgraphs (PyTorch dataset)"| GNNTrain
    GNNTrain -->|"trained model"| GNNEval
    GNNEval --> GNNOutputs

    %% Utils dependencies
    AugBuilder --- KpathsUtils
    AugBuilder --- AugNetUtils
    PathExtractor --- KpathsUtils
    SubgraphBuilder --- SubgraphUtils

    GNNTrain --- GNNDataUtils
    GNNTrain --- GNNTrainEvalUtils
    GNNEval --- GNNTrainEvalUtils

    %% Side docs connections
    DataStore -.-> Readme
    DataStore -.-> Requirements
    DataStore -.-> Assets

    %% Class Definitions
    classDef preprocess fill:#D0E8FF,stroke:#0033A0
    classDef llm fill:#D0F9D8,stroke:#2E7D32
    classDef gnn fill:#FFE0B2,stroke:#EF6C00
    classDef external fill:#E0E0E0,stroke:#616161
    classDef utils fill:#F0F0F0,stroke:#AAAAAA
    classDef db fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5
    classDef docs fill:#F5F5F5,stroke:#9E9E9E
```
