fix(dspy): render PEP 604 unions like typing.Union in get_annotation_name (#10575)

Author: kayzenline

dspy/adapters/utils.py

@@ -240,6 +240,10 @@ def parse_value(value, annotation):
 def get_annotation_name(annotation):
     origin = get_origin(annotation)
     args = get_args(annotation)
+    if origin is types.UnionType:
+        # Render PEP 604 unions (e.g. `str | None`) the same way as `typing.Union`/`Optional` on Python < 3.14,
+        # matching Python 3.14+ where `get_origin(str | None)` already returns `typing.Union`.
+        origin = Union
     if origin is None:
         if annotation is Reasoning:
             # Keep backward compatibility with the old behavior in `dspy.ChainOfThought`, where reasoning

tests/adapters/test_adapter_utils.py

@@ -5,7 +5,7 @@
 import pytest
 from pydantic import BaseModel
 
-from dspy.adapters.utils import parse_value
+from dspy.adapters.utils import get_annotation_name, parse_value
 
 
 class Profile(BaseModel):
@@ -115,3 +115,18 @@ def test_parse_value_json_repair():
     malformed = "not json or literal"
     with pytest.raises(Exception):
         parse_value(malformed, dict)
+
+
+@pytest.mark.parametrize(
+    "pep604_annotation,typing_annotation,expected",
+    [
+        (str | None, Optional[str], "Union[str, NoneType]"),  # noqa: UP045
+        (int | str, Union[int, str], "Union[int, str]"),
+        (int | str | None, Union[int, str, None], "Union[int, str, NoneType]"),
+        (list[str] | None, Optional[list[str]], "Union[list[str], NoneType]"),  # noqa: UP045
+        (dict[str, int | None], dict[str, Optional[int]], "dict[str, Union[int, NoneType]]"),  # noqa: UP045
+    ],
+)
+def test_get_annotation_name_pep604_union_matches_typing_union(pep604_annotation, typing_annotation, expected):
+    assert get_annotation_name(typing_annotation) == expected
+    assert get_annotation_name(pep604_annotation) == expected

tests/adapters/test_chat_adapter.py

@@ -3050,3 +3050,15 @@ class OptionalSyntaxSignature(dspy.Signature):
     with dspy.context(lm=DummyLM(responses), adapter=dspy.ChatAdapter()):
         with pytest.raises(AdapterParseError):
             dspy.Predict(OptionalSyntaxSignature)(question="anything")
+
+
+def test_chat_adapter_formats_pep604_union_like_typing_union():
+    class QA(dspy.Signature):
+        question: str = dspy.InputField()
+        answer: int | None = dspy.OutputField()
+
+    messages = dspy.ChatAdapter().format(QA, [], {"question": "How many?"})
+
+    assert "1. `answer` (Union[int, NoneType])" in messages[0]["content"]
+    assert "must be formatted as a valid Python Union[int, NoneType]" in messages[-1]["content"]
+    assert "UnionType" not in messages[0]["content"] + messages[-1]["content"]

tests/adapters/test_xml_adapter.py

@@ -1,4 +1,3 @@
-import sys
 from unittest import mock
 
 import pydantic
@@ -454,7 +453,7 @@ class QA(dspy.Signature):
     assert messages[0]["role"] == "system"
     assert messages[1]["role"] == "user"
 
-    union_type_repr = "Union[str, NoneType]" if sys.version_info >= (3, 14) else "UnionType[str, NoneType]"
+    union_type_repr = "Union[str, NoneType]"
 
     expected_system = (
         "Your input fields are:\n"