Merge pull request #70 from srl-labs/annotations

support annotation json

Author: FloSch62

.gitignore

@@ -182,4 +182,5 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
-# End of https://www.toptal.com/developers/gitignore/api/python
+CLAUDE.md
+AGENTS.md

src/clab_io_draw/clab2drawio.py

@@ -279,7 +279,9 @@ def main(
         os.makedirs(output_folder, exist_ok=True)
 
         grafana_dashboard = GrafanaDashboard(
-            diagram, grafana_config_path=grafana_config_path, grafana_interface_format=grafana_interface_format
+            diagram,
+            grafana_config_path=grafana_config_path,
+            grafana_interface_format=grafana_interface_format,
         )
         panel_config = grafana_dashboard.create_panel_yaml()
 
@@ -334,7 +336,9 @@ def cli(  # noqa: B008
         None, "--grafana-config", help="Path to Grafana YAML config"
     ),  # noqa: B008
     grafana_interface_format: str | None = typer.Option(
-        None, "--grafana-interface-format", help="Regex pattern for mapping interface names (e.g., 'e1-{x}:ethernet1/{x}')"
+        None,
+        "--grafana-interface-format",
+        help="Regex pattern for mapping interface names (e.g., 'e1-{x}:ethernet1/{x}')",
     ),  # noqa: B008
     include_unlinked_nodes: bool = typer.Option(
         False, "--include-unlinked-nodes", help="Include nodes without links"

src/clab_io_draw/core/data/node_link_builder.py

@@ -24,6 +24,7 @@ def __init__(
         self.styles = styles
         self.prefix = prefix
         self.lab_name = lab_name
+        self.annotations = containerlab_data.get("annotations")
 
     def format_node_name(self, base_name: str) -> str:
         """
@@ -62,28 +63,50 @@ def _build_nodes(self):
         node_height = self.styles.get("node_height", 75)
         base_style = self.styles.get("base_style", "")
 
+        # Create mapping of node annotations by id if annotations exist
+        node_annotations_map = {}
+        if self.annotations and "nodeAnnotations" in self.annotations:
+            for annotation in self.annotations["nodeAnnotations"]:
+                node_annotations_map[annotation["id"]] = annotation
+
         nodes = {}
         for node_name, node_data in nodes_from_clab.items():
             formatted_node_name = self.format_node_name(node_name)
 
-            # Extract position from graph-posX and graph-posY labels if available
+            # Initialize default values
             pos_x = node_data.get("pos_x", "")
             pos_y = node_data.get("pos_y", "")
+            graph_icon = None
+            graph_level = None
 
-            # Check for graph-posX and graph-posY in labels
+            # First check labels (lower priority)
             labels = node_data.get("labels", {})
             if "graph-posX" in labels:
                 pos_x = labels["graph-posX"]
             if "graph-posY" in labels:
                 pos_y = labels["graph-posY"]
+            if "graph-icon" in labels:
+                graph_icon = labels["graph-icon"]
+            if "graph-level" in labels:
+                graph_level = labels["graph-level"]
+
+            # Then check annotations (higher priority - overrides labels)
+            if node_name in node_annotations_map:
+                annotation = node_annotations_map[node_name]
+                if "position" in annotation:
+                    pos_x = str(annotation["position"]["x"])
+                    pos_y = str(annotation["position"]["y"])
+                if "icon" in annotation:
+                    graph_icon = annotation["icon"]
+                # Note: graph-level could be added to annotations if needed
 
             node = Node(
                 name=formatted_node_name,
                 label=node_name,
                 kind=node_data.get("kind", ""),
                 mgmt_ipv4=node_data.get("mgmt_ipv4", ""),
-                graph_level=node_data.get("labels", {}).get("graph-level", None),
-                graph_icon=node_data.get("labels", {}).get("graph-icon", None),
+                graph_level=graph_level,
+                graph_icon=graph_icon,
                 base_style=base_style,
                 custom_style=self.styles.get(node_data.get("kind", ""), ""),
                 pos_x=pos_x,

src/clab_io_draw/core/data/topology_loader.py

@@ -1,4 +1,6 @@
+import json
 import logging
+import os
 
 import yaml
 
@@ -21,9 +23,10 @@ class TopologyLoader:
     def load(self, input_file: str) -> dict:
         """
         Load the containerlab YAML topology file, including environment-variable expansion.
+        Also loads annotations from .annotations.json file if it exists.
 
         :param input_file: Path to the containerlab YAML file.
-        :return: Parsed containerlab topology data with env variables expanded.
+        :return: Parsed containerlab topology data with env variables expanded and annotations.
         :raises TopologyLoaderError: If file not found or parse error occurs.
         """
         logger.debug(f"Loading topology from file: {input_file}")
@@ -35,6 +38,19 @@ def load(self, input_file: str) -> dict:
             expanded_content = expand_env_vars(raw_content)
 
             containerlab_data = yaml.safe_load(expanded_content)
+
+            # Load annotations if .annotations.json file exists
+            annotations_file = f"{input_file}.annotations.json"
+            if os.path.exists(annotations_file):
+                logger.debug(f"Loading annotations from: {annotations_file}")
+                with open(annotations_file) as f:
+                    annotations = json.load(f)
+                containerlab_data["annotations"] = annotations
+                logger.debug("Annotations successfully loaded.")
+            else:
+                logger.debug(f"No annotations file found at: {annotations_file}")
+                containerlab_data["annotations"] = None
+
             logger.debug("Topology successfully loaded.")
             return containerlab_data
 

src/clab_io_draw/core/grafana/grafana_manager.py

@@ -12,7 +12,12 @@ class GrafanaDashboard:
     Manages the creation of a Grafana dashboard and associated panel config from the diagram data.
     """
 
-    def __init__(self, diagram=None, grafana_config_path: str | None = None, grafana_interface_format: str | None = None):
+    def __init__(
+        self,
+        diagram=None,
+        grafana_config_path: str | None = None,
+        grafana_interface_format: str | None = None,
+    ):
         """
         :param diagram: Diagram object that includes node and link data.
         :param grafana_config_path: Path to the YAML file containing grafana panel config (targets, thresholds, etc.).
@@ -79,42 +84,44 @@ def _map_interface_name(self, interface_name: str) -> str:
         """
         Map interface names for Grafana export using user-provided regex pattern.
         Supports patterns like 'e1-{x}:ethernet1/{x}' to convert 'e1-1' to 'ethernet1/1'.
-        
+
         :param interface_name: Original interface name
         :return: Mapped interface name
         """
         if not self.grafana_interface_format:
             return interface_name
-        
+
         import re
-        
+
         # Parse the pattern format: "before_pattern:after_pattern"
-        if ':' not in self.grafana_interface_format:
-            logger.warning(f"Invalid grafana_interface_format pattern: {self.grafana_interface_format}. Expected format: 'pattern:replacement'")
+        if ":" not in self.grafana_interface_format:
+            logger.warning(
+                f"Invalid grafana_interface_format pattern: {self.grafana_interface_format}. Expected format: 'pattern:replacement'"
+            )
             return interface_name
-        
-        pattern_part, replacement_part = self.grafana_interface_format.split(':', 1)
-        
+
+        pattern_part, replacement_part = self.grafana_interface_format.split(":", 1)
+
         # Convert {x} placeholders to regex capture groups
         # Replace {x} with (\d+) for numeric captures
-        regex_pattern = pattern_part.replace('{x}', r'(\d+)')
-        
+        regex_pattern = pattern_part.replace("{x}", r"(\d+)")
+
         # Convert replacement pattern from {x} to \1, \2, etc.
         replacement = replacement_part
         capture_count = 1
-        while '{x}' in replacement:
-            replacement = replacement.replace('{x}', f'\\{capture_count}', 1)
+        while "{x}" in replacement:
+            replacement = replacement.replace("{x}", f"\\{capture_count}", 1)
             capture_count += 1
-        
+
         try:
             # Try to match and replace
-            match = re.match(f'^{regex_pattern}$', interface_name)
+            match = re.match(f"^{regex_pattern}$", interface_name)
             if match:
-                return re.sub(f'^{regex_pattern}$', replacement, interface_name)
+                return re.sub(f"^{regex_pattern}$", replacement, interface_name)
         except re.error as e:
             logger.warning(f"Invalid regex pattern in grafana_interface_format: {e}")
             return interface_name
-        
+
         # If no pattern matches, return original name
         return interface_name