simplify

Signed-off-by: Dmitry Shmulevich <dshmulevich@nvidia.com>

Author: dmitsh

charts/topograph/README.md

@@ -43,7 +43,7 @@ global:
   provider:
     name: dra        # or aws, gcp, oci, nebius, netq, infiniband-k8s, ...
   engine:
-    name: k8s        # or slurm, slinky
+    name: k8s        # or slurm, slinky, graph
 ```
 
 For the full list of values and their defaults, see [`values.yaml`](./values.yaml). Example values files for specific deployment patterns:
@@ -95,7 +95,7 @@ Both are installed together when you install this chart. Their values are access
 - **Project documentation site**: <https://topograph.docs.buildwithfern.com/topograph>
 - **Main repository**: <https://github.com/NVIDIA/topograph>
 - **Provider-specific setup**: `docs/providers/` in the main repository
-- **Engine documentation**: `docs/engines/k8s.md`, `docs/engines/slinky.md`, `docs/engines/slurm.md`
+- **Engine documentation**: `docs/engines/k8s.md`, `docs/engines/slinky.md`, `docs/engines/slurm.md`, `docs/engines/graph.md`
 - **Node-labels reference**: `docs/reference/node-labels.md`
 - **Contributing**: see [`CONTRIBUTING.md`](https://github.com/NVIDIA/topograph/blob/main/CONTRIBUTING.md) in the main repository
 

charts/topograph/values.schema.json

@@ -45,7 +45,7 @@
             "name": {
               "type": "string",
               "description": "Scheduler-output engine. Must match a registered engine in pkg/registry/registry.go.",
-              "enum": ["k8s", "slinky", "slurm"]
+              "enum": ["graph", "k8s", "slinky", "slurm"]
             }
           },
           "required": ["name"]

charts/topograph/values.yaml

@@ -4,10 +4,10 @@
 
 global:
   provider:
-    # name: "aws", "oci", "gcp", "nebius", "netq", "infiniband-k8s", "dra" or "test".
+    # name: "aws", "oci", "gcp", "nebius", "nscale", "netq", "infiniband-k8s", "dra" or "test".
     name: test
   engine:
-    # name: "k8s" or "slinky"
+    # name: "k8s", "slinky", "slurm" or "graph"
     name: k8s
 
   service:

docs/api.md

@@ -20,7 +20,7 @@ http:
 provider: test
 
 # engine: the engine that topograph will use (optional)
-# Valid options include "slurm", "k8s", or "slinky".
+# Valid options include "slurm", "k8s", "slinky", or "graph".
 # Can be overridden if the engine is specified in a topology request to topograph
 engine: slurm
 
@@ -73,11 +73,11 @@ Topograph exposes three endpoints for interacting with the service. Below are th
     - **creds**: (optional) A key-value map with provider-specific parameters for authentication.
     - **params**: (optional) A key-value map with provider-specific parameters. The `test` provider uses these parameters for response simulation; for complete behavior and examples, see [Test Mode and Test Provider](./providers/test.md).
   - **engine**: (optional) Selects the topology output and provides any engine-specific parameters.
-    - **name**: (optional) A string specifying the topology output, either `slurm`, `k8s`, or `slinky`. This parameter will override the engine set in the topograph config.
+    - **name**: (optional) A string specifying the topology output, either `slurm`, `k8s`, `slinky`, or `graph`. This parameter will override the engine set in the topograph config.
     - **params**: (optional) A key-value map with engine-specific parameters.
       - **plugin**: (optional) Used in: [`slurm`, `slinky`]. A string specifying the cluster-wide topology plugin: `topology/tree` or `topology/block`. For `slurm`, this defaults to `topology/tree` when neither `plugin` nor `topologies` is set. Do not set `plugin` together with `topologies`.
       - **blockSizes**: (optional) Used in: [`slurm`, `slinky`]. An array of block sizes for `topology/block`.
-      - **topologyConfigPath**: Used in: [`slurm`, `slinky`]. Optional for `slurm`; required for `slinky`. For `slurm`, a file path for the topology configuration; if omitted, the topology config content is returned in the HTTP response. For `slinky`, the key for the topology config in the ConfigMap.
+      - **topologyConfigPath**: Used in: [`slurm`, `slinky`, `graph`]. Optional for `slurm` and `graph`; required for `slinky`. For `slurm`, a file path for the topology configuration; if omitted, the topology config content is returned in the HTTP response. For `slinky`, the key for the topology config in the ConfigMap. For `graph`, an existing path on the Topograph host where instance JSON should be written; if omitted, the JSON is returned in the topology response.
       - **topologies**: (optional) Used in: [`slurm`, `slinky`]. A map of named per-partition topology settings. Do not set top-level `plugin` together with `topologies`.
         - **plugin**: Used in: [`slurm`, `slinky`]. A required string specifying the per-partition topology plugin: `topology/tree`, `topology/block`, or `topology/flat`.
         - **blockSizes**: (optional) Used in: [`slurm`, `slinky`]. An array of block sizes for `topology/block`.

docs/engines/graph.md

@@ -0,0 +1,68 @@
+# Topograph Graph Engine
+
+The `graph` engine returns instance-oriented topology metadata as JSON. It is intended for clients that need per-instance GPU and placement 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 instance metadata, while the `graph` engine only assembles and emits the requested instance records.
+
+## Output
+
+By default, the generated JSON is returned in the `/v1/topology` response:
+
+```json
+{
+  "instances": [
+    {
+      "id": "I21",
+      "type": "H100",
+      "provider": "test",
+      "region": "us-west",
+      "network_layers": ["leaf-a", "spine-a"],
+      "attributes": {
+        "nvlink": "nvl-1",
+        "gpu": {
+          "status": "known",
+          "collected_at": "2026-01-01T13:59:00.000Z",
+          "gpus": [
+            {
+              "index": 0,
+              "pci_bus_id": "00000000:0F:00.0",
+              "uuid": "GPU-example",
+              "model": "NVIDIA H100 SXM5 80GB",
+              "memory_mib": 81920
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+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"
+  },
+  "nodes": [
+    {
+      "region": "none",
+      "instances": {
+        "I21": "n-I21",
+        "I22": "n-I22"
+      }
+    }
+  ]
+}
+```

docs/get-started/quickstart-k8s.md

@@ -1,6 +1,6 @@
 # Install on Kubernetes
 
-Topograph installs on a Kubernetes cluster via a Helm chart. The same chart supports two engines:
+Topograph installs on a Kubernetes cluster via a Helm chart. This quickstart covers the two Kubernetes-facing scheduler engines:
 
 - **[`k8s` engine](#engine-k8s)** — labels Kubernetes nodes with topology keys so schedulers (native `podAffinity`, KAI Scheduler, Kueue TAS, etc.) can make topology-aware placement decisions
 - **[`slinky` engine](#engine-slinky)** — writes Slurm topology configuration into a `ConfigMap` for [Slinky](https://github.com/SlinkyProject) (Slurm-on-Kubernetes) deployments

docs/index.yml

@@ -49,6 +49,8 @@ navigation:
         path: engines/k8s.md
       - page: Slinky
         path: engines/slinky.md
+      - page: Graph
+        path: engines/graph.md
 
   - section: Reference
     contents:

docs/modeling.md

@@ -126,8 +126,9 @@ The `nodes` map describes compute nodes directly. Each key is the node name. The
 
 | Field | Description |
 |---|---|
-| `name` | Optional. If set, it must match the map key. Usually omitted. |
-| `capacity_block_id` | Optional accelerated domain ID. If set and `capacity_blocks` is omitted, Topograph creates the corresponding capacity block entry. |
+| `id` | Optional. If set, it must match the map key. Usually omitted. |
+| `type` | Optional instance type metadata used by instance-oriented exports. |
+| `capacity_block` | Optional accelerated domain ID. If set and `capacity_blocks` is omitted, Topograph creates the corresponding capacity block entry. |
 | `attributes.nvlink` | Optional accelerated-domain / NVLink identifier. Used by block topology simulation paths. |
 | `attributes.status` | Optional node status metadata. |
 | `attributes.timestamp` | Optional timestamp metadata. |
@@ -138,7 +139,7 @@ Example:
 ```yaml
 nodes:
   n1:
-    capacity_block_id: cb1
+    capacity_block: cb1
     attributes:
       nvlink: nvl1
   n2:
@@ -148,10 +149,10 @@ nodes:
 
 Node rules:
 
-- `capacity_block_id` is optional.
-- Nodes without `capacity_block_id` are still valid compute nodes.
-- If `capacity_block_id` is set and `capacity_blocks` is omitted, Topograph creates the capacity block and adds the node to it.
-- If a node is listed under `capacity_blocks.<id>.nodes`, Topograph fills in the node's missing `capacity_block_id`.
+- `capacity_block` is optional.
+- Nodes without `capacity_block` are still valid compute nodes.
+- If `capacity_block` is set and `capacity_blocks` is omitted, Topograph creates the capacity block and adds the node to it.
+- If a node is listed under `capacity_blocks.<id>.nodes`, Topograph fills in the node's missing `capacity_block`.
 - If both sides specify different capacity block IDs for the same node, model loading fails.
 
 ## Capacity Blocks
@@ -210,7 +211,7 @@ After YAML parsing, Topograph completes the model before simulation uses it:
 - Node names are copied from their map keys.
 - Switch names are copied from their map keys.
 - Missing nodes can be created from `capacity_blocks.<id>.nodes`.
-- Missing capacity block entries can be created from node `capacity_block_id` values.
+- Missing capacity block entries can be created from node `capacity_block` values.
 - Node `NetLayers` is derived from the switch path from leaf to root.
 - Node `Metadata` is built by merging switch metadata along the same path.
 - `Instances` is derived from node names and grouped by `metadata.region`; nodes without a region use `none`.
@@ -249,12 +250,12 @@ After loading:
 
 ### Capacity Blocks From Nodes
 
-This model omits `capacity_blocks`. Topograph creates `cb1` from `n1.capacity_block_id`.
+This model omits `capacity_blocks`. Topograph creates `cb1` from `n1.capacity_block`.
 
 ```yaml
 nodes:
   n1:
-    capacity_block_id: cb1
+    capacity_block: cb1
     attributes:
       nvlink: nvl1
   n2:
@@ -275,7 +276,7 @@ This is valid. It declares a capacity block that currently has no nodes.
 ```yaml
 nodes:
   n1:
-    capacity_block_id: cb1
+    capacity_block: cb1
 
 capacity_blocks:
   cb1: {}
@@ -368,5 +369,5 @@ Before using a new model in a regression test:
 - Confirm every switch child has only one parent.
 - Confirm every switched node is defined in `nodes` or generated from `capacity_blocks`.
 - Confirm no node appears under two switches.
-- Confirm capacity block membership does not conflict with node `capacity_block_id`.
+- Confirm capacity block membership does not conflict with node `capacity_block`.
 - Run the relevant provider simulation test or API flow with the target engine.

docs/overview.md

@@ -49,6 +49,7 @@ Currently supported engines:
 - [SLURM](./engines/slurm.md)
 - [Kubernetes](./engines/k8s.md)
 - [SLURM-on-Kubernetes (Slinky)](./engines/slinky.md)
+- [Graph](./engines/graph.md) - returns instance-oriented topology metadata as JSON
 
 ### Choosing a Provider
 

docs/providers/test.md

@@ -93,7 +93,7 @@ The test provider is configured through `provider.params` in the `/v1/generate`
 }
 ```
 
-The `engine` object follows the normal Topograph engine configuration. For example, use `slurm` parameters to request `topology/tree` or `topology/block` output, use `k8s` parameters to write node labels, or use `slinky` parameters to update a Slinky ConfigMap.
+The `engine` object follows the normal Topograph engine configuration. For example, use `slurm` parameters to request `topology/tree` or `topology/block` output, use `k8s` parameters to write node labels, use `slinky` parameters to update a Slinky ConfigMap, or use `graph` to return model-backed instance metadata as JSON.
 
 ### Test Provider Parameters