DSL syntax refinement

Author: networmix

.claude/skills/netgraph-dsl/SKILL.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.0] - 2026-01-10
+
+### Changed
+
+- **BREAKING**: DSL syntax refinement with renamed fields and restructured expansion blocks; see updated [DSL reference](docs/reference/dsl.md)
+
 ## [0.16.0] - 2025-12-21
 
 ### Changed

.claude/skills/netgraph-dsl/references/EXAMPLES.md

@@ -103,52 +103,55 @@ seed: 42
 # Define reusable topology templates
 blueprints:
   Clos_Fabric:
-    groups:
-      spine: {node_count: 2, name_template: "spine{node_num}"}
-      leaf:  {node_count: 4, name_template: "leaf{node_num}"}
-    adjacency:
+    nodes:
+      spine: {count: 2, template: "spine{n}"}
+      leaf:  {count: 4, template: "leaf{n}"}
+    links:
     - source: /leaf
       target: /spine
       pattern: mesh
-      link_params: {capacity: 100, cost: 1}
+      capacity: 100
+      cost: 1
     - source: /spine
       target: /leaf
       pattern: mesh
-      link_params: {capacity: 100, cost: 1}
+      capacity: 100
+      cost: 1
 
 # Instantiate network from templates
 network:
-  groups:
-    site1: {use_blueprint: Clos_Fabric}
-    site2: {use_blueprint: Clos_Fabric}
-  adjacency:
+  nodes:
+    site1: {blueprint: Clos_Fabric}
+    site2: {blueprint: Clos_Fabric}
+  links:
   - source: {path: site1/spine}
     target: {path: site2/spine}
     pattern: one_to_one
-    link_params: {capacity: 50, cost: 10}
+    capacity: 50
+    cost: 10
 
-# Define traffic matrix
-traffic_matrix_set:
+# Define traffic demands
+demands:
   global_traffic:
     - source: ^site1/leaf/
-      sink: ^site2/leaf/
-      demand: 100.0
+      target: ^site2/leaf/
+      volume: 100.0
       mode: combine
-      flow_policy_config: SHORTEST_PATHS_ECMP
+      flow_policy: SHORTEST_PATHS_ECMP
 
 # Define analysis workflow
 workflow:
-- step_type: NetworkStats
+- type: NetworkStats
   name: stats
-- step_type: MaxFlow
+- type: MaxFlow
   name: site_capacity
   source: ^site1/leaf/
-  sink: ^site2/leaf/
+  target: ^site2/leaf/
   mode: combine
   shortest_path: false
-- step_type: MaximumSupportedDemand
+- type: MaximumSupportedDemand
   name: max_demand
-  matrix_name: global_traffic
+  demand_set: global_traffic
 ```
 
 ## Repository Structure

.claude/skills/netgraph-dsl/references/REFERENCE.md

@@ -44,46 +44,40 @@ network:
     # Parallel edges between A->B
     - source: A
       target: B
-      link_params:
-        capacity: 1
-        cost: 1
+      capacity: 1
+      cost: 1
     - source: A
       target: B
-      link_params:
-        capacity: 2
-        cost: 1
+      capacity: 2
+      cost: 1
 
     # Parallel edges between B->C
     - source: B
       target: C
-      link_params:
-        capacity: 1
-        cost: 1
+      capacity: 1
+      cost: 1
     - source: B
       target: C
-      link_params:
-        capacity: 2
-        cost: 1
+      capacity: 2
+      cost: 1
 
     # Alternative path A->D->C
     - source: A
       target: D
-      link_params:
-        capacity: 3
-        cost: 2
+      capacity: 3
+      cost: 2
     - source: D
       target: C
-      link_params:
-        capacity: 3
-        cost: 2
+      capacity: 3
+      cost: 2
 """
 
 # Create the network
 scenario = Scenario.from_yaml(scenario_yaml)
 network = scenario.network
 ```
 
-Note that here we used a simple `nodes` and `links` structure to directly define the network topology. The optional `seed` parameter ensures reproducible results when using randomized workflow steps. In more complex scenarios, you would typically use `groups` and `adjacency` to define groups of nodes and their connections, or even leverage the `blueprints` to create reusable components. This advanced functionality is explained in the [DSL Reference](../reference/dsl.md) and used in the [Clos Fabric Analysis](clos-fabric.md) example.
+Note that here we used a simple `nodes` and `links` structure to directly define the network topology. The optional `seed` parameter ensures reproducible results when using randomized workflow steps. In more complex scenarios, you would typically use node groups with `count` and `template` to define groups of nodes and link rules to define their connections, or even leverage the `blueprints` to create reusable components. This advanced functionality is explained in the [DSL Reference](../reference/dsl.md) and used in the [Clos Fabric Analysis](clos-fabric.md) example.
 
 ### Flow Analysis Variants
 
@@ -138,7 +132,7 @@ result = analyze(network).max_flow_detailed(
 )
 
 # Extract flow value and summary
-(src_label, sink_label), summary = next(iter(result.items()))
+(src_label, target_label), summary = next(iter(result.items()))
 
 print(f"Total flow: {summary.total_flow}")
 print(f"Cost distribution: {summary.cost_distribution}")

CHANGELOG.md

@@ -7,7 +7,7 @@ NetGraph ships with ready-to-run scenarios that demonstrate the DSL, workflow st
 Inspect first, then run:
 
 ```bash
-# Inspect (structure, steps, matrices, failure policies)
+# Inspect (structure, steps, demands, failure policies)
 ngraph inspect scenarios/backbone_clos.yml --detail
 
 # Run and write JSON results next to the scenario (or under --output)
@@ -21,8 +21,8 @@ You can filter output by workflow step names with `--keys` (see each scenario se
 - **Purpose**: Toy 4-node full mesh to exercise MSD search, TM placement, and pairwise MaxFlow.
 - **Highlights**:
 
-  - Failure policy: single link choice (`failure_policy_set.single_link_failure`)
-  - Traffic matrix: pairwise demands across all nodes (`baseline_traffic_matrix`)
+  - Failure policy: single link choice (`failures.single_link_failure`)
+  - Demand set: pairwise demands across all nodes (`baseline_traffic_matrix`)
   - Workflow steps: `msd_baseline`, `tm_placement`, `node_to_node_capacity_matrix`
 
 Run:
@@ -40,9 +40,9 @@ ngraph run scenarios/square_mesh.yaml --keys msd_baseline --stdout
 - **Purpose**: Small Clos/metro fabric with components, SRLG-like risk groups, and multi-step workflow.
 - **Highlights**:
 
-  - Uses `blueprints`, attribute-based adjacency selectors, and hardware component attrs
-  - Failure policy: weighted multi-mode (`failure_policy_set.weighted_modes`)
-  - Traffic matrix: inter-metro DC flows with TE/WCMP policy
+  - Uses `blueprints`, attribute-based link selectors, and hardware component attrs
+  - Failure policy: weighted multi-mode (`failures.weighted_modes`)
+  - Demand set: inter-metro DC flows with TE/WCMP policy
   - Workflow steps: `network_statistics`, `msd_baseline`, `tm_placement`, `cost_power`
 
 Run:
@@ -76,4 +76,4 @@ ngraph run scenarios/nsfnet.yaml --keys node_to_node_capacity_matrix_1 --stdout
 
 ## Notes on results
 
-All runs emit a consistent JSON shape with `workflow`, `steps`, and `scenario` sections. Steps like `MaxFlow` and `TrafficMatrixPlacement` store per-iteration lists under `data.flow_results` with `summary` and optional `cost_distribution` or `min_cut` fields. See Reference → Workflow for the exact schema.
+All runs emit a consistent JSON shape with `workflow`, `steps`, and `scenario` sections. Steps like `MaxFlow` and `TrafficMatrixPlacement` store per-iteration lists under `data.flow_results` with `summary` and optional `cost_distribution` or `min_cut` fields. See Reference -> Workflow for the exact schema.

README.md

@@ -9,7 +9,7 @@ Refer to [Tutorial](../getting-started/tutorial.md) for running bundled scenario
 We'll create two separate 3-tier Clos networks and analyze the maximum flow capacity between them. This scenario showcases:
 
 - Hierarchical blueprint composition
-- Complex adjacency patterns
+- Complex link patterns
 - Flow analysis with different placement policies
 
 ## Programmatic scenario
@@ -21,65 +21,61 @@ from ngraph import analyze, Mode, FlowPlacement
 scenario_yaml = """
 blueprints:
   brick_2tier:
-    groups:
+    nodes:
       t1:
-        node_count: 8
-        name_template: "t1-{node_num}"
+        count: 8
+        template: "t1-{n}"
       t2:
-        node_count: 8
-        name_template: "t2-{node_num}"
+        count: 8
+        template: "t2-{n}"
 
-    adjacency:
+    links:
       - source: /t1
         target: /t2
         pattern: mesh
-        link_params:
-          capacity: 2
-          cost: 1
+        capacity: 2
+        cost: 1
 
   3tier_clos:
-    groups:
+    nodes:
       b1:
-        use_blueprint: brick_2tier
+        blueprint: brick_2tier
       b2:
-        use_blueprint: brick_2tier
+        blueprint: brick_2tier
       spine:
-        node_count: 64
-        name_template: "t3-{node_num}"
+        count: 64
+        template: "t3-{n}"
 
-    adjacency:
+    links:
       - source: b1/t2
         target: spine
         pattern: one_to_one
-        link_params:
-          capacity: 2
-          cost: 1
+        capacity: 2
+        cost: 1
       - source: b2/t2
         target: spine
         pattern: one_to_one
-        link_params:
-          capacity: 2
-          cost: 1
+        capacity: 2
+        cost: 1
 
 network:
   name: "3tier_clos_network"
   version: 1.0
 
-  groups:
+  nodes:
     my_clos1:
-      use_blueprint: 3tier_clos
+      blueprint: 3tier_clos
 
     my_clos2:
-      use_blueprint: 3tier_clos
+      blueprint: 3tier_clos
 
-  adjacency:
+  links:
     - source: my_clos1/spine
       target: my_clos2/spine
       pattern: one_to_one
-      link_count: 4
-      link_params:
-        capacity: 1
-        cost: 1
+      count: 4
+      capacity: 1
+      cost: 1
 """
 
 # Create and analyze the scenario
@@ -104,7 +100,7 @@ print(f"Maximum flow with ECMP: {max_flow_ecmp}")
 The result `{('b1|b2', 'b1|b2'): 256.0}` means:
 
 - **Source**: All t1 nodes in both b1 and b2 segments of my_clos1
-- **Sink**: All t1 nodes in both b1 and b2 segments of my_clos2
+- **Target**: All t1 nodes in both b1 and b2 segments of my_clos2
 - **Capacity**: Maximum flow of 256.0 units
 
 ## ECMP vs WCMP: Impact of Link Failures
@@ -133,26 +129,26 @@ from ngraph.scenario import Scenario
 scenario_yaml = """
 blueprints:
   brick_2tier:
-    groups:
-      t1: {node_count: 8, name_template: "t1-{node_num}"}
-      t2: {node_count: 8, name_template: "t2-{node_num}"}
-    adjacency:
-      - {source: /t1, target: /t2, pattern: mesh, link_params: {capacity: 2, cost: 1}}
+    nodes:
+      t1: {count: 8, template: "t1-{n}"}
+      t2: {count: 8, template: "t2-{n}"}
+    links:
+      - {source: /t1, target: /t2, pattern: mesh, capacity: 2, cost: 1}
   3tier_clos:
-    groups:
-      b1: {use_blueprint: brick_2tier}
-      b2: {use_blueprint: brick_2tier}
-      spine: {node_count: 64, name_template: "t3-{node_num}"}
-    adjacency:
-      - {source: b1/t2, target: spine, pattern: one_to_one, link_params: {capacity: 2, cost: 1}}
-      - {source: b2/t2, target: spine, pattern: one_to_one, link_params: {capacity: 2, cost: 1}}
+    nodes:
+      b1: {blueprint: brick_2tier}
+      b2: {blueprint: brick_2tier}
+      spine: {count: 64, template: "t3-{n}"}
+    links:
+      - {source: b1/t2, target: spine, pattern: one_to_one, capacity: 2, cost: 1}
+      - {source: b2/t2, target: spine, pattern: one_to_one, capacity: 2, cost: 1}
 network:
   name: 3tier_clos_network
-  groups:
-    my_clos1: {use_blueprint: 3tier_clos}
-    my_clos2: {use_blueprint: 3tier_clos}
-  adjacency:
-    - {source: my_clos1/spine, target: my_clos2/spine, pattern: one_to_one, link_count: 4, link_params: {capacity: 1, cost: 1}}
+  nodes:
+    my_clos1: {blueprint: 3tier_clos}
+    my_clos2: {blueprint: 3tier_clos}
+  links:
+    - {source: my_clos1/spine, target: my_clos2/spine, pattern: one_to_one, count: 4, capacity: 1, cost: 1}
 """
 
 scenario = Scenario.from_yaml(scenario_yaml)

docs/examples/basic.md

@@ -5,7 +5,7 @@ This guide shows the fastest way to run a scenario from the CLI and a minimal pr
 ## CLI: run and inspect
 
 ```bash
-# Inspect (validate and preview structure, steps, matrices)
+# Inspect (validate and preview structure, steps, demands)
 ngraph inspect scenarios/square_mesh.yaml --detail
 
 # Run and store results (JSON) next to the scenario or under --output
@@ -28,9 +28,9 @@ network:
     A: {}
     B: {}
   links:
-    - {source: A, target: B, link_params: {capacity: 10.0, cost: 1.0}}
+    - {source: A, target: B, capacity: 10.0, cost: 1.0}
 workflow:
-  - step_type: NetworkStats
+  - type: NetworkStats
     name: baseline_stats
 """