InfraGraph (INFRAstructure GRAPH)

InfraGraph defines a model-driven, vendor-neutral API for capturing a system of systems suitable for use in co-designing AI/HPC solutions.

The model and API allows for defining physical infrastructure using a standardized graph like terminology.

In addition to the base graph definition, user provided annotations can extend the graph allowing for an unlimited number of different physical and/or logical characteristics/view.

Additional information such as background, schema and examples can be found in the online documentation.

Using InfraGraph CLI

InfraGraph ships with a CLI that lets you convert existing system descriptions into InfraGraph format and visualize infrastructure topologies.

Install using pip:

pip install infragraph

Or clone the repo and run make clean && make install, or download the .whl from releases and install it with pip install infragraph-<version>.whl.

Convert system formats to InfraGraph — translate output from tools like lstopo directly into an InfraGraph YAML/JSON definition:

# Convert lstopo XML output to an InfraGraph YAML file
infragraph translate lstopo -i lstopo_output.xml -o my_device.yaml --dump yaml

Visualize infrastructure topologies — generate an interactive, drillable HTML visualization from any InfraGraph definition:

# Generate a visualization with host and switch hints
infragraph visualize -i my_infrastructure.yaml -o ./viz --hosts "dgx_a100" --switches "leaf_switch,spine_switch"
# Then open ./viz/index.html in a browser

The visualizer produces a multi-level view: a top-level graph of instances and inter-device connectivity, with drill-down into each device's internal components (xPUs, NICs, CPUs, memory, PCIe topology, etc.). For large topologies the visualizer can compress the infrastructure view. A Compressed button appears in the header for fabrics with more than 128 hosts. It merges nodes that have identical connectivity into a single node, and a slider next to it chooses how aggressively, from merging equivalent neighbours up to one node per tier. Groups are named from the data: a bottom-tier group whose members all uplink to one switch is shown as a rack, and several such racks merged is shown as a pod.

Clicking a rack or pod opens it rather than jumping straight into a device template. You see its actual member servers together with the switches they uplink to, and a hop slider controls how much surrounding fabric comes with them. Clicking a server there drills into that device's internals as usual, so the trail reads Infrastructure, then rack, then device. Switch groups behave differently and go straight to the device template, because every switch in a group is an instance of the same device. At the highest compression rungs a single node can stand for every server in the fabric, and those are left closed since expanding one would build thousands of nodes; lower the compression to reach a group you can open. Passing --hosts helps the visualizer identify the bottom tier.

Note: More converters and tools are work-in-progress. See the Ecosystem documentation for the full roadmap and we invite contributions from the community.

Chakra + InfraGraph Ecosystem

MLCommons Chakra captures AI workload details as Execution Traces — graphs of operators, tensors, dependencies, and timing. InfraGraph complements Chakra by representing the underlying infrastructure — hosts, NICs, xPUs/accelerators, interconnects, and topologies. Together, Chakra + InfraGraph let you pair workload traces with infrastructure blueprints to analyze current systems and co-design future ones, while safely sharing artifacts across teams and partners.

For more details, see the Ecosystem documentation.

Versioning Rules

Infragraph follows a structured versioning scheme to maintain consistency across releases and ensure clear dependency management. Each version reflects compatibility, schema evolution, and API stability expectations.

For versioning rules, refer this readme.

Contributing

Contributions can be made in the following ways:

• open an issue in the repository
• fork the models repository and submit a PR