# wangskygit/kehgn-r architecture

> Architecture diagram of the GitHub repository wangskygit/kehgn-r, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wangskygit/kehgn-r
- Repository: https://github.com/wangskygit/kehgn-r

## Overview

1. **What this repo is**
   - KeGCN-R is a training/evaluation repository for graph-based prediction on company subgraphs.
   - The core idea is to combine a GCN-style graph encoder with optional pre-trained knowledge embeddings (“KE”) for each entity/company.

2. **Primary runtime and dependencies**
   - The code is a Python 3.9 / PyTorch 1.11 project.
   - Data handling and evaluation rely on `pandas`, `scipy`, and `sklearn`.
   - Knowledge embeddings are produced outside the repo with DGL-KE and then loaded in as an offline artifact.

3. **Input data boundary**
   - The repository expects unpacked dataset folders in the working directory.
   - Each dataset contains:
     - `.npy` adjacency matrices for company subgraphs
     - `fv.csv` with features and labels
   - The `year` column in `fv.csv` is a special field used for constructing the “trust-worthy” test split, not as a model feature.

4. **Offline embedding boundary**
   - A second external input is a pretraining result directory from DGL-KE.
   - This acts as a separate knowledge source that can be fused into the model or disabled with `-wke`.
   - Architecturally, this creates a two-stream setup: graph data from the dataset, and entity embeddings from the KE checkpoint.

5. **Training entrypoint**
   - `main.py` is the orchestration layer.
   - It likely parses CLI flags such as `--model`, `--dataset`, `-d`, `-lr`, `--device`, and `-wke`, then:
     - loads data
     - builds the chosen model
     - runs training
     - evaluates on the test split
   - The README examples show that `main.py` is the only user-facing entrypoint for normal runs.

6. **Model subsystem**
   - `model.py` is the main model registry/implementation file.
   - It contains the KeGCN family:
     - `KeGCN`
     - `KeGCNR` (the “R” variant used in the paper/repo name)
   - The model boundary is likely where graph features, structural messages, and optional KE vectors are combined before classification/regression.

7. **Graph neural network layers**
   - `layer.py` holds reusable graph-layer building blocks.
   - This is the architectural seam where low-level message passing, graph aggregation, or residual/attention-style operations are implemented.
   - `model.py` likely assembles these layers into the full KeGCN/KeGCN-R architecture.

8. **Loss and optimization**
   - `loss.py` isolates the training objective(s).
   - This is where task-specific supervision is separated from the model definition, which makes it easier to swap objectives or compare variants.
   - In diagrams, this is the “prediction head → loss” boundary after the model forward pass.

9. **Baselines and experiments**
   - `baseline.py` suggests alternative non-KeGCN approaches for comparison.
   - `exp.py` likely contains experiment runners, evaluation helpers, or ablation logic.
   - These files define the experimental boundary around the core model so the repo can reproduce paper comparisons and ablations like “KeGCNR w/o ke”.

10. **Evaluation / split logic**
   - `tm.py` and `sieve.py` appear to support dataset partitioning, trustworthiness filtering, or sample selection.
   - Because the README explicitly mentions a year-based trustworthy test set, these modules are likely part of the data-splitting and test-set construction path.
   - This is important architecturally because the evaluation split is not a trivial random split; it depends on dataset metadata.

11. **Utilities**
   - `util.py` is the shared support layer for common tasks such as seeding, I/O, logging, metrics, or tensor/data conversion.
   - In the architecture, this is the cross-cutting helper boundary used by training, evaluation, and preprocessing code.

12. **End-to-end data flow**
   - Dataset files and KE embeddings are loaded from disk.
   - `main.py` builds the selected model variant.
   - The model consumes graph structure from `.npy` adjacency matrices plus tabular features from `fv.csv`.
   - If enabled, KE vectors are merged into the representation.
   - The output is passed to the task loss in `loss.py`, optimized with PyTorch, and evaluated on the designated split logic implemented by the supporting modules.

13. **Key architectural toggle**
   - The `-wke` flag is the main switch that changes the model boundary:
     - enabled: graph-only / no knowledge embedding branch
     - disabled: graph + KE hybrid model
   - For an architecture diagram, this is the clearest branch point in the system.

14. **What to emphasize in a diagram**
   - Show three main layers:
     1. offline artifacts: datasets and KE checkpoint
     2. training orchestration: `main.py` plus split/eval utilities
     3. model stack: `model.py` / `layer.py` / `loss.py`
   - The most important integration point is the fusion of graph structure with pre-trained knowledge embeddings.

Main entry points: [`main.py`](https://github.com/wangskygit/kehgn-r/blob/main/main.py) (main.py), [`model.py`](https://github.com/wangskygit/kehgn-r/blob/main/model.py) (model.py), [`layer.py`](https://github.com/wangskygit/kehgn-r/blob/main/layer.py) (layer.py), [`loss.py`](https://github.com/wangskygit/kehgn-r/blob/main/loss.py) (loss.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Offline inputs"]
  node_dataset[("Dataset files<br/>offline data")]
  node_ke_ckpt[("KE checkpoint<br/>offline embedding")]
end

subgraph group_orchestration["Training flow"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_util_py["util.py<br/>shared utils<br/>[util.py]"]
  node_tm_py["tm.py<br/>split logic<br/>[tm.py]"]
  node_sieve_py["sieve.py<br/>selection logic<br/>[sieve.py]"]
  node_exp_py["exp.py<br/>experiments<br/>[exp.py]"]
  node_baseline_py["baseline.py<br/>baselines<br/>[baseline.py]"]
end

subgraph group_model["Model stack"]
  node_model_py["model.py<br/>model registry<br/>[model.py]"]
  node_layer_py["layer.py<br/>graph layers<br/>[layer.py]"]
  node_loss_py["loss.py<br/>objective<br/>[loss.py]"]
  node_graph_encoder{{"Graph encoder<br/>GCN encoder"}}
  node_ke_fusion{{"KE fusion<br/>feature fusion"}}
  node_prediction_head{{"Prediction head<br/>output head"}}
  node_kegcn["KeGCN<br/>model variant"]
  node_kegcnr["KeGCNR<br/>model variant"]
end

node_dataset -->|"load graph data"| node_main_py
node_ke_ckpt -->|"load KE"| node_main_py
node_main_py -->|"build split"| node_tm_py
node_main_py -->|"filter samples"| node_sieve_py
node_main_py -->|"instantiate"| node_model_py
node_main_py -->|"run baselines"| node_baseline_py
node_main_py -->|"orchestrate exp"| node_exp_py
node_main_py -->|"shared helpers"| node_util_py
node_model_py -->|"compose layers"| node_layer_py
node_model_py -->|"encode graph"| node_graph_encoder
node_model_py -->|"merge KE"| node_ke_fusion
node_model_py -->|"predict"| node_prediction_head
node_graph_encoder -->|"message passing"| node_layer_py
node_ke_fusion -->|"consume embeddings"| node_ke_ckpt
node_prediction_head -->|"compute loss"| node_loss_py
node_model_py -->|"implements"| node_kegcn
node_model_py -->|"implements"| node_kegcnr
node_kegcn -->|"with KE"| node_ke_fusion
node_kegcnr -->|"with KE"| node_ke_fusion
node_kegcnr -->|"graph branch"| node_graph_encoder
node_main_py -->|"optimize"| node_loss_py

click node_main_py "https://github.com/wangskygit/kehgn-r/blob/main/main.py"
click node_util_py "https://github.com/wangskygit/kehgn-r/blob/main/util.py"
click node_tm_py "https://github.com/wangskygit/kehgn-r/blob/main/tm.py"
click node_sieve_py "https://github.com/wangskygit/kehgn-r/blob/main/sieve.py"
click node_exp_py "https://github.com/wangskygit/kehgn-r/blob/main/exp.py"
click node_baseline_py "https://github.com/wangskygit/kehgn-r/blob/main/baseline.py"
click node_model_py "https://github.com/wangskygit/kehgn-r/blob/main/model.py"
click node_layer_py "https://github.com/wangskygit/kehgn-r/blob/main/layer.py"
click node_loss_py "https://github.com/wangskygit/kehgn-r/blob/main/loss.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dataset,node_ke_ckpt toneBlue
class node_main_py,node_util_py,node_tm_py,node_sieve_py,node_exp_py,node_baseline_py toneAmber
class node_model_py,node_layer_py,node_loss_py,node_graph_encoder,node_ke_fusion,node_prediction_head,node_kegcn,node_kegcnr toneMint
```

## Components

### Offline inputs

Dataset folders and pre-trained knowledge embeddings consumed from disk.

- **Dataset files**: offline data · Unpacked company-subgraph datasets with adjacency .npy files and fv.csv features/labels.
- **KE checkpoint**: offline embedding · External DGL-KE pretraining artifacts loaded as optional entity embeddings.

### Training flow

Entry point, splitting, evaluation, and experiment plumbing.

- [main.py](https://github.com/wangskygit/kehgn-r/blob/main/main.py): entrypoint · CLI orchestration for loading data, building the model, training, and evaluation. · `main.py`
- [util.py](https://github.com/wangskygit/kehgn-r/blob/main/util.py): shared utils · Cross-cutting helpers for seeding, I/O, metrics, logging, and tensor/data handling. · `util.py`
- [tm.py](https://github.com/wangskygit/kehgn-r/blob/main/tm.py): split logic · Support for trustworthy test split construction and related dataset partitioning. · `tm.py`
- [sieve.py](https://github.com/wangskygit/kehgn-r/blob/main/sieve.py): selection logic · Sample filtering or selection support used by evaluation and split construction. · `sieve.py`
- [exp.py](https://github.com/wangskygit/kehgn-r/blob/main/exp.py): experiments · Experiment runners, ablations, and evaluation helpers around the core training loop. · `exp.py`
- [baseline.py](https://github.com/wangskygit/kehgn-r/blob/main/baseline.py): baselines · Alternative comparison models and non-KeGCN reference methods. · `baseline.py`

### Model stack

KeGCN variants, reusable layers, and training objective.

- [model.py](https://github.com/wangskygit/kehgn-r/blob/main/model.py): model registry · Main KeGCN/KeGCNR implementation and architecture assembly. · `model.py`
- [layer.py](https://github.com/wangskygit/kehgn-r/blob/main/layer.py): graph layers · Reusable message-passing and aggregation building blocks for the encoder. · `layer.py`
- [loss.py](https://github.com/wangskygit/kehgn-r/blob/main/loss.py): objective · Task loss and optimization target used after the model forward pass. · `loss.py`
- **Graph encoder**: GCN encoder · Learns structural representations from company subgraph topology.
- **KE fusion**: feature fusion · Merges optional pre-trained knowledge embeddings with graph representations.
- **Prediction head**: output head · Maps the fused representation to the task output before loss computation.
- **KeGCN**: model variant · Hybrid graph-plus-knowledge model variant.
- **KeGCNR**: model variant · Repository-named KeGCN-R variant used in the paper and main runs.

## Connections

- Dataset files → main.py: load graph data · Main reads adjacency matrices and fv.csv features/labels.
- KE checkpoint → main.py: load KE · Main optionally loads pre-trained entity embeddings.
- main.py → tm.py: build split · Constructs the trustworthy test split and related partitions.
- main.py → sieve.py: filter samples · Applies dataset selection or filtering for evaluation setup.
- main.py → model.py: instantiate · Chooses the requested model variant and wires inputs.
- main.py → baseline.py: run baselines · Routes comparison runs to baseline implementations.
- main.py → exp.py: orchestrate exp · Invokes experiment and ablation workflows.
- main.py → util.py: shared helpers · Uses common utilities during training and evaluation.
- model.py → layer.py: compose layers · Builds the encoder from reusable graph-layer blocks.
- model.py → Graph encoder: encode graph · Turns company subgraph structure into learned embeddings.
- model.py → KE fusion: merge KE · Integrates optional knowledge embeddings when enabled.
- model.py → Prediction head: predict · Produces task outputs from fused representations.
- Graph encoder → layer.py: message passing · Uses the lower-level GCN/message-passing layers.
- KE fusion → KE checkpoint: consume embeddings · Reads the offline KE artifact as a secondary input stream.
- Prediction head → loss.py: compute loss · Feeds predictions into the task objective.
- model.py → KeGCN: implements · Contains the KeGCN family implementation.
- model.py → KeGCNR: implements · Contains the KeGCN-R variant used by the repo.
- KeGCN → KE fusion: with KE · Hybrid branch that includes knowledge embeddings.
- KeGCNR → KE fusion: with KE · Paper/repo variant that combines graph and knowledge streams.
- KeGCNR → Graph encoder: graph branch · Structural encoder path shared with the hybrid model.
- main.py → loss.py: optimize · Coordinates training with the shared loss module.
