Skip to content

Commit 2281d4d

Browse files
authored
Python: add typing.Literal support to KernelJsonSchemaBuilder (#14514)
### Motivation and Context `KernelJsonSchemaBuilder` had no handling for `typing.Literal`. A parameter typed `Literal["fast", "slow"]` was advertised to the model as a bare `{"type": "object"}` with no `enum`, so the model was never told the allowed values. This also hit Pydantic fields, `Optional[Literal[...]]` and `list[Literal[...]]`. Fixes #14511 ### Description In `handle_complex_type`, a `Literal` now builds `{"type": ..., "enum": [...]}`, the same shape `build_enum_schema` returns for `Enum` classes: - `type` is the JSON type of the values when they all share one, otherwise a list of the types (with `"null"` last). `None` maps to `"null"`. - `Enum` members inside a `Literal` are converted to their `.value`. - `Optional[Literal[...]]` (and `Literal[...] | None`) now adds `"null"` to `type` and `None` to `enum`. The Optional branch also no longer nests a list inside `type` when the inner schema already has a list type. - `list[Literal[...]]` works through the existing `list` branch and puts the `enum` on `items`. Tests added in `tests/unit/schema/test_schema_builder.py` cover str, int, bool, mixed, Optional, `| None`, list, Enum members, descriptions, and a Pydantic model with Literal fields. The new tests fail on current main and pass now. `tests/unit/schema`, `tests/unit/functions`, `tests/unit/connectors/utils` and `test_function_choice_behavior.py`: all pass. `ruff` and `mypy` are clean on the changed files. The repro from the issue now gives `{"type": "string", "enum": ["fast", "slow"], "description": "speed mode"}` for `mode` and an `enum` on the nested `level` field. ### Contribution Checklist - [x] The code builds clean without any errors or warnings - [x] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [x] All unit tests pass, and I have added new tests where possible - [x] I didn't break anyone 😄
1 parent 2a3236d commit 2281d4d

2 files changed

Lines changed: 58 additions & 3 deletions

File tree

‎python/semantic_kernel/schema/kernel_json_schema_builder.py‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import sys
44
import types
55
from enum import Enum
6-
from typing import Any, Union, get_args, get_origin, get_type_hints
6+
from typing import Any, Literal, Union, get_args, get_origin, get_type_hints
77

88
from semantic_kernel.const import PARSED_ANNOTATION_UNION_DELIMITER
99
from semantic_kernel.exceptions.function_exceptions import FunctionInvalidParameterConfiguration
@@ -196,12 +196,23 @@ def handle_complex_type(
196196
if structured_output:
197197
schema["additionalProperties"] = False
198198
return schema
199+
if origin is Literal:
200+
values = [arg.value if isinstance(arg, Enum) else arg for arg in args]
201+
value_types = {"null" if v is None else TYPE_MAPPING.get(type(v), "string") for v in values}
202+
ordered_types = sorted(value_types, key=lambda t: (t == "null", t))
203+
schema = {"type": ordered_types[0] if len(ordered_types) == 1 else ordered_types, "enum": values}
204+
if description:
205+
schema["description"] = description
206+
return schema
199207
if origin in {Union, types.UnionType}:
200208
# Handle Optional[T] (Union[T, None]) by making schema nullable
201209
if len(args) == 2 and type(None) in args:
202210
non_none_type = args[0] if args[1] is type(None) else args[1]
203211
schema = cls.build(non_none_type, structured_output=structured_output)
204-
schema["type"] = [schema["type"], "null"]
212+
schema_types = schema["type"] if isinstance(schema["type"], list) else [schema["type"]]
213+
schema["type"] = schema_types if "null" in schema_types else [*schema_types, "null"]
214+
if "enum" in schema and None not in schema["enum"]:
215+
schema["enum"] = [*schema["enum"], None]
205216
if description:
206217
schema["description"] = description
207218
if structured_output:

‎python/tests/unit/schema/test_schema_builder.py‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
import json
44
from enum import Enum
5-
from typing import Annotated, Any, Optional, Union
5+
from typing import Annotated, Any, Literal, Optional, Union
66
from unittest.mock import Mock
77

88
import pytest
@@ -455,3 +455,47 @@ def test_build_schema_with_nonpydantic_structured_output():
455455
}
456456

457457
assert structured_output_schema == expected_schema
458+
459+
460+
class LiteralModel(KernelBaseModel):
461+
level: Literal["low", "high"]
462+
maybe: Literal["a", "b"] | None = None
463+
464+
465+
@pytest.mark.parametrize(
466+
("literal_type", "expected"),
467+
[
468+
(Literal["fast", "slow"], {"type": "string", "enum": ["fast", "slow"]}),
469+
(Literal[1, 2], {"type": "integer", "enum": [1, 2]}),
470+
(Literal[True], {"type": "boolean", "enum": [True]}),
471+
(Literal["a", 1], {"type": ["integer", "string"], "enum": ["a", 1]}),
472+
(Optional[Literal["fast", "slow"]], {"type": ["string", "null"], "enum": ["fast", "slow", None]}), # noqa: UP045
473+
(Literal["fast", "slow"] | None, {"type": ["string", "null"], "enum": ["fast", "slow", None]}),
474+
(Optional[Literal["a", None]], {"type": ["string", "null"], "enum": ["a", None]}), # noqa: UP045
475+
(list[Literal["a", "b"]], {"type": "array", "items": {"type": "string", "enum": ["a", "b"]}}),
476+
],
477+
)
478+
def test_build_literal(literal_type, expected):
479+
assert KernelJsonSchemaBuilder.build(literal_type) == expected
480+
481+
482+
def test_build_literal_with_description():
483+
schema = KernelJsonSchemaBuilder.build(Literal["fast", "slow"], "speed mode")
484+
assert schema == {"type": "string", "enum": ["fast", "slow"], "description": "speed mode"}
485+
486+
487+
def test_build_literal_enum_member():
488+
schema = KernelJsonSchemaBuilder.build(Literal[EnumTest.OPTION_A])
489+
assert schema == {"type": "string", "enum": ["OptionA"]}
490+
491+
492+
def test_build_model_with_literal_fields():
493+
schema = KernelJsonSchemaBuilder.build(LiteralModel)
494+
assert schema == {
495+
"type": "object",
496+
"properties": {
497+
"level": {"type": "string", "enum": ["low", "high"]},
498+
"maybe": {"type": ["string", "null"], "enum": ["a", "b", None]},
499+
},
500+
"required": ["level"],
501+
}

0 commit comments

Comments
 (0)