> This page is for Topograph, version v1.0.0.
> For other versions, use one of these documentation indexes:
> - Latest · v1.1.0 (default): https://docs.nvidia.com/topograph/v1.1.0/llms.txt
> - v1.0.0: https://docs.nvidia.com/topograph/v1.0.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/topograph/v0.5.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/topograph/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/topograph/_mcp/server.

# Topograph Graph Engine

The `graph` engine returns instance-oriented topology labels 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 labels, carry them 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.

Each instance entry contains:
- `id` — the provider instance ID
- `network_layers` — switch names or IDs in closest-first order (tier 0 is the switch directly connected to the node, increasing outward); the depth is variable and provider-dependent
- `labels` — per-instance topology labels inherited from the model or provider
  (for example, XCLR domain and optional sub-domain)

```json
{
  "instances": [
    {
      "id": "I21",
      "network_layers": ["leaf-a", "spine-a"],
      "labels": {
        "example.com/gpu-product": "H100",
        "accelerator.topograph.run/domain": "nvl-1",
        "accelerator.topograph.run/sub-domain": "nvl-1.rack-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.

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