diff --git a/python/semantic_kernel/functions/kernel_function_decorator.py b/python/semantic_kernel/functions/kernel_function_decorator.py index 4fae4004e672..ce526d39a2f0 100644 --- a/python/semantic_kernel/functions/kernel_function_decorator.py +++ b/python/semantic_kernel/functions/kernel_function_decorator.py @@ -6,6 +6,8 @@ from inspect import Parameter, Signature, isasyncgenfunction, isclass, isgeneratorfunction, signature from typing import Annotated, Any, ForwardRef, Union, get_args, get_origin +from semantic_kernel.schema.kernel_json_schema_builder import KernelJsonSchemaBuilder + NoneType = type(None) logger = logging.getLogger(__name__) @@ -65,7 +67,7 @@ def decorator(func: Callable[..., object]) -> Callable[..., object]: logger.debug(f"Parsing decorator for function: {getattr(func, '__kernel_function_name__')}") func_sig = signature(func, eval_str=True) - annotations = _process_signature(func_sig) + annotations = _process_signature(func_sig, getattr(func, "__globals__", None)) logger.debug(f"{annotations=}") setattr(func, "__kernel_function_parameters__", annotations) @@ -114,8 +116,15 @@ def _get_underlying_type(annotation: Any) -> Any: return annotation -def _process_signature(func_sig: Signature) -> list[dict[str, Any]]: - """Process the signature of the function.""" +def _process_signature(func_sig: Signature, globalns: dict[str, Any] | None = None) -> list[dict[str, Any]]: + """Process the signature of the function. + + Args: + func_sig: The signature of the function. + globalns: The function's module globals, used to resolve forward references such as + ``list["Model"]`` in parameter annotations. ``signature(..., eval_str=True)`` evaluates an + annotation that is a string, but not a string nested inside a generic alias. + """ annotations = [] for arg in func_sig.parameters.values(): @@ -129,6 +138,8 @@ def _process_signature(func_sig: Signature) -> list[dict[str, Any]]: underlying_type = _get_underlying_type(annotation) else: underlying_type = annotation + if globalns is not None: + underlying_type = KernelJsonSchemaBuilder.resolve_forward_refs(underlying_type, globalns) parsed_annotation["type_object"] = underlying_type annotations.append(parsed_annotation) diff --git a/python/semantic_kernel/schema/kernel_json_schema_builder.py b/python/semantic_kernel/schema/kernel_json_schema_builder.py index 7bd41e3399b7..5a020576dab9 100644 --- a/python/semantic_kernel/schema/kernel_json_schema_builder.py +++ b/python/semantic_kernel/schema/kernel_json_schema_builder.py @@ -1,14 +1,23 @@ # Copyright (c) Microsoft. All rights reserved. +import logging import sys import types +from contextvars import ContextVar from enum import Enum -from typing import Any, ClassVar, Literal, Union, get_args, get_origin, get_type_hints +from functools import reduce +from operator import or_ +from typing import Annotated, Any, ClassVar, ForwardRef, Literal, Union, get_args, get_origin, get_type_hints from semantic_kernel.const import PARSED_ANNOTATION_UNION_DELIMITER from semantic_kernel.exceptions.function_exceptions import FunctionInvalidParameterConfiguration from semantic_kernel.kernel_pydantic import KernelBaseModel +logger = logging.getLogger(__name__) + +# The models whose schema is being built further up the call stack. +_models_in_progress: ContextVar[tuple[Any, ...]] = ContextVar("_models_in_progress", default=()) + TYPE_MAPPING = { int: "integer", str: "string", @@ -79,6 +88,11 @@ def build_model_schema( """ # TODO (moonbox3): add support for handling forward references, which is not currently tested # https://github.com/microsoft/semantic-kernel/issues/6464 + in_progress = _models_in_progress.get() + if any(model is seen for seen in in_progress): + # A resolved reference back to a model being built has no finite inline schema; use the placeholder. + return cls.build_from_type_name("object", description) + properties = {} required = [] @@ -91,6 +105,7 @@ def build_model_schema( # excludes them from model fields and serialized instances, # so they must not become (required) schema properties. continue + field_type = cls.resolve_forward_refs(field_type, model_module_globals) field_description = None if hasattr(model, "model_fields") and field_name in model.model_fields: field_info = model.model_fields[field_name] @@ -109,7 +124,11 @@ def build_model_schema( break if not cls._is_optional(field_type): required.append(field_name) - properties[field_name] = cls.build(field_type, field_description, structured_output) + token = _models_in_progress.set((*in_progress, model)) + try: + properties[field_name] = cls.build(field_type, field_description, structured_output) + finally: + _models_in_progress.reset(token) schema = {"type": "object", "properties": properties} if required: @@ -121,6 +140,126 @@ def build_model_schema( return schema + @classmethod + def resolve_forward_refs(cls, annotation: Any, globalns: dict[str, Any]) -> Any: + """Resolves forward references that annotation evaluation leaves behind. + + Kernel function parameters come from ``signature(func, eval_str=True)``, which evaluates an + annotation that *is* a string and nothing below it, on every Python version. ``list["Inner"]`` + keeps its string, and unwrapping ``Optional["Inner"]`` or ``Annotated["Inner", ...]`` leaves a bare + ``ForwardRef``. Unresolved, these fall through to the ``{"type": "object"}`` placeholder. + + Model fields come from ``get_type_hints``. On Python 3.10 it evaluates ``ForwardRef`` objects but + not a bare ``str`` in a PEP 585 alias's ``__args__``, because ``list.__class_getitem__`` stores + ``"Inner"`` verbatim. Python 3.11 made it wrap those strings itself (gh-85542), so on 3.11+ model + field hints arrive fully resolved and come back from here unchanged. + + Args: + annotation: The annotation to resolve. + globalns: The namespace of the module owning the annotation. + + Returns: + Any: The annotation, rebuilt with resolvable references replaced by their types. An alias + that cannot be rebuilt is returned unchanged and a warning is logged. + """ + if isinstance(annotation, (str, ForwardRef)): + return cls._resolve_forward_ref_arg(annotation, globalns) + origin = get_origin(annotation) + args = get_args(annotation) + if origin is None or not args: + return annotation + if origin is Literal: + # Literal members are values, not names; a Literal["Inner"] must stay a string. + return annotation + if origin is Annotated: + # Only the annotated type is a type; the metadata that follows it is left alone. + return Annotated[(cls._resolve_forward_ref_arg(args[0], globalns), *args[1:])] + + resolved_args = tuple(cls._resolve_forward_ref_arg(arg, globalns) for arg in args) + if resolved_args == args: + return annotation + + try: + return cls._rebuild_alias(origin, resolved_args) + except TypeError as ex: + # A failure here must not stop a function from being decorated, so keep the original alias and its + # placeholder schema, but say so: a reference that did resolve has just been thrown away. + logger.warning(f"Could not rebuild {annotation!r} with its forward references resolved: {ex}") + return annotation + + @staticmethod + def _rebuild_alias(origin: Any, args: tuple[Any, ...]) -> Any: + """Rebuilds a generic alias from its origin and resolved arguments. + + Args: + origin: The origin of the alias, as returned by ``get_origin``. + args: The resolved arguments of the alias. + + Returns: + Any: The rebuilt alias. + + Raises: + TypeError: If the origin cannot be parameterized with these arguments. + """ + if origin is types.UnionType: + # Before Python 3.14 this is the origin of PEP 604 unions only and it is not subscriptable. From 3.14 + # it is also typing.Union, and joining the arguments is still correct for both spellings. + return reduce(or_, args) + # Special forms such as ClassVar and Final accept a single type, not a one element tuple. + return origin[args[0] if len(args) == 1 else args] + + @classmethod + def _resolve_forward_ref_arg(cls, arg: Any, globalns: dict[str, Any]) -> Any: + """Resolves a single generic argument, recursing into nested generic aliases. + + Args: + arg: The generic argument to resolve. + globalns: The namespace to resolve the reference against. + + Returns: + Any: The resolved type, or the argument unchanged when it cannot be resolved. + """ + if isinstance(arg, str): + return cls._lookup_type(arg, globalns, default=arg) + if isinstance(arg, ForwardRef): + return cls._lookup_type(arg.__forward_arg__, globalns, default=arg) + if isinstance(arg, list): + # Callable keeps its parameter types in a nested list. + return [cls._resolve_forward_ref_arg(item, globalns) for item in arg] + return cls.resolve_forward_refs(arg, globalns) + + @staticmethod + def _lookup_type(name: str, globalns: dict[str, Any], default: Any) -> Any: + """Looks a name up in the namespace, substituting it only when it names a usable type. + + A forward reference that happens to share its name with a module, a function or a plain + value must not be rebuilt around that object: a module reaches ``build_model_schema`` and + fails on ``__module__``, and a function or value would produce a misleading schema. The same + goes for a class whose own type hints do not evaluate, for example hints on names imported only + under ``TYPE_CHECKING``: ``build_model_schema`` would raise at function registration. Keeping + the original reference lets the existing placeholder fallback apply instead. + + Args: + name: The referenced name. + globalns: The namespace to look it up in. + default: What to return when the name is missing or does not name a usable type. + + Returns: + Any: The class or typing construct the name refers to, or ``default``. + """ + value = globalns.get(name, default) + if get_origin(value) is not None: + return value + if not isinstance(value, type): + return default + try: + get_type_hints(value, globalns=vars(sys.modules[value.__module__]), localns={}) + except Exception as ex: + # Evaluating annotation strings can raise anything. + logger.warning(f"Keeping forward reference {name!r} unresolved, its type hints do not evaluate: {ex}") + return default + return value + @classmethod def _is_optional(cls, field_type: Any) -> bool: return get_origin(field_type) in {types.UnionType, Union} and type(None) in get_args(field_type) diff --git a/python/tests/unit/functions/test_kernel_function_decorators.py b/python/tests/unit/functions/test_kernel_function_decorators.py index 83f6cfbdd6d8..f6874d4f82aa 100644 --- a/python/tests/unit/functions/test_kernel_function_decorators.py +++ b/python/tests/unit/functions/test_kernel_function_decorators.py @@ -2,11 +2,12 @@ from collections.abc import AsyncGenerator, AsyncIterable from inspect import Parameter, Signature -from typing import TYPE_CHECKING, Annotated, Any, Union +from typing import TYPE_CHECKING, Annotated, Any, Optional, Union import pytest from semantic_kernel.functions.kernel_function_decorator import _process_signature, kernel_function +from semantic_kernel.functions.kernel_function_from_method import KernelFunctionFromMethod from semantic_kernel.kernel_pydantic import KernelBaseModel if TYPE_CHECKING: @@ -18,6 +19,14 @@ class InputObject(KernelBaseModel): arg2: int +class SelfReferencingInput(KernelBaseModel): + children: list["SelfReferencingInput"] = [] + + +class UnevaluableHintsInput: + value: "NotDefinedAnywhere" # noqa: F821 + + class MiscClass: __test__ = False @@ -38,6 +47,54 @@ def func_docstring_as_description(self, input): """Description.""" return input + @kernel_function + def func_forward_ref_list(self, items: list["InputObject"]): + return items + + @kernel_function + def func_forward_ref_colliding_with_module(self, items: list["pytest"]): + return items + + @kernel_function + def func_forward_ref_nested_nullable_list(self, items: list[list["InputObject"] | None]): + return items + + @kernel_function + def func_forward_ref_nullable_list(self, items: list["InputObject"] | None): + return items + + @kernel_function + def func_forward_ref_dict_nested_in_union(self, items: dict[str, list["InputObject"] | None]): + return items + + @kernel_function + def func_forward_ref_self_referencing(self, items: list["SelfReferencingInput"]): + return items + + @kernel_function + def func_forward_ref_optional(self, input: Optional["InputObject"] = None): + return input + + @kernel_function + def func_forward_ref_union_with_none(self, input: Union["InputObject", None] = None): + return input + + @kernel_function + def func_forward_ref_annotated(self, input: Annotated["InputObject", "description"]): + return input + + @kernel_function + def func_forward_ref_optional_self_referencing(self, input: Optional["SelfReferencingInput"] = None): + return input + + @kernel_function + def func_forward_ref_list_unevaluable_hints(self, input: list["UnevaluableHintsInput"]): + return input + + @kernel_function + def func_forward_ref_optional_unevaluable_hints(self, input: Optional["UnevaluableHintsInput"] = None): + return input + @kernel_function def func_input_annotated(self, input: Annotated[str, "input description"]): return input @@ -322,3 +379,145 @@ def test_annotation_parsing(name, annotation, description, type_, is_required): assert description == annotation_dict.get("description") assert type_ == annotation_dict["type_"] assert is_required == annotation_dict["is_required"] + + +def test_kernel_function_resolves_forward_ref_in_list_parameter(): + """list["InputObject"] on a kernel function parameter resolves to list[InputObject].""" + my_func = getattr(MiscClass(), "func_forward_ref_list") + param = my_func.__kernel_function_parameters__[0] + + assert param["name"] == "items" + assert param["type_"] == "list[InputObject]" + assert param["type_object"] == list[InputObject] + + +@pytest.mark.parametrize( + ("annotation", "expected_type_object", "expected_description"), + [ + (list["InputObject"], list[InputObject], None), + (dict[str, "InputObject"], dict[str, InputObject], None), + (Annotated[list["InputObject"], "description"], list[InputObject], "description"), + (list["InputObject"] | None, list[InputObject], None), + (list[list["InputObject"] | None], list[list[InputObject] | None], None), + (dict[str, list["InputObject"] | None], dict[str, list[InputObject] | None], None), + (Annotated[list[list["InputObject"] | None], "description"], list[list[InputObject] | None], "description"), + (Optional["InputObject"], InputObject, None), + (Union["InputObject", None], InputObject, None), + (Annotated["InputObject", "description"], InputObject, "description"), + ], +) +def test_process_signature_resolves_forward_refs_with_globalns(annotation, expected_type_object, expected_description): + param = Parameter( + name="items", + annotation=annotation, + default=Parameter.empty, + kind=Parameter.POSITIONAL_OR_KEYWORD, + ) + func_sig = Signature(parameters=[param]) + + annotations = _process_signature(func_sig, globals()) + + assert annotations[0]["type_object"] == expected_type_object + assert annotations[0].get("description") == expected_description + + +def test_process_signature_without_globalns_leaves_forward_refs_unchanged(): + """Callers that pass no namespace get the previous behaviour.""" + param = Parameter( + name="items", + annotation=list["InputObject"], + default=Parameter.empty, + kind=Parameter.POSITIONAL_OR_KEYWORD, + ) + func_sig = Signature(parameters=[param]) + + annotations = _process_signature(func_sig) + + assert annotations[0]["type_object"] == list["InputObject"] + + +def test_kernel_function_forward_ref_that_names_a_module_is_left_unresolved(): + """A reference colliding with a non type global must not be substituted or raise at decoration.""" + my_func = getattr(MiscClass(), "func_forward_ref_colliding_with_module") + param = my_func.__kernel_function_parameters__[0] + + assert param["type_"] == "list[pytest]" + assert param["type_object"] == list["pytest"] + + +def _parameter_schema(function_name): + my_func = getattr(MiscClass(), function_name) + return KernelFunctionFromMethod(method=my_func, plugin_name="test").metadata.parameters[0].schema_data + + +INPUT_OBJECT_PROPERTIES = {"arg1": {"type": "string"}, "arg2": {"type": "integer"}} + + +def test_kernel_function_schema_resolves_forward_ref_in_nested_nullable_list(): + schema = _parameter_schema("func_forward_ref_nested_nullable_list") + + assert schema["type"] == "array" + assert schema["items"]["type"] == ["array", "null"] + assert schema["items"]["items"]["properties"] == INPUT_OBJECT_PROPERTIES + + +def test_kernel_function_schema_resolves_forward_ref_in_nullable_list(): + schema = _parameter_schema("func_forward_ref_nullable_list") + + assert schema["items"]["properties"] == INPUT_OBJECT_PROPERTIES + + +def test_kernel_function_schema_resolves_forward_ref_in_dict_nested_in_union(): + schema = _parameter_schema("func_forward_ref_dict_nested_in_union") + + assert schema["additionalProperties"]["type"] == ["array", "null"] + assert schema["additionalProperties"]["items"]["properties"] == INPUT_OBJECT_PROPERTIES + + +def test_kernel_function_schema_stops_at_a_self_reference(): + """Resolving the reference must not turn the placeholder into a recursion error at registration.""" + schema = _parameter_schema("func_forward_ref_self_referencing") + + assert schema["items"]["properties"]["children"] == {"type": "array", "items": {"type": "object"}} + + +@pytest.mark.parametrize( + "function_name", + ["func_forward_ref_optional", "func_forward_ref_union_with_none", "func_forward_ref_annotated"], +) +def test_kernel_function_schema_resolves_bare_forward_ref(function_name): + """Unwrapping these annotations leaves a bare ForwardRef, which has no origin to walk.""" + schema = _parameter_schema(function_name) + + assert schema["properties"] == INPUT_OBJECT_PROPERTIES + assert schema["required"] == ["arg1", "arg2"] + + +@pytest.mark.parametrize( + "function_name", + ["func_forward_ref_optional", "func_forward_ref_union_with_none", "func_forward_ref_annotated"], +) +async def test_kernel_function_invocation_parses_bare_forward_ref(function_name, kernel): + function = KernelFunctionFromMethod(method=getattr(MiscClass(), function_name), plugin_name="test") + + result = await function.invoke(kernel, input={"arg1": "a", "arg2": 1}) + + assert result.value == InputObject(arg1="a", arg2=1) + + +def test_kernel_function_schema_stops_at_a_bare_self_reference(): + schema = _parameter_schema("func_forward_ref_optional_self_referencing") + + assert schema["properties"]["children"] == {"type": "array", "items": {"type": "object"}} + + +@pytest.mark.parametrize( + ("function_name", "expected_schema"), + [ + ("func_forward_ref_list_unevaluable_hints", {"type": "array", "items": {"type": "object"}}), + ("func_forward_ref_optional_unevaluable_hints", {"type": "object"}), + ], +) +def test_kernel_function_schema_keeps_placeholder_when_class_hints_do_not_evaluate(function_name, expected_schema): + """A class that cannot be built must not fail registration where the placeholder used to apply.""" + assert _parameter_schema(function_name) == expected_schema diff --git a/python/tests/unit/schema/test_schema_builder.py b/python/tests/unit/schema/test_schema_builder.py index 0238317cccf1..fd1f003e6794 100644 --- a/python/tests/unit/schema/test_schema_builder.py +++ b/python/tests/unit/schema/test_schema_builder.py @@ -1,8 +1,13 @@ # Copyright (c) Microsoft. All rights reserved. +import collections.abc import json +import logging +import sys +import types +import typing from enum import Enum -from typing import Annotated, Any, ClassVar, Literal, Optional, Union +from typing import Annotated, Any, ClassVar, Final, ForwardRef, Literal, Optional, Union, get_args from unittest.mock import Mock import pytest @@ -623,3 +628,370 @@ def test_build_model_with_literal_fields(): }, "required": ["level"], } + + +class ForwardRefTarget(KernelBaseModel): + value: int + label: str + + +class DirectListHolder(KernelBaseModel): + items: list[ForwardRefTarget] = [] + + +class ForwardRefListHolder(KernelBaseModel): + items: list["ForwardRefTarget"] = [] + + +class ForwardRefDictHolder(KernelBaseModel): + mapping: dict[str, "ForwardRefTarget"] = {} + + +class ForwardRefNestedHolder(KernelBaseModel): + items: list[list["ForwardRefTarget"]] = [] + + +class ForwardRefOptionalHolder(KernelBaseModel): + items: list[Optional["ForwardRefTarget"]] = [] + + +class UnresolvableForwardRefHolder(KernelBaseModel): + items: list["NotDefinedAnywhere"] = [] # noqa: F821 + + +def test_build_model_schema_resolves_forward_ref_in_list(): + """list["Target"] must produce the same schema as list[Target].""" + forward_ref = KernelJsonSchemaBuilder.build(ForwardRefListHolder)["properties"]["items"] + direct = KernelJsonSchemaBuilder.build(DirectListHolder)["properties"]["items"] + + assert forward_ref == direct + assert forward_ref["items"]["properties"] == {"value": {"type": "integer"}, "label": {"type": "string"}} + assert forward_ref["items"]["required"] == ["value", "label"] + + +def test_build_model_schema_resolves_forward_ref_in_dict(): + """dict[str, "Target"] must carry the element schema through additionalProperties.""" + schema = KernelJsonSchemaBuilder.build(ForwardRefDictHolder)["properties"]["mapping"] + + assert schema["additionalProperties"]["properties"] == { + "value": {"type": "integer"}, + "label": {"type": "string"}, + } + + +def test_build_model_schema_resolves_nested_forward_ref(): + """Resolution recurses into nested generic aliases.""" + schema = KernelJsonSchemaBuilder.build(ForwardRefNestedHolder)["properties"]["items"] + + assert schema["items"]["items"]["properties"] == { + "value": {"type": "integer"}, + "label": {"type": "string"}, + } + + +def test_build_model_schema_resolves_forward_ref_inside_optional(): + """A ForwardRef nested under Optional inside a list still resolves.""" + schema = KernelJsonSchemaBuilder.build(ForwardRefOptionalHolder)["properties"]["items"] + + assert schema["items"]["type"] == ["object", "null"] + assert schema["items"]["properties"] == {"value": {"type": "integer"}, "label": {"type": "string"}} + + +@pytest.mark.skipif( + sys.version_info >= (3, 11), + reason="On 3.11+ get_type_hints raises NameError for the unresolvable name before the builder sees it", +) +def test_build_model_schema_unresolvable_forward_ref_falls_back(): + """An unresolvable name keeps the previous placeholder rather than raising.""" + schema = KernelJsonSchemaBuilder.build(UnresolvableForwardRefHolder)["properties"]["items"] + + assert schema == {"type": "array", "items": {"type": "object"}} + + +def test_resolve_forward_refs_leaves_literal_values_and_annotated_metadata_alone(): + """Strings that are values, not names, must not be looked up even when a global matches.""" + namespace = {"ForwardRefTarget": ForwardRefTarget} + + literal = KernelJsonSchemaBuilder.resolve_forward_refs(list[Literal["ForwardRefTarget"]], namespace) + annotated = KernelJsonSchemaBuilder.resolve_forward_refs( + list[Annotated["ForwardRefTarget", "ForwardRefTarget"]], namespace + ) + + assert literal == list[Literal["ForwardRefTarget"]] + assert annotated == list[Annotated[ForwardRefTarget, "ForwardRefTarget"]] + + +def _not_a_type(): + return None + + +NOT_A_TYPE_VALUE = 3 + + +def test_resolve_forward_refs_ignores_names_that_do_not_refer_to_a_type(): + """A reference that collides with a module, function or value keeps the placeholder fallback.""" + namespace = { + "json": json, + "_not_a_type": _not_a_type, + "NOT_A_TYPE_VALUE": NOT_A_TYPE_VALUE, + "ForwardRefTarget": ForwardRefTarget, + } + + assert KernelJsonSchemaBuilder.resolve_forward_refs(list["json"], namespace) == list["json"] + assert KernelJsonSchemaBuilder.resolve_forward_refs(list["_not_a_type"], namespace) == list["_not_a_type"] + assert ( + KernelJsonSchemaBuilder.resolve_forward_refs(dict[str, "NOT_A_TYPE_VALUE"], namespace) + == (dict[str, "NOT_A_TYPE_VALUE"]) + ) + # a sibling argument that does name a type is still resolved + assert ( + KernelJsonSchemaBuilder.resolve_forward_refs(dict["json", "ForwardRefTarget"], namespace) + == (dict["json", ForwardRefTarget]) + ) + + +def test_resolve_forward_refs_rebuilds_pep604_union_nested_in_list(): + """A PEP 604 union has no subscriptable origin, so it needs its own rebuild.""" + + class Inner(KernelBaseModel): + name: str + + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(list[list["Inner"] | None], {"Inner": Inner}) + + assert resolved == list[list[Inner] | None] + assert isinstance(get_args(resolved)[0], types.UnionType) + + +@pytest.mark.parametrize( + ("annotation", "expected"), + [ + (list["ForwardRefTarget"] | None, list[ForwardRefTarget] | None), + (None | list["ForwardRefTarget"], None | list[ForwardRefTarget]), + (list[list["ForwardRefTarget"] | None], list[list[ForwardRefTarget] | None]), + (dict[str, "ForwardRefTarget"] | None, dict[str, ForwardRefTarget] | None), + (list[dict[str, "ForwardRefTarget"] | None], list[dict[str, ForwardRefTarget] | None]), + (dict[str, list["ForwardRefTarget"] | None], dict[str, list[ForwardRefTarget] | None]), + ( + list["ForwardRefTarget"] | dict[str, "ForwardRefTarget"] | None, + list[ForwardRefTarget] | dict[str, ForwardRefTarget] | None, + ), + (tuple["ForwardRefTarget", ...] | None, tuple[ForwardRefTarget, ...] | None), + ( + dict[str, list[dict[str, list["ForwardRefTarget"] | None] | None]], + dict[str, list[dict[str, list[ForwardRefTarget] | None] | None]], + ), + (Union[list["ForwardRefTarget"], None], Union[list[ForwardRefTarget], None]), + (list[Optional[list["ForwardRefTarget"]]], list[Optional[list[ForwardRefTarget]]]), + ( + Union["ForwardRefTarget", "NotDefinedAnywhere"], # noqa: F821 + Union[ForwardRefTarget, "NotDefinedAnywhere"], # noqa: F821 + ), + ( + list["NotDefinedAnywhere"] | list["ForwardRefTarget"], # noqa: F821 + list["NotDefinedAnywhere"] | list[ForwardRefTarget], # noqa: F821 + ), + ], +) +def test_resolve_forward_refs_rebuilds_unions(annotation, expected): + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(annotation, {"ForwardRefTarget": ForwardRefTarget}) + + assert resolved == expected + + +@pytest.mark.parametrize( + "annotation", + [list["NotDefinedAnywhere"] | None, list[list["NotDefinedAnywhere"] | None]], # noqa: F821 +) +def test_resolve_forward_refs_keeps_unresolvable_name_in_union(annotation, caplog): + with caplog.at_level(logging.WARNING): + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(annotation, {"ForwardRefTarget": ForwardRefTarget}) + + assert resolved is annotation + assert not caplog.records + + +def test_resolve_forward_refs_keeps_metadata_of_annotated_pep604_union(): + metadata = ("ForwardRefTarget", {"key": "value"}) + + resolved = KernelJsonSchemaBuilder.resolve_forward_refs( + Annotated[(list["ForwardRefTarget"] | None, *metadata)], {"ForwardRefTarget": ForwardRefTarget} + ) + + assert resolved == Annotated[(list[ForwardRefTarget] | None, *metadata)] + assert resolved.__metadata__ == metadata + + +def test_resolve_forward_refs_leaves_literal_value_in_union_alone(): + annotation = list[Literal["ForwardRefTarget"] | None] + + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(annotation, {"ForwardRefTarget": ForwardRefTarget}) + + assert resolved == annotation + + +@pytest.mark.parametrize("callable_alias", [collections.abc.Callable, typing.Callable]) +def test_resolve_forward_refs_resolves_callable_parameter_list(callable_alias): + """Callable keeps its parameter types in a nested list.""" + namespace = {"ForwardRefTarget": ForwardRefTarget} + + only_parameters = KernelJsonSchemaBuilder.resolve_forward_refs( + callable_alias[["ForwardRefTarget", int], str], namespace + ) + nested = KernelJsonSchemaBuilder.resolve_forward_refs( + list[callable_alias[[list["ForwardRefTarget"] | None], "ForwardRefTarget"]], namespace + ) + ellipsis_parameters = KernelJsonSchemaBuilder.resolve_forward_refs( + callable_alias[..., "ForwardRefTarget"], namespace + ) + + assert get_args(only_parameters) == ([ForwardRefTarget, int], str) + assert get_args(get_args(nested)[0]) == ([list[ForwardRefTarget] | None], ForwardRefTarget) + assert get_args(ellipsis_parameters) == (..., ForwardRefTarget) + + +@pytest.mark.parametrize("special_form", [ClassVar, Final]) +def test_resolve_forward_refs_rebuilds_single_type_special_forms(special_form): + """Special forms accept a single type and reject a one element tuple.""" + resolved = KernelJsonSchemaBuilder.resolve_forward_refs( + special_form["ForwardRefTarget"], {"ForwardRefTarget": ForwardRefTarget} + ) + + assert resolved == special_form[ForwardRefTarget] + + +def test_resolve_forward_refs_warns_when_an_alias_cannot_be_rebuilt(caplog): + annotation = types.GenericAlias(int, ("ForwardRefTarget",)) + + with caplog.at_level(logging.WARNING, logger="semantic_kernel.schema.kernel_json_schema_builder"): + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(annotation, {"ForwardRefTarget": ForwardRefTarget}) + + assert resolved is annotation + assert "Could not rebuild" in caplog.text + + +class ForwardRefNullableListHolder(KernelBaseModel): + items: list["ForwardRefTarget"] | None = None + + +class ForwardRefNestedNullableListHolder(KernelBaseModel): + items: list[list["ForwardRefTarget"] | None] = [] + + +class ForwardRefNullableDictInUnionHolder(KernelBaseModel): + mapping: dict[str, list["ForwardRefTarget"] | None] | None = None + + +def test_build_model_schema_resolves_forward_ref_in_nullable_list(): + schema = KernelJsonSchemaBuilder.build(ForwardRefNullableListHolder)["properties"]["items"] + + assert schema["type"] == ["array", "null"] + assert schema["items"]["properties"] == {"value": {"type": "integer"}, "label": {"type": "string"}} + + +def test_build_model_schema_resolves_forward_ref_in_nested_nullable_list(): + schema = KernelJsonSchemaBuilder.build(ForwardRefNestedNullableListHolder)["properties"]["items"] + + assert schema["items"]["type"] == ["array", "null"] + assert schema["items"]["items"]["properties"] == {"value": {"type": "integer"}, "label": {"type": "string"}} + + +def test_build_model_schema_resolves_forward_ref_in_dict_nested_in_union(): + schema = KernelJsonSchemaBuilder.build(ForwardRefNullableDictInUnionHolder)["properties"]["mapping"] + + assert schema["type"] == ["object", "null"] + assert schema["additionalProperties"]["type"] == ["array", "null"] + assert schema["additionalProperties"]["items"]["properties"] == { + "value": {"type": "integer"}, + "label": {"type": "string"}, + } + + +class SelfReferencingHolder(KernelBaseModel): + name: str + children: list["SelfReferencingHolder"] = [] + + +class MutualReferenceFirst(KernelBaseModel): + second: list["MutualReferenceSecond"] = [] + + +class MutualReferenceSecond(KernelBaseModel): + first: list["MutualReferenceFirst"] = [] + + +class RepeatedTargetHolder(KernelBaseModel): + first: list["ForwardRefTarget"] = [] + second: list["ForwardRefTarget"] = [] + + +def test_build_model_schema_stops_at_a_self_reference(): + """A resolved reference back to the model being built ends at the placeholder instead of recursing.""" + schema = KernelJsonSchemaBuilder.build(SelfReferencingHolder) + + assert schema["properties"]["name"] == {"type": "string"} + assert schema["properties"]["children"] == {"type": "array", "items": {"type": "object"}} + + +def test_build_model_schema_stops_at_a_mutual_reference(): + schema = KernelJsonSchemaBuilder.build(MutualReferenceFirst) + + assert schema["properties"]["second"]["items"]["properties"]["first"] == { + "type": "array", + "items": {"type": "object"}, + } + + +def test_build_model_schema_expands_a_repeated_model_every_time(): + """Only a model further up the call stack is cut short; a sibling field repeating a model is not.""" + properties = KernelJsonSchemaBuilder.build(RepeatedTargetHolder)["properties"] + + assert properties["first"] == properties["second"] + assert properties["second"]["items"]["properties"] == {"value": {"type": "integer"}, "label": {"type": "string"}} + + +@pytest.mark.parametrize("reference", ["ForwardRefTarget", ForwardRef("ForwardRefTarget")]) +def test_resolve_forward_refs_resolves_a_bare_reference(reference): + """Unwrapping Optional["Target"] or Annotated["Target", ...] on a kernel function leaves a bare ForwardRef.""" + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(reference, {"ForwardRefTarget": ForwardRefTarget}) + + assert resolved is ForwardRefTarget + + +@pytest.mark.parametrize( + ("reference", "namespace"), + [ + ("NotDefinedAnywhere", {}), + (ForwardRef("NotDefinedAnywhere"), {}), + (ForwardRef("json"), {"json": json}), + ], +) +def test_resolve_forward_refs_keeps_a_bare_reference_that_does_not_name_a_type(reference, namespace, caplog): + with caplog.at_level(logging.WARNING): + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(reference, namespace) + + assert resolved is reference + assert not caplog.records + + +class UnevaluableHintsTarget: + value: "NotDefinedAnywhere" # noqa: F821 + + +@pytest.mark.parametrize( + "annotation", + [ + list["UnevaluableHintsTarget"], + ForwardRef("UnevaluableHintsTarget"), + list["UnevaluableHintsTarget"] | None, + ], +) +def test_resolve_forward_refs_keeps_a_reference_to_a_class_whose_hints_do_not_evaluate(annotation, caplog): + """Building such a class raises, so the reference keeps the placeholder fallback and says why.""" + namespace = {"UnevaluableHintsTarget": UnevaluableHintsTarget} + + with caplog.at_level(logging.WARNING, logger="semantic_kernel.schema.kernel_json_schema_builder"): + resolved = KernelJsonSchemaBuilder.resolve_forward_refs(annotation, namespace) + + assert resolved is annotation + assert "UnevaluableHintsTarget" in caplog.text + assert "NotDefinedAnywhere" in caplog.text