Feature annotation

[harsh-sikhwal]

Summary

Reworks the annotation and get_graph APIs to support richer, batched annotations and a structured graph response format.

Annotation API

• Replaces AnnotateRequest with a new Annotation schema. The old flat (name, attribute, value) triples are replaced with Annotation.Node, Annotation.Edge, and Annotation.Link objects, each carrying a list of Annotation.Attribute (attribute/value) pairs.
• Adds link annotations: annotating a link name applies the attributes to every edge sharing that link.
• Adds slice / prefix expansion for node and edge names via the new _expand_node_string helper, so a single annotation can target many graph elements:
  • dgx[0:3] → dgx.0, dgx.1, dgx.2
  • dgx[0:2]cpu[0:2] → cartesian product over both slices
  • dgx.0 → all nodes under the dgx.0 prefix
• Protects an _IMMUTABLE_ATTRIBUTES set (type, instance, instance_idx, device, composed_device, link) — annotating these now raises ValueError.
• Adds _build_prefix_map and _build_link_map to make node-prefix and link-name lookups O(1) per annotation.

get_graph API

• GraphRequest now selects between two return formats:
  • infragraph — structured response containing the original Infrastructure plus the Annotation object.
  • networkx — the existing networkx node-link YAML string.
• Each format takes an Annotation.Config with choice of full (every attribute) or partial (annotations only, excluding immutable infrastructure-derived attributes).
• set_graph now resets annotations as part of building the graph.

Tests

• Migrates test_ipaddress_annotations, test_rank_annotations, and test_shortest_path to the new Annotation schema.
• Adds test_expand_node_string.py covering the slice-expansion grammar (single name, single slice, multi-segment, mixed slice/no-slice, empty input).

Test plan

• pytest src/tests/test_expand_node_string.py
• pytest src/tests/test_ipaddress_annotations.py src/tests/test_rank_annotations.py src/tests/test_shortest_path.py
• Round-trip get_graph in both infragraph and networkx formats with full and partial annotation modes
• Verify annotating an immutable attribute (e.g. type) raises ValueError
• Verify link annotation applies attributes to all edges sharing that link