Allow string labels in Bin primitive

- remove integer cast for bin labels during deserialization\n- update Bin typing to support non-integer labels\n- add serialization/transform tests for string labels\n\nImplements #96

Author: matthewhorridge

src/harmonization_framework/primitives/bin_primitive.py

@@ -1,8 +1,8 @@
 from .base import PrimitiveOperation, support_iterable
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
 class _IntervalNode:
-    def __init__(self, label: int, lower: int, upper: int, left=None, right=None):
+    def __init__(self, label: Any, lower: int, upper: int, left=None, right=None):
         self.label = label
         self.lower = lower
         self.upper = upper
@@ -15,7 +15,7 @@ class Bin(PrimitiveOperation):
     Assign values into histogram bins. 
     Performs a range query using an interval tree. Bins must not overlap.
     """
-    def __init__(self, bins: List[Tuple[int, Tuple[int]]]):
+    def __init__(self, bins: List[Tuple[Any, Tuple[int, int]]]):
         self.bins = self._validate_bins(bins)
         self._tree = self._build_tree(self.bins, 0, len(self.bins)-1)
 
@@ -35,13 +35,13 @@ def to_dict(self):
         return output
 
     @support_iterable
-    def transform(self, value: int) -> int:
+    def transform(self, value: int) -> Any:
         transformed = self._query(value, self._tree)
         if transformed is None:
             print(f"Warning: value={value} does not belong to a bin.")
         return transformed
 
-    def _query(self, value: int, node: _IntervalNode) -> int:
+    def _query(self, value: int, node: _IntervalNode) -> Any:
         if node is None:
             return None
         if value < node.lower:
@@ -52,7 +52,7 @@ def _query(self, value: int, node: _IntervalNode) -> int:
             return node.label
         return None
 
-    def _build_tree(self, bins: List[Tuple[int, Tuple[int]]], left: int, right: int):
+    def _build_tree(self, bins: List[Tuple[Any, Tuple[int, int]]], left: int, right: int):
         if left > right:
             return None
 
@@ -68,7 +68,7 @@ def _build_tree(self, bins: List[Tuple[int, Tuple[int]]], left: int, right: int)
         )
         return node
 
-    def _validate_bins(self, bins: List[Tuple[int, Tuple[int]]]) -> List[Tuple[int, Tuple[int]]]:
+    def _validate_bins(self, bins: List[Tuple[Any, Tuple[int, int]]]) -> List[Tuple[Any, Tuple[int, int]]]:
         normalized = []
         for label, (start, end) in bins:
             if start > end:
@@ -91,7 +91,7 @@ def _validate_bins(self, bins: List[Tuple[int, Tuple[int]]]) -> List[Tuple[int,
     @classmethod
     def from_serialization(cls, serialization):
         bins = [
-            (int(interval["label"]), (int(interval["start"]), int(interval["end"])))
+            (interval["label"], (int(interval["start"]), int(interval["end"])))
             for interval in serialization["bins"]
         ]
         return Bin(bins)

tests/test_primitives_serialization.py

@@ -42,6 +42,21 @@ def test_bin_serialization_and_transform():
     assert primitive.transform([3, 12]) == [low_label, high_label]
 
 
+def test_bin_string_labels_roundtrip_and_transform():
+    primitive = Bin([("child", (0, 12)), ("adult", (13, 120))])
+    payload = primitive.to_dict()
+
+    assert payload["bins"] == [
+        {"label": "child", "start": 0, "end": 12},
+        {"label": "adult", "start": 13, "end": 120},
+    ]
+
+    roundtrip = Bin.from_serialization(payload)
+    assert roundtrip.to_dict() == payload
+    assert roundtrip.transform(7) == "child"
+    assert roundtrip.transform(34) == "adult"
+
+
 def test_bin_rejects_overlapping_bins():
     with pytest.raises(ValueError, match="Overlapping bins detected"):
         Bin([(1, (0, 10)), (2, (10, 20))])