Skip to content

Commit 4a3bebd

Browse files
committed
Python: rebuild PEP 604 unions when resolving nested forward references
types.UnionType is not subscriptable, so origin[args] raised and the caught TypeError restored the unresolved alias. list[list["Inner"] | None] kept its string and the item schema stayed a bare object. Join these unions with | as get_type_hints does. On Python 3.14 types.UnionType is typing.Union, and the same path handles both spellings there. The same rebuild dropped ClassVar and Final, which reject a one element tuple, and the walk skipped the nested parameter list of Callable. Handle both. A rebuild that still fails now logs a warning instead of passing silently. Optional["Inner"], Union["Inner", None] and Annotated["Inner", ...] on a kernel function unwrap to a bare ForwardRef, which has no origin and was returned as it was: the schema stayed a bare object and invoking the function failed. Resolve a bare reference too. Resolving references also means a model that refers back to itself recurses without end where main stops at a placeholder, for example a kernel function parameter typed list["Node"]. build_model_schema now returns that placeholder for a model already being built further up the call stack. A class whose own hints do not evaluate would raise at registration in the same way, so a reference to one stays unresolved with a warning and keeps the placeholder.
1 parent 9d5bf0d commit 4a3bebd

3 files changed

Lines changed: 462 additions & 22 deletions

File tree

‎python/semantic_kernel/schema/kernel_json_schema_builder.py‎

Lines changed: 76 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
11
# Copyright (c) Microsoft. All rights reserved.
22

3+
import logging
34
import sys
45
import types
6+
from contextvars import ContextVar
57
from enum import Enum
8+
from functools import reduce
9+
from operator import or_
610
from typing import Annotated, Any, ClassVar, ForwardRef, Literal, Union, get_args, get_origin, get_type_hints
711

812
from semantic_kernel.const import PARSED_ANNOTATION_UNION_DELIMITER
913
from semantic_kernel.exceptions.function_exceptions import FunctionInvalidParameterConfiguration
1014
from semantic_kernel.kernel_pydantic import KernelBaseModel
1115

16+
logger = logging.getLogger(__name__)
17+
18+
# The models whose schema is being built further up the call stack.
19+
_models_in_progress: ContextVar[tuple[Any, ...]] = ContextVar("_models_in_progress", default=())
20+
1221
TYPE_MAPPING = {
1322
int: "integer",
1423
str: "string",
@@ -79,6 +88,11 @@ def build_model_schema(
7988
"""
8089
# TODO (moonbox3): add support for handling forward references, which is not currently tested
8190
# https://github.com/microsoft/semantic-kernel/issues/6464
91+
in_progress = _models_in_progress.get()
92+
if any(model is seen for seen in in_progress):
93+
# A resolved reference back to a model being built has no finite inline schema; use the placeholder.
94+
return cls.build_from_type_name("object", description)
95+
8296
properties = {}
8397
required = []
8498

@@ -110,7 +124,11 @@ def build_model_schema(
110124
break
111125
if not cls._is_optional(field_type):
112126
required.append(field_name)
113-
properties[field_name] = cls.build(field_type, field_description, structured_output)
127+
token = _models_in_progress.set((*in_progress, model))
128+
try:
129+
properties[field_name] = cls.build(field_type, field_description, structured_output)
130+
finally:
131+
_models_in_progress.reset(token)
114132

115133
schema = {"type": "object", "properties": properties}
116134
if required:
@@ -124,26 +142,28 @@ def build_model_schema(
124142

125143
@classmethod
126144
def resolve_forward_refs(cls, annotation: Any, globalns: dict[str, Any]) -> Any:
127-
"""Resolves forward references sitting inside a generic alias.
145+
"""Resolves forward references that annotation evaluation leaves behind.
128146
129-
On Python 3.10, ``get_type_hints`` evaluates an annotation that *is* a string and
130-
``ForwardRef`` objects nested inside a generic alias, but not a bare ``str`` sitting in a
131-
PEP 585 alias's ``__args__``. ``list["Inner"]`` goes through ``list.__class_getitem__``,
132-
which stores ``"Inner"`` verbatim with no ``ForwardRef`` wrapper, so nothing resolves it and
133-
the element type falls through to the ``{"type": "object"}`` placeholder.
134-
``typing.Optional["Inner"]`` does wrap the string, which is why the top-level and
135-
``Optional`` forms already work.
147+
Kernel function parameters come from ``signature(func, eval_str=True)``, which evaluates an
148+
annotation that *is* a string and nothing below it, on every Python version. ``list["Inner"]``
149+
keeps its string, and unwrapping ``Optional["Inner"]`` or ``Annotated["Inner", ...]`` leaves a bare
150+
``ForwardRef``. Unresolved, these fall through to the ``{"type": "object"}`` placeholder.
136151
137-
Python 3.11 made ``get_type_hints`` wrap those strings itself (gh-85542), so on 3.11+ the
138-
hints arrive fully resolved and this is a no-op that returns the annotation unchanged.
152+
Model fields come from ``get_type_hints``. On Python 3.10 it evaluates ``ForwardRef`` objects but
153+
not a bare ``str`` in a PEP 585 alias's ``__args__``, because ``list.__class_getitem__`` stores
154+
``"Inner"`` verbatim. Python 3.11 made it wrap those strings itself (gh-85542), so on 3.11+ model
155+
field hints arrive fully resolved and come back from here unchanged.
139156
140157
Args:
141158
annotation: The annotation to resolve.
142159
globalns: The namespace of the module owning the annotation.
143160
144161
Returns:
145-
Any: The annotation, rebuilt with resolvable string arguments replaced by their types.
162+
Any: The annotation, rebuilt with resolvable references replaced by their types. An alias
163+
that cannot be rebuilt is returned unchanged and a warning is logged.
146164
"""
165+
if isinstance(annotation, (str, ForwardRef)):
166+
return cls._resolve_forward_ref_arg(annotation, globalns)
147167
origin = get_origin(annotation)
148168
args = get_args(annotation)
149169
if origin is None or not args:
@@ -160,11 +180,34 @@ def resolve_forward_refs(cls, annotation: Any, globalns: dict[str, Any]) -> Any:
160180
return annotation
161181

162182
try:
163-
return origin[resolved_args]
164-
except TypeError:
165-
# Not every alias can be rebuilt from its origin and args; keep the original.
183+
return cls._rebuild_alias(origin, resolved_args)
184+
except TypeError as ex:
185+
# A failure here must not stop a function from being decorated, so keep the original alias and its
186+
# placeholder schema, but say so: a reference that did resolve has just been thrown away.
187+
logger.warning(f"Could not rebuild {annotation!r} with its forward references resolved: {ex}")
166188
return annotation
167189

190+
@staticmethod
191+
def _rebuild_alias(origin: Any, args: tuple[Any, ...]) -> Any:
192+
"""Rebuilds a generic alias from its origin and resolved arguments.
193+
194+
Args:
195+
origin: The origin of the alias, as returned by ``get_origin``.
196+
args: The resolved arguments of the alias.
197+
198+
Returns:
199+
Any: The rebuilt alias.
200+
201+
Raises:
202+
TypeError: If the origin cannot be parameterized with these arguments.
203+
"""
204+
if origin is types.UnionType:
205+
# Before Python 3.14 this is the origin of PEP 604 unions only and it is not subscriptable. From 3.14
206+
# it is also typing.Union, and joining the arguments is still correct for both spellings.
207+
return reduce(or_, args)
208+
# Special forms such as ClassVar and Final accept a single type, not a one element tuple.
209+
return origin[args[0] if len(args) == 1 else args]
210+
168211
@classmethod
169212
def _resolve_forward_ref_arg(cls, arg: Any, globalns: dict[str, Any]) -> Any:
170213
"""Resolves a single generic argument, recursing into nested generic aliases.
@@ -180,29 +223,42 @@ def _resolve_forward_ref_arg(cls, arg: Any, globalns: dict[str, Any]) -> Any:
180223
return cls._lookup_type(arg, globalns, default=arg)
181224
if isinstance(arg, ForwardRef):
182225
return cls._lookup_type(arg.__forward_arg__, globalns, default=arg)
226+
if isinstance(arg, list):
227+
# Callable keeps its parameter types in a nested list.
228+
return [cls._resolve_forward_ref_arg(item, globalns) for item in arg]
183229
return cls.resolve_forward_refs(arg, globalns)
184230

185231
@staticmethod
186232
def _lookup_type(name: str, globalns: dict[str, Any], default: Any) -> Any:
187-
"""Looks a name up in the namespace, substituting it only when it names a type.
233+
"""Looks a name up in the namespace, substituting it only when it names a usable type.
188234
189235
A forward reference that happens to share its name with a module, a function or a plain
190236
value must not be rebuilt around that object: a module reaches ``build_model_schema`` and
191-
fails on ``__module__``, and a function or value would produce a misleading schema. Keeping
237+
fails on ``__module__``, and a function or value would produce a misleading schema. The same
238+
goes for a class whose own type hints do not evaluate, for example hints on names imported only
239+
under ``TYPE_CHECKING``: ``build_model_schema`` would raise at function registration. Keeping
192240
the original reference lets the existing placeholder fallback apply instead.
193241
194242
Args:
195243
name: The referenced name.
196244
globalns: The namespace to look it up in.
197-
default: What to return when the name is missing or does not name a type.
245+
default: What to return when the name is missing or does not name a usable type.
198246
199247
Returns:
200248
Any: The class or typing construct the name refers to, or ``default``.
201249
"""
202250
value = globalns.get(name, default)
203-
if isinstance(value, type) or get_origin(value) is not None:
251+
if get_origin(value) is not None:
204252
return value
205-
return default
253+
if not isinstance(value, type):
254+
return default
255+
try:
256+
get_type_hints(value, globalns=vars(sys.modules[value.__module__]), localns={})
257+
except Exception as ex:
258+
# Evaluating annotation strings can raise anything.
259+
logger.warning(f"Keeping forward reference {name!r} unresolved, its type hints do not evaluate: {ex}")
260+
return default
261+
return value
206262

207263
@classmethod
208264
def _is_optional(cls, field_type: Any) -> bool:

‎python/tests/unit/functions/test_kernel_function_decorators.py‎

Lines changed: 134 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22

33
from collections.abc import AsyncGenerator, AsyncIterable
44
from inspect import Parameter, Signature
5-
from typing import TYPE_CHECKING, Annotated, Any, Union
5+
from typing import TYPE_CHECKING, Annotated, Any, Optional, Union
66

77
import pytest
88

99
from semantic_kernel.functions.kernel_function_decorator import _process_signature, kernel_function
10+
from semantic_kernel.functions.kernel_function_from_method import KernelFunctionFromMethod
1011
from semantic_kernel.kernel_pydantic import KernelBaseModel
1112

1213
if TYPE_CHECKING:
@@ -18,6 +19,14 @@ class InputObject(KernelBaseModel):
1819
arg2: int
1920

2021

22+
class SelfReferencingInput(KernelBaseModel):
23+
children: list["SelfReferencingInput"] = []
24+
25+
26+
class UnevaluableHintsInput:
27+
value: "NotDefinedAnywhere" # noqa: F821
28+
29+
2130
class MiscClass:
2231
__test__ = False
2332

@@ -46,6 +55,46 @@ def func_forward_ref_list(self, items: list["InputObject"]):
4655
def func_forward_ref_colliding_with_module(self, items: list["pytest"]):
4756
return items
4857

58+
@kernel_function
59+
def func_forward_ref_nested_nullable_list(self, items: list[list["InputObject"] | None]):
60+
return items
61+
62+
@kernel_function
63+
def func_forward_ref_nullable_list(self, items: list["InputObject"] | None):
64+
return items
65+
66+
@kernel_function
67+
def func_forward_ref_dict_nested_in_union(self, items: dict[str, list["InputObject"] | None]):
68+
return items
69+
70+
@kernel_function
71+
def func_forward_ref_self_referencing(self, items: list["SelfReferencingInput"]):
72+
return items
73+
74+
@kernel_function
75+
def func_forward_ref_optional(self, input: Optional["InputObject"] = None):
76+
return input
77+
78+
@kernel_function
79+
def func_forward_ref_union_with_none(self, input: Union["InputObject", None] = None):
80+
return input
81+
82+
@kernel_function
83+
def func_forward_ref_annotated(self, input: Annotated["InputObject", "description"]):
84+
return input
85+
86+
@kernel_function
87+
def func_forward_ref_optional_self_referencing(self, input: Optional["SelfReferencingInput"] = None):
88+
return input
89+
90+
@kernel_function
91+
def func_forward_ref_list_unevaluable_hints(self, input: list["UnevaluableHintsInput"]):
92+
return input
93+
94+
@kernel_function
95+
def func_forward_ref_optional_unevaluable_hints(self, input: Optional["UnevaluableHintsInput"] = None):
96+
return input
97+
4998
@kernel_function
5099
def func_input_annotated(self, input: Annotated[str, "input description"]):
51100
return input
@@ -349,6 +398,12 @@ def test_kernel_function_resolves_forward_ref_in_list_parameter():
349398
(dict[str, "InputObject"], dict[str, InputObject], None),
350399
(Annotated[list["InputObject"], "description"], list[InputObject], "description"),
351400
(list["InputObject"] | None, list[InputObject], None),
401+
(list[list["InputObject"] | None], list[list[InputObject] | None], None),
402+
(dict[str, list["InputObject"] | None], dict[str, list[InputObject] | None], None),
403+
(Annotated[list[list["InputObject"] | None], "description"], list[list[InputObject] | None], "description"),
404+
(Optional["InputObject"], InputObject, None),
405+
(Union["InputObject", None], InputObject, None),
406+
(Annotated["InputObject", "description"], InputObject, "description"),
352407
],
353408
)
354409
def test_process_signature_resolves_forward_refs_with_globalns(annotation, expected_type_object, expected_description):
@@ -388,3 +443,81 @@ def test_kernel_function_forward_ref_that_names_a_module_is_left_unresolved():
388443

389444
assert param["type_"] == "list[pytest]"
390445
assert param["type_object"] == list["pytest"]
446+
447+
448+
def _parameter_schema(function_name):
449+
my_func = getattr(MiscClass(), function_name)
450+
return KernelFunctionFromMethod(method=my_func, plugin_name="test").metadata.parameters[0].schema_data
451+
452+
453+
INPUT_OBJECT_PROPERTIES = {"arg1": {"type": "string"}, "arg2": {"type": "integer"}}
454+
455+
456+
def test_kernel_function_schema_resolves_forward_ref_in_nested_nullable_list():
457+
schema = _parameter_schema("func_forward_ref_nested_nullable_list")
458+
459+
assert schema["type"] == "array"
460+
assert schema["items"]["type"] == ["array", "null"]
461+
assert schema["items"]["items"]["properties"] == INPUT_OBJECT_PROPERTIES
462+
463+
464+
def test_kernel_function_schema_resolves_forward_ref_in_nullable_list():
465+
schema = _parameter_schema("func_forward_ref_nullable_list")
466+
467+
assert schema["items"]["properties"] == INPUT_OBJECT_PROPERTIES
468+
469+
470+
def test_kernel_function_schema_resolves_forward_ref_in_dict_nested_in_union():
471+
schema = _parameter_schema("func_forward_ref_dict_nested_in_union")
472+
473+
assert schema["additionalProperties"]["type"] == ["array", "null"]
474+
assert schema["additionalProperties"]["items"]["properties"] == INPUT_OBJECT_PROPERTIES
475+
476+
477+
def test_kernel_function_schema_stops_at_a_self_reference():
478+
"""Resolving the reference must not turn the placeholder into a recursion error at registration."""
479+
schema = _parameter_schema("func_forward_ref_self_referencing")
480+
481+
assert schema["items"]["properties"]["children"] == {"type": "array", "items": {"type": "object"}}
482+
483+
484+
@pytest.mark.parametrize(
485+
"function_name",
486+
["func_forward_ref_optional", "func_forward_ref_union_with_none", "func_forward_ref_annotated"],
487+
)
488+
def test_kernel_function_schema_resolves_bare_forward_ref(function_name):
489+
"""Unwrapping these annotations leaves a bare ForwardRef, which has no origin to walk."""
490+
schema = _parameter_schema(function_name)
491+
492+
assert schema["properties"] == INPUT_OBJECT_PROPERTIES
493+
assert schema["required"] == ["arg1", "arg2"]
494+
495+
496+
@pytest.mark.parametrize(
497+
"function_name",
498+
["func_forward_ref_optional", "func_forward_ref_union_with_none", "func_forward_ref_annotated"],
499+
)
500+
async def test_kernel_function_invocation_parses_bare_forward_ref(function_name, kernel):
501+
function = KernelFunctionFromMethod(method=getattr(MiscClass(), function_name), plugin_name="test")
502+
503+
result = await function.invoke(kernel, input={"arg1": "a", "arg2": 1})
504+
505+
assert result.value == InputObject(arg1="a", arg2=1)
506+
507+
508+
def test_kernel_function_schema_stops_at_a_bare_self_reference():
509+
schema = _parameter_schema("func_forward_ref_optional_self_referencing")
510+
511+
assert schema["properties"]["children"] == {"type": "array", "items": {"type": "object"}}
512+
513+
514+
@pytest.mark.parametrize(
515+
("function_name", "expected_schema"),
516+
[
517+
("func_forward_ref_list_unevaluable_hints", {"type": "array", "items": {"type": "object"}}),
518+
("func_forward_ref_optional_unevaluable_hints", {"type": "object"}),
519+
],
520+
)
521+
def test_kernel_function_schema_keeps_placeholder_when_class_hints_do_not_evaluate(function_name, expected_schema):
522+
"""A class that cannot be built must not fail registration where the placeholder used to apply."""
523+
assert _parameter_schema(function_name) == expected_schema

0 commit comments

Comments
 (0)