# tsafavi/codex architecture

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

- Interactive diagram: https://gitdiagram.com/tsafavi/codex
- Repository: https://github.com/tsafavi/codex

## Overview

CoDEx is a knowledge-graph completion benchmark: users load a dataset and its metadata, inspect positive and hard-negative triples, or evaluate pretrained models for link prediction and triple classification. The Python API reads the packaged files; evaluation scripts use LibKGE checkpoints and produce metrics. The README also documents a notebook for exploring the data and a command-line pretrained-model downloader. Source excerpts establish the API’s file reads and downloader’s file writes; evaluation and notebook relationships are documented in the README, not verified from their implementation.

Main entry points: [`codex/codex.py`](https://github.com/tsafavi/codex/blob/master/codex/codex.py) (CoDEx API), [`scripts`](https://github.com/tsafavi/codex/tree/master/scripts) (Link prediction), [`scripts/tc.py`](https://github.com/tsafavi/codex/blob/master/scripts/tc.py) (Triple classification), [`scripts/baseline.py`](https://github.com/tsafavi/codex/blob/master/scripts/baseline.py) (Frequency baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Benchmark data"]
  node_triples["Positive triples"]
  node_negatives["Hard negatives"]
  node_entity_meta["Entity metadata"]
  node_relations["Relation metadata"]
  node_types["Entity types"]
  node_extracts["Wikipedia extracts"]
  node_type_extracts["Type extracts"]
end

subgraph group_api["Data access"]
  node_api_class["CoDEx API<br/>[codex.py]"]
  node_package["Python package<br/>[__init__.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_link_eval["Link prediction"]
  node_class_eval["Triple classification<br/>[tc.py]"]
  node_baseline["Frequency baseline<br/>[baseline.py]"]
  node_results["Evaluation results"]
end

subgraph group_models["Models and exploration"]
  node_explore["Data notebook"]
  node_lp_configs["Link prediction configs"]
  node_tc_configs["Classification configs"]
  node_checkpoints["Pretrained checkpoints"]
  node_downloader["Model downloader"]
end

node_user(("Researcher"))
node_libkge["LibKGE"]

node_user -->|"loads dataset"| node_api_class
node_api_class -->|"reads splits"| node_triples
node_api_class -->|"reads negatives"| node_negatives
node_api_class -->|"reads entities"| node_entity_meta
node_api_class -->|"reads relations"| node_relations
node_api_class -->|"reads types"| node_types
node_api_class -->|"reads extracts"| node_extracts
node_api_class -->|"reads extracts"| node_type_extracts
node_user -->|"explores data"| node_explore
node_user -->|"runs evaluation"| node_link_eval
node_link_eval -->|"uses framework"| node_libkge
node_link_eval -->|"uses configs"| node_lp_configs
node_link_eval -->|"loads models"| node_checkpoints
node_link_eval -->|"reports metrics"| node_results
node_user -->|"runs evaluation"| node_class_eval
node_class_eval -->|"loads models"| node_libkge
node_class_eval -->|"uses configs"| node_tc_configs
node_class_eval -->|"loads hard negatives"| node_negatives
node_class_eval -->|"reports metrics"| node_results
node_user -->|"compares models"| node_baseline
node_baseline -->|"loads checkpoint"| node_libkge
node_baseline -->|"reports rankings"| node_results
node_user -->|"requests checkpoints"| node_downloader
node_downloader -->|"writes checkpoints"| node_checkpoints
node_downloader -->|"downloads checkpoints"| node_libkge

click node_api_class "https://github.com/tsafavi/codex/blob/master/codex/codex.py"
click node_package "https://github.com/tsafavi/codex/blob/master/codex/__init__.py"
click node_triples "https://github.com/tsafavi/codex/tree/master/data/triples"
click node_negatives "https://github.com/tsafavi/codex/tree/master/data/triples"
click node_entity_meta "https://github.com/tsafavi/codex/tree/master/data/entities"
click node_relations "https://github.com/tsafavi/codex/tree/master/data/relations"
click node_types "https://github.com/tsafavi/codex/tree/master/data/types"
click node_extracts "https://github.com/tsafavi/codex/tree/master/data/entities"
click node_type_extracts "https://github.com/tsafavi/codex/tree/master/data/types"
click node_explore "https://github.com/tsafavi/codex/blob/master/Explore%20CoDEx.ipynb"
click node_lp_configs "https://github.com/tsafavi/codex/tree/master/models/link-prediction"
click node_tc_configs "https://github.com/tsafavi/codex/tree/master/models/triple-classification"
click node_checkpoints "https://github.com/tsafavi/codex/tree/master/models"
click node_downloader "https://github.com/tsafavi/codex/blob/master/download_pretrained.py"
click node_link_eval "https://github.com/tsafavi/codex/tree/master/scripts"
click node_class_eval "https://github.com/tsafavi/codex/blob/master/scripts/tc.py"
click node_baseline "https://github.com/tsafavi/codex/blob/master/scripts/baseline.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_triples,node_negatives,node_entity_meta,node_relations,node_types,node_extracts,node_type_extracts toneBlue
class node_api_class,node_package toneAmber
class node_link_eval,node_class_eval,node_baseline,node_results toneMint
class node_explore,node_lp_configs,node_tc_configs,node_checkpoints,node_downloader toneRose
class node_user,node_libkge toneIndigo
```

## Components

### Benchmark data

- [Positive triples](https://github.com/tsafavi/codex/tree/master/data/triples): `data/triples`
- [Hard negatives](https://github.com/tsafavi/codex/tree/master/data/triples): `data/triples`
- [Entity metadata](https://github.com/tsafavi/codex/tree/master/data/entities): `data/entities`
- [Relation metadata](https://github.com/tsafavi/codex/tree/master/data/relations): `data/relations`
- [Entity types](https://github.com/tsafavi/codex/tree/master/data/types): `data/types`
- [Wikipedia extracts](https://github.com/tsafavi/codex/tree/master/data/entities): `data/entities`
- [Type extracts](https://github.com/tsafavi/codex/tree/master/data/types): `data/types`

### Data access

- [CoDEx API](https://github.com/tsafavi/codex/blob/master/codex/codex.py): `codex/codex.py`
- [Python package](https://github.com/tsafavi/codex/blob/master/codex/__init__.py): `codex/__init__.py`

### Evaluation

- [Link prediction](https://github.com/tsafavi/codex/tree/master/scripts): `scripts`
- [Triple classification](https://github.com/tsafavi/codex/blob/master/scripts/tc.py): `scripts/tc.py`
- [Frequency baseline](https://github.com/tsafavi/codex/blob/master/scripts/baseline.py): `scripts/baseline.py`
- **Evaluation results**

### Models and exploration

- [Data notebook](https://github.com/tsafavi/codex/blob/master/Explore%20CoDEx.ipynb): `Explore CoDEx.ipynb`
- [Link prediction configs](https://github.com/tsafavi/codex/tree/master/models/link-prediction): `models/link-prediction`
- [Classification configs](https://github.com/tsafavi/codex/tree/master/models/triple-classification): `models/triple-classification`
- [Pretrained checkpoints](https://github.com/tsafavi/codex/tree/master/models): `models`
- [Model downloader](https://github.com/tsafavi/codex/blob/master/download_pretrained.py): `download_pretrained.py`

### Other components

- **Researcher**
- **LibKGE**

## Connections

- Researcher → CoDEx API: loads dataset (evidence: `README.md`)
- CoDEx API → Positive triples: reads splits (evidence: `codex/codex.py`)
- CoDEx API → Hard negatives: reads negatives (evidence: `codex/codex.py`)
- CoDEx API → Entity metadata: reads entities (evidence: `codex/codex.py`)
- CoDEx API → Relation metadata: reads relations (evidence: `codex/codex.py`)
- CoDEx API → Entity types: reads types (evidence: `codex/codex.py`)
- CoDEx API → Wikipedia extracts: reads extracts (evidence: `codex/codex.py`)
- CoDEx API → Type extracts: reads extracts (evidence: `codex/codex.py`)
- Researcher → Data notebook: explores data (evidence: `README.md`)
- Researcher → Link prediction: runs evaluation (evidence: `README.md`)
- Link prediction → LibKGE: uses framework (evidence: `README.md`)
- Link prediction → Link prediction configs: uses configs (evidence: `README.md`)
- Link prediction → Pretrained checkpoints: loads models (evidence: `README.md`)
- Link prediction → Evaluation results: reports metrics (evidence: `README.md`)
- Researcher → Triple classification: runs evaluation (evidence: `README.md`)
- Triple classification → LibKGE: loads models (evidence: `scripts/tc.py`)
- Triple classification → Classification configs: uses configs (evidence: `README.md`)
- Triple classification → Hard negatives: loads hard negatives (evidence: `scripts/tc.py`)
- Triple classification → Evaluation results: reports metrics (evidence: `scripts/tc.py`)
- Researcher → Frequency baseline: compares models (evidence: `README.md`)
- Frequency baseline → LibKGE: loads checkpoint (evidence: `scripts/baseline.py`)
- Frequency baseline → Evaluation results: reports rankings (evidence: `scripts/baseline.py`)
- Researcher → Model downloader: requests checkpoints (evidence: `README.md`)
- Model downloader → Pretrained checkpoints: writes checkpoints (evidence: `download_pretrained.py`)
- Model downloader → LibKGE: downloads checkpoints (evidence: `README.md`)
