# hhdo/tipnn architecture

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

- Interactive diagram: https://gitdiagram.com/hhdo/tipnn
- Repository: https://github.com/hhdo/tipnn

## Overview

TiPNN is a research implementation for temporal knowledge-graph reasoning. The main workflow loads timestamped triples, builds rolling history graphs, trains a temporal path neural network to score future links, and evaluates predictions with filtered ranking metrics. It also supports inductive evaluation using a model pretrained on a paired dataset, and pathview provides human-readable path interpretations. The README documents these capabilities; the supplied source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/main.py`](https://github.com/hhdo/tipnn/blob/main/src/main.py) (Training Runner), [`src/utils.py`](https://github.com/hhdo/tipnn/blob/main/src/utils.py) (Graph and Ranking Utilities), [`src/inductive.py`](https://github.com/hhdo/tipnn/blob/main/src/inductive.py) (Inductive Runner), [`src/model.py`](https://github.com/hhdo/tipnn/blob/main/src/model.py) (TiPNN)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Training and Evaluation"]
  node_main["Training Runner<br/>[main.py]"]
  node_config["Run Configuration<br/>[config.py]"]
  node_optimizer["Training and Loss<br/>[main.py]"]
  node_evaluation["Filtered Evaluation<br/>[main.py]"]
  node_checkpoint["Model Checkpoint<br/>[main.py]"]
end

subgraph group_data["Temporal Data"]
  node_datasets["Temporal Datasets"]
  node_kgutil["Dataset Reader<br/>[kgutil.py]"]
  node_utils["Graph and Ranking Utilities<br/>[utils.py]"]
  node_history["History Graph<br/>[utils.py]"]
end

subgraph group_model["Reasoning Model"]
  node_model["TiPNN<br/>[model.py]"]
  node_layers["Temporal Aggregation<br/>[layers.py]"]
end

subgraph group_interpretation["Inductive and Path Analysis"]
  node_inductive["Inductive Runner<br/>[inductive.py]"]
  node_pathview["Path Interpretation<br/>[pathview.py]"]
  node_pretrained["Pretrained Model"]
end

node_user(("Researcher"))

node_user -->|"runs"| node_main
node_user -->|"runs"| node_inductive
node_main -->|"reads options"| node_config
node_inductive -->|"reads options"| node_config
node_main -->|"loads data"| node_utils
node_inductive -->|"loads data"| node_utils
node_utils -->|"loads dataset"| node_kgutil
node_kgutil -->|"reads triples"| node_datasets
node_main -->|"builds history"| node_history
node_inductive -->|"builds history"| node_history
node_history -->|"uses graph helpers"| node_utils
node_main -->|"samples negatives"| node_utils
node_main -->|"scores triples"| node_model
node_inductive -->|"scores triples"| node_model
node_model -->|"aggregates messages"| node_layers
node_main -->|"trains model"| node_optimizer
node_optimizer -->|"updates parameters"| node_model
node_optimizer -->|"synchronizes"| node_utils
node_main -->|"evaluates rankings"| node_evaluation
node_evaluation -->|"ranks predictions"| node_utils
node_main -->|"saves and loads"| node_checkpoint
node_inductive -->|"loads checkpoint"| node_pretrained
node_pathview -->|"builds history and ranks"| node_utils
node_pathview -->|"scores and traces"| node_model
node_user -->|"requests interpretation"| node_pathview

click node_main "https://github.com/hhdo/tipnn/blob/main/src/main.py"
click node_inductive "https://github.com/hhdo/tipnn/blob/main/src/inductive.py"
click node_config "https://github.com/hhdo/tipnn/blob/main/src/config.py"
click node_datasets "https://github.com/hhdo/tipnn/tree/main/data"
click node_kgutil "https://github.com/hhdo/tipnn/blob/main/src/kgutil.py"
click node_utils "https://github.com/hhdo/tipnn/blob/main/src/utils.py"
click node_history "https://github.com/hhdo/tipnn/blob/main/src/utils.py"
click node_model "https://github.com/hhdo/tipnn/blob/main/src/model.py"
click node_layers "https://github.com/hhdo/tipnn/blob/main/src/layers.py"
click node_optimizer "https://github.com/hhdo/tipnn/blob/main/src/main.py"
click node_evaluation "https://github.com/hhdo/tipnn/blob/main/src/main.py"
click node_checkpoint "https://github.com/hhdo/tipnn/blob/main/src/main.py"
click node_pathview "https://github.com/hhdo/tipnn/blob/main/src/pathview.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_main,node_config,node_optimizer,node_evaluation,node_checkpoint toneBlue
class node_datasets,node_kgutil,node_utils,node_history toneAmber
class node_model,node_layers toneMint
class node_inductive,node_pathview,node_pretrained toneRose
class node_user toneIndigo
```

## Components

### Training and Evaluation

- [Training Runner](https://github.com/hhdo/tipnn/blob/main/src/main.py): `src/main.py`
- [Run Configuration](https://github.com/hhdo/tipnn/blob/main/src/config.py): `src/config.py`
- [Training and Loss](https://github.com/hhdo/tipnn/blob/main/src/main.py): `src/main.py`
- [Filtered Evaluation](https://github.com/hhdo/tipnn/blob/main/src/main.py): `src/main.py`
- [Model Checkpoint](https://github.com/hhdo/tipnn/blob/main/src/main.py): `src/main.py`

### Temporal Data

- [Temporal Datasets](https://github.com/hhdo/tipnn/tree/main/data): `data`
- [Dataset Reader](https://github.com/hhdo/tipnn/blob/main/src/kgutil.py): `src/kgutil.py`
- [Graph and Ranking Utilities](https://github.com/hhdo/tipnn/blob/main/src/utils.py): `src/utils.py`
- [History Graph](https://github.com/hhdo/tipnn/blob/main/src/utils.py): `src/utils.py`

### Reasoning Model

- [TiPNN](https://github.com/hhdo/tipnn/blob/main/src/model.py): `src/model.py`
- [Temporal Aggregation](https://github.com/hhdo/tipnn/blob/main/src/layers.py): `src/layers.py`

### Inductive and Path Analysis

- [Inductive Runner](https://github.com/hhdo/tipnn/blob/main/src/inductive.py): `src/inductive.py`
- [Path Interpretation](https://github.com/hhdo/tipnn/blob/main/src/pathview.py): `src/pathview.py`
- **Pretrained Model**

### Other components

- **Researcher**

## Connections

- Researcher → Training Runner: runs
- Researcher → Inductive Runner: runs
- Training Runner → Run Configuration: reads options
- Inductive Runner → Run Configuration: reads options
- Training Runner → Graph and Ranking Utilities: loads data
- Inductive Runner → Graph and Ranking Utilities: loads data
- Graph and Ranking Utilities → Dataset Reader: loads dataset
- Dataset Reader → Temporal Datasets: reads triples
- Training Runner → History Graph: builds history
- Inductive Runner → History Graph: builds history
- History Graph → Graph and Ranking Utilities: uses graph helpers
- Training Runner → Graph and Ranking Utilities: samples negatives
- Training Runner → TiPNN: scores triples
- Inductive Runner → TiPNN: scores triples
- TiPNN → Temporal Aggregation: aggregates messages
- Training Runner → Training and Loss: trains model
- Training and Loss → TiPNN: updates parameters
- Training and Loss → Graph and Ranking Utilities: synchronizes
- Training Runner → Filtered Evaluation: evaluates rankings
- Filtered Evaluation → Graph and Ranking Utilities: ranks predictions
- Training Runner → Model Checkpoint: saves and loads
- Inductive Runner → Pretrained Model: loads checkpoint
- Path Interpretation → Graph and Ranking Utilities: builds history and ranks
- Path Interpretation → TiPNN: scores and traces
- Researcher → Path Interpretation: requests interpretation