Using the knowledge graph explorer

The Knowledge Graph Explorer is a generated view of the Torch-Spyre codebase. Sphinx rebuilds it from the source tree on every documentation build, so it matches the code at the commit it was built from. Every node records the file and line it came from, and the panel below the graph links to that location.

This page describes what you can do with it. The first half is for people running models on Spyre. The second is for people working on the backend.

What it is for

Torch-Spyre is a few hundred Python modules plus a C++ runtime. Most of the useful facts are relationships: a PyTorch op is handled by a lowering, that lowering is part of a pass group, and the pass group reads an environment variable. These relationships are spread across decorators, class definitions, and import statements, so reading them one file at a time is slow. A diagram maintained by hand goes out of date as soon as someone merges a PR.

The explorer avoids that. It reads the structure directly from the code with Python’s ast module at build time, so the graph shows the current code rather than a description of it.

For users

If you run models through torch.compile, the two most useful views are Operations and Configuration.

Checking whether an op is supported

Open the Operations view and search for the op, for example mm or softmax. The node color and its outgoing edge show how the backend handles it:

Decomposition: the op is rewritten into smaller ops before it runs on the hardware.
Lowering: the op maps to a Spyre kernel during compilation.
Custom op: a hand-written Spyre operator implements it.
CPU fallback (dashed red edge): the op runs on the host instead of the accelerator. Fallbacks cause graph breaks and slowdowns, so check this view when a model is slower than you expect.
Eager kernel: the op has a direct implementation that also works outside torch.compile.

If an op is not in the graph, the backend has no registration for it. That is a concrete answer, and a useful detail to include when you file an issue.

Finding the variable that controls a behavior

The Configuration view shows every environment variable the code reads (SENCORES, LX_PLANNING, TORCH_SPYRE_DEBUG, and the rest) and the module that reads it. To change runtime or compilation behavior, use this view to find the variable, then follow the source link to the code that reads it, where you can see the accepted values and the default.

For developers

For contributors, the explorer helps with two things: learning an unfamiliar area, and checking what a change affects.

Exploring an unfamiliar subsystem

The Architecture view shows module dependencies and class inheritance for the torch_spyre package. When you start working in a subsystem you have not seen before, find the class you were pointed to, turn on Focus to hide everything else, and read its base classes and the modules that import it. That is usually enough to decide where to set a breakpoint.

Opening the source

Every node with a single definition site is a link. Click it to see the file and line in the panel, or double-click to open that definition on GitHub in a new tab. The link uses the commit the graph was built from, so the line number stays correct even after the code moves.

Checking what a change affects

Two relationships are worth tracing before you refactor:

imports edges (Architecture view) show which modules depend on the one you are changing. Focus the module node to see the inbound edges.
inherits_from edges show the subclasses a base-class change affects.

This does not replace running the tests, but it shows you where to look.

Learning the op registration patterns

When you add an operation, the Operations view shows the ops already implemented with each pattern. Filter to the op family you are working on and open the existing decomposition, lowering, or custom-op definitions. Use this with the Spyre Inductor Operation Cookbook guide: the guide explains the three patterns, and the graph shows every op that uses each one, with a link to its code.

Viewing the compiler pipeline

The Compiler Passes view shows each Custom*Passes group and the pass functions it runs, in pipeline order from top to bottom. Use it to see where a transformation happens and what runs before it, before you add or reorder a pass.

Accuracy and limits

Three properties are worth relying on:

The graph is rebuilt on every documentation build. A Sphinx extension runs docs/source/_ext/extract_graph.py and writes a fresh graph.json, so there is no stored copy that can go out of date.
Extraction is syntactic. It parses the source with ast and imports nothing, so it runs without Spyre hardware or the C++ extensions and is not affected by import-time side effects.
Source links are commit-pinned. They use the commit the graph was built from, and use the default branch only when the build runs outside a git checkout.

The graph covers registrations, class hierarchies, imports, dataclass fields, and environment-variable reads. It does not trace runtime call graphs or data flow, and it only parses the files listed in build_graph(). If a new registration pattern or source file is not showing up, the extractor needs updating. The Contributing notes and the check-docs checklist explain how.