# gridfm/gridfm-graphkit architecture

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

- Interactive diagram: https://gitdiagram.com/gridfm/gridfm-graphkit
- Repository: https://github.com/gridfm/gridfm-graphkit

## Overview

gridfm-graphkit is a power-grid graph foundation-model library for training, fine-tuning, evaluating, predicting, and serving reconstruction requests. The principal workflow is CLI configuration → graph dataset and data module → task/model execution → losses and logged or saved results. Separate task modules cover power flow, optimal power flow, state estimation, and reconstruction. The vLLM integration provides an additional serving path. Edges below are limited to README statements and visible source references; several domain-specific links remain unshown because their implementation was not sampled.

Main entry points: [`gridfm_graphkit/cli.py`](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/cli.py) (CLI workflows), [`gridfm_graphkit/datasets/hetero_powergrid_datamodule.py`](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/hetero_powergrid_datamodule.py) (Data module), [`gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py`](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py) (PF request processor), [`gridfm_graphkit/io/param_handler.py`](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/param_handler.py) (Component factories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI workflows<br/>[cli.py]"]
  node_config["Config migration<br/>[config_version.py]"]
  node_parameters["Component factories<br/>[param_handler.py]"]
  node_registries["Registries<br/>[registries.py]"]
end

subgraph group_data["Graph data"]
  node_datamodule["Data module"]
  node_dataset["Power-grid dataset"]
  node_graphbuilder["Graph construction<br/>[graph_builder.py]"]
  node_features["Feature schema<br/>[globals.py]"]
  node_normalizers["Normalization<br/>[normalizers.py]"]
  node_transforms["Positional statistics<br/>[posenc_stats.py]"]
end

subgraph group_model["Model components"]
  node_gnn["Heterogeneous GNN"]
  node_grit["GRIT transformer"]
  node_gritlayer["GRIT layer<br/>[grit_layer.py]"]
  node_physics["Physics decoders<br/>[utils.py]"]
end

subgraph group_tasks["Tasks and training"]
  node_base_task["Task base<br/>[base_task.py]"]
  node_reconstruction["Reconstruction task"]
  node_pf["Power flow task<br/>[pf_task.py]"]
  node_opf["Optimal flow task<br/>[opf_task.py]"]
  node_stateest["State estimation<br/>[se_task.py]"]
  node_baselines["AC/DC baselines"]
  node_opfb["OPF baselines"]
  node_loss["Loss functions<br/>[loss.py]"]
  node_callbacks["Training callbacks<br/>[callbacks.py]"]
end

subgraph group_serving["Inference serving"]
  node_vllm_model["vLLM model<br/>[model.py]"]
  node_vllm_config["Inference bundle<br/>[config.py]"]
  node_codec["Graph codec<br/>[graph_codec.py]"]
  node_pf_processor["PF request processor<br/>[io_processor.py]"]
end

node_user(("User"))
node_vllm["vLLM runtime"]

node_user -->|"invokes"| node_cli
node_cli -->|"resolves config"| node_config
node_cli -->|"sets up data"| node_datamodule
node_cli -->|"loads task"| node_parameters
node_cli -->|"configures callbacks"| node_callbacks
node_datamodule -->|"creates dataset"| node_dataset
node_datamodule -->|"fits normalizers"| node_normalizers
node_datamodule -->|"uses statistics"| node_transforms
node_dataset -->|"builds graphs"| node_graphbuilder
node_dataset -->|"normalizes data"| node_normalizers
node_parameters -->|"creates components"| node_registries
node_parameters -->|"creates losses"| node_loss
node_reconstruction -->|"loads model and loss"| node_parameters
node_reconstruction -->|"extends"| node_base_task
node_grit -->|"uses layer"| node_gritlayer
node_gnn -->|"uses schema"| node_features
node_grit -->|"uses schema"| node_features
node_pf -->|"uses schema"| node_features
node_opf -->|"uses schema"| node_features
node_pf -->|"uses decoders"| node_physics
node_opf -->|"uses decoders"| node_physics
node_pf -.->|"computes losses"| node_loss
node_opf -.->|"computes losses"| node_loss
node_vllm_model -->|"loads config"| node_vllm_config
node_vllm_model -->|"uses codec"| node_codec
node_pf_processor -->|"builds bundle"| node_vllm_config
node_pf_processor -->|"constructs graphs"| node_graphbuilder
node_pf_processor -->|"encodes graphs"| node_codec
node_vllm -.->|"dispatches requests"| node_pf_processor

click node_cli "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/cli.py"
click node_config "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/config_version.py"
click node_parameters "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/param_handler.py"
click node_registries "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/registries.py"
click node_datamodule "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/hetero_powergrid_datamodule.py"
click node_dataset "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/powergrid_hetero_dataset.py"
click node_graphbuilder "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/graph_builder.py"
click node_features "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/globals.py"
click node_normalizers "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/normalizers.py"
click node_transforms "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/posenc_stats.py"
click node_gnn "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/gnn_heterogeneous_gns.py"
click node_grit "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/grit_transformer.py"
click node_gritlayer "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/grit_layer.py"
click node_physics "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/utils.py"
click node_base_task "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/base_task.py"
click node_reconstruction "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/reconstruction_tasks.py"
click node_pf "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/pf_task.py"
click node_opf "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/opf_task.py"
click node_stateest "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/se_task.py"
click node_baselines "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/pf_ac_dc_baseline.py"
click node_opfb "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/opf_ac_dc_baseline.py"
click node_loss "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/training/loss.py"
click node_callbacks "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/training/callbacks.py"
click node_vllm_model "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/model.py"
click node_vllm_config "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/config.py"
click node_codec "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/graph_codec.py"
click node_pf_processor "https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.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_cli,node_config,node_parameters,node_registries,node_user toneBlue
class node_datamodule,node_dataset,node_graphbuilder,node_features,node_normalizers,node_transforms toneAmber
class node_gnn,node_grit,node_gritlayer,node_physics toneMint
class node_base_task,node_reconstruction,node_pf,node_opf,node_stateest,node_baselines,node_opfb,node_loss,node_callbacks toneRose
class node_vllm_model,node_vllm_config,node_codec,node_pf_processor,node_vllm toneIndigo
```

## Components

### User interface

- [CLI workflows](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/cli.py): `gridfm_graphkit/cli.py`
- [Config migration](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/config_version.py): `gridfm_graphkit/io/config_version.py`
- [Component factories](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/param_handler.py): `gridfm_graphkit/io/param_handler.py`
- [Registries](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/io/registries.py): `gridfm_graphkit/io/registries.py`

### Graph data

- [Data module](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/hetero_powergrid_datamodule.py): `gridfm_graphkit/datasets/hetero_powergrid_datamodule.py`
- [Power-grid dataset](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/powergrid_hetero_dataset.py): `gridfm_graphkit/datasets/powergrid_hetero_dataset.py`
- [Graph construction](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/graph_builder.py): `gridfm_graphkit/datasets/graph_builder.py`
- [Feature schema](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/globals.py): `gridfm_graphkit/datasets/globals.py`
- [Normalization](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/normalizers.py): `gridfm_graphkit/datasets/normalizers.py`
- [Positional statistics](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/datasets/posenc_stats.py): `gridfm_graphkit/datasets/posenc_stats.py`

### Model components

- [Heterogeneous GNN](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/gnn_heterogeneous_gns.py): `gridfm_graphkit/models/gnn_heterogeneous_gns.py`
- [GRIT transformer](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/grit_transformer.py): `gridfm_graphkit/models/grit_transformer.py`
- [GRIT layer](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/grit_layer.py): `gridfm_graphkit/models/grit_layer.py`
- [Physics decoders](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/models/utils.py): `gridfm_graphkit/models/utils.py`

### Tasks and training

- [Task base](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/base_task.py): `gridfm_graphkit/tasks/base_task.py`
- [Reconstruction task](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/reconstruction_tasks.py): `gridfm_graphkit/tasks/reconstruction_tasks.py`
- [Power flow task](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/pf_task.py): `gridfm_graphkit/tasks/pf_task.py`
- [Optimal flow task](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/opf_task.py): `gridfm_graphkit/tasks/opf_task.py`
- [State estimation](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/se_task.py): `gridfm_graphkit/tasks/se_task.py`
- [AC/DC baselines](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/pf_ac_dc_baseline.py): `gridfm_graphkit/tasks/pf_ac_dc_baseline.py`
- [OPF baselines](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/tasks/opf_ac_dc_baseline.py): `gridfm_graphkit/tasks/opf_ac_dc_baseline.py`
- [Loss functions](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/training/loss.py): `gridfm_graphkit/training/loss.py`
- [Training callbacks](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/training/callbacks.py): `gridfm_graphkit/training/callbacks.py`

### Inference serving

- [vLLM model](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/model.py): `gridfm_graphkit/vllm/model.py`
- [Inference bundle](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/config.py): `gridfm_graphkit/vllm/config.py`
- [Graph codec](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/graph_codec.py): `gridfm_graphkit/vllm/graph_codec.py`
- [PF request processor](https://github.com/gridfm/gridfm-graphkit/blob/main/gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py): `gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py`

### Other components

- **User**
- **vLLM runtime**

## Connections

- User → CLI workflows: invokes (evidence: `README.md`)
- CLI workflows → Config migration: resolves config (evidence: `gridfm_graphkit/cli.py`)
- CLI workflows → Data module: sets up data (evidence: `gridfm_graphkit/cli.py`)
- CLI workflows → Component factories: loads task (evidence: `gridfm_graphkit/cli.py`)
- CLI workflows → Training callbacks: configures callbacks (evidence: `gridfm_graphkit/cli.py`)
- Data module → Power-grid dataset: creates dataset (evidence: `gridfm_graphkit/datasets/hetero_powergrid_datamodule.py`)
- Data module → Normalization: fits normalizers (evidence: `gridfm_graphkit/datasets/hetero_powergrid_datamodule.py`)
- Data module → Positional statistics: uses statistics (evidence: `gridfm_graphkit/datasets/hetero_powergrid_datamodule.py`)
- Power-grid dataset → Graph construction: builds graphs (evidence: `gridfm_graphkit/datasets/powergrid_hetero_dataset.py`)
- Power-grid dataset → Normalization: normalizes data (evidence: `gridfm_graphkit/datasets/powergrid_hetero_dataset.py`)
- Component factories → Registries: creates components (evidence: `gridfm_graphkit/io/param_handler.py`)
- Component factories → Loss functions: creates losses (evidence: `gridfm_graphkit/io/param_handler.py`)
- Reconstruction task → Component factories: loads model and loss (evidence: `gridfm_graphkit/tasks/reconstruction_tasks.py`)
- Reconstruction task → Task base: extends (evidence: `gridfm_graphkit/tasks/reconstruction_tasks.py`)
- GRIT transformer → GRIT layer: uses layer (evidence: `gridfm_graphkit/models/grit_transformer.py`)
- Heterogeneous GNN → Feature schema: uses schema (evidence: `gridfm_graphkit/models/gnn_heterogeneous_gns.py`)
- GRIT transformer → Feature schema: uses schema (evidence: `gridfm_graphkit/models/grit_transformer.py`)
- Power flow task → Feature schema: uses schema (evidence: `gridfm_graphkit/tasks/pf_task.py`)
- Optimal flow task → Feature schema: uses schema (evidence: `gridfm_graphkit/tasks/opf_task.py`)
- Power flow task → Physics decoders: uses decoders (evidence: `gridfm_graphkit/tasks/pf_task.py`)
- Optimal flow task → Physics decoders: uses decoders (evidence: `gridfm_graphkit/tasks/opf_task.py`)
- Power flow task → Loss functions: computes losses
- Optimal flow task → Loss functions: computes losses
- vLLM model → Inference bundle: loads config (evidence: `gridfm_graphkit/vllm/model.py`)
- vLLM model → Graph codec: uses codec (evidence: `gridfm_graphkit/vllm/model.py`)
- PF request processor → Inference bundle: builds bundle (evidence: `gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py`)
- PF request processor → Graph construction: constructs graphs (evidence: `gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py`)
- PF request processor → Graph codec: encodes graphs (evidence: `gridfm_graphkit/vllm/plugins/pf_reconstruction/io_processor.py`)
- vLLM runtime → PF request processor: dispatches requests
