fix: handle Union types in generic type argument validation

GenericType.validate() now correctly checks compatibility when a generic
type argument is a Union (e.g., Converter[str, str] is accepted for
Param[Converter[str, Union[str, List[str], ...]]]).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bpiwowar

src/experimaestro/core/types.py

@@ -837,6 +837,47 @@ def __repr__(self):
         return str(self)
 
 
+def _is_type_arg_compatible(actual, expected) -> bool:
+    """Check if an actual type argument is compatible with the expected one.
+
+    Handles Union types: actual is compatible with Union[X, Y, Z] if actual
+    is a subtype of any member of the union.
+    """
+    # Both concrete types: use subclass check
+    if isinstance(expected, type) and isinstance(actual, type):
+        return issubclass(actual, expected)
+
+    # Expected is a Union: actual must be compatible with at least one member
+    if get_origin(expected) is typing.Union:
+        return any(
+            _is_type_arg_compatible(actual, member) for member in get_args(expected)
+        )
+
+    # Actual is a Union: each member of actual must be compatible with expected
+    if get_origin(actual) is typing.Union:
+        return all(
+            _is_type_arg_compatible(member, expected) for member in get_args(actual)
+        )
+
+    # For generic types (e.g., List[str]), check origin and args recursively
+    expected_origin = get_origin(expected)
+    actual_origin = get_origin(actual)
+    if expected_origin is not None and actual_origin is not None:
+        if not issubclass(actual_origin, expected_origin):
+            return False
+        expected_args = get_args(expected)
+        actual_args = get_args(actual)
+        if expected_args and actual_args:
+            return all(
+                _is_type_arg_compatible(a, e)
+                for a, e in zip(actual_args, expected_args)
+            )
+        return True
+
+    # Fallback: exact equality
+    return expected == actual
+
+
 class GenericType(Type):
     def __init__(self, type: typing.Type):
         self.type = type
@@ -873,17 +914,11 @@ def validate(self, value):
             for expected, actual in zip(self.args, matching_args):
                 if isinstance(expected, TypeVar) or isinstance(actual, TypeVar):
                     continue
-                if isinstance(expected, type) and isinstance(actual, type):
-                    if not issubclass(actual, expected):
-                        raise TypeError(
-                            f"{type(value).__qualname__} has type argument "
-                            f"{actual.__qualname__} which is not a subtype of "
-                            f"expected {expected.__qualname__}"
-                        )
-                elif expected != actual:
+                if not _is_type_arg_compatible(actual, expected):
                     raise TypeError(
                         f"{type(value).__qualname__} has type argument "
-                        f"{actual} which does not match expected {expected}"
+                        f"{actual} which is not compatible with "
+                        f"expected {expected}"
                     )
 
         return value

src/experimaestro/tests/core/test_generics.py

@@ -1,6 +1,6 @@
 """Tests for the use of generics in configurations"""
 
-from typing import Generic, Optional, TypeVar
+from typing import Generic, List, Optional, Tuple, TypeVar, Union
 
 import pytest
 from experimaestro import field, Config, Param
@@ -398,3 +398,48 @@ class Container(Config):
 
     with pytest.raises((ValueError, TypeError)):
         Container.C(sampler=MyBatchSampler.C())
+
+
+# =============================================================================
+# Tests for Union type compatibility in generic type arguments
+# =============================================================================
+
+V = TypeVar("V")
+W = TypeVar("W")
+
+
+class Converter(Config, Generic[V, W]):
+    pass
+
+
+HFTokenizerInput = Union[str, List[str], List[Tuple[str, str]]]
+
+
+class TopicTextConverter(Converter[str, str]):
+    pass
+
+
+def test_core_generics_union_type_arg_accepts_member():
+    """Param[Base[str, Union[str, ...]]] should accept Base[str, str]
+    since str is a member of the Union"""
+
+    class HFTokenizerAdapter(Config):
+        converter: Param[Converter[str, HFTokenizerInput]]
+
+    converter = TopicTextConverter.C()
+    adapter = HFTokenizerAdapter.C(converter=converter)
+    assert adapter.converter is converter
+
+
+def test_core_generics_union_type_arg_rejects_non_member():
+    """Param[Base[str, Union[str, ...]]] should reject Base[str, int]
+    since int is not a member of the Union"""
+
+    class IntConverter(Converter[str, int]):
+        pass
+
+    class HFTokenizerAdapter(Config):
+        converter: Param[Converter[str, HFTokenizerInput]]
+
+    with pytest.raises(TypeError):
+        HFTokenizerAdapter.C(converter=IntConverter.C())