Topograph Graph Engine#

The graph engine returns instance-oriented topology metadata as JSON. It is intended for clients that need per-instance placement and accelerator-domain context rather than scheduler-specific output such as topology.conf, Kubernetes node labels, or a Slinky ConfigMap.

The engine preserves the provider/engine boundary: providers still discover topology and optional instance metadata, carry it on the canonical topology graph, and the graph engine only formats those records.

Output#

By default, the generated JSON is returned in the /v1/topology response:

{
  "instances": [
    {
      "id": "I21",
      "type": "H100",
      "network_layers": ["leaf-a", "spine-a"],
      "attributes": {
        "nvlink": "nvl-1"
      }
    }
  ]
}

Set engine.params.topologyConfigPath to write the JSON to an existing validated path on the Topograph host. When topologyConfigPath is set, the HTTP result body is OK.

Request#

The engine needs the instance IDs to export. Supply nodes in the request, or use a provider that can supply compute instances directly. The initial implementation is covered by the test provider and model-backed simulation providers.

{
  "provider": {
    "name": "test",
    "params": {
      "modelFileName": "small-tree.yaml"
    }
  },
  "engine": {
    "name": "graph",
    "params": {
      "topologyConfigPath": "topology.json"
    }
  }
}