> 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 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:

```json
\{
  "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.

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