diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index 7ea242078a2..6fb7638b77b 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -30,12 +30,25 @@ from collections import deque from collections.abc import AsyncIterable, Awaitable, Callable, Generator, Iterable, Mapping, Sequence from contextvars import ContextVar, Token -from dataclasses import dataclass +from dataclasses import dataclass, is_dataclass from functools import partial from pathlib import Path -from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeAlias, TypeVar, cast +from types import UnionType +from typing import ( + TYPE_CHECKING, + Any, + ClassVar, + Literal, + TypeAlias, + TypeVar, + Union, + cast, + get_args, + get_origin, +) import msgspec +import typing_extensions from typing_extensions import TypedDict from ._feature_stage import ExperimentalFeature, experimental @@ -257,6 +270,253 @@ def encode_pydantic(value: Any) -> Mapping[str, Any]: ) +_RESTORE_LEAF: Any = object() +_LocationTree: TypeAlias = dict[Any, Any] + + +def _field_alias_names(field: Any) -> list[str]: + """Return every serialized key one pydantic field may legitimately appear under.""" + names: list[str] = [] + validation_alias = getattr(field, "validation_alias", None) + if isinstance(validation_alias, str): + names.append(validation_alias) + else: + names.extend(choice for choice in getattr(validation_alias, "choices", ()) if isinstance(choice, str)) + for alias in (getattr(field, "alias", None), getattr(field, "serialization_alias", None)): + if isinstance(alias, str) and alias not in names: + names.append(alias) + return names + + +def _model_fields(value_cls: Any) -> Mapping[str, Any]: + fields = cast("Mapping[str, Any] | None", getattr(value_cls, "model_fields", None)) + return fields if isinstance(fields, Mapping) else {} + + +def _union_branch_label(annotation: Any) -> str: + """Format a type the way pydantic labels its synthetic union branches.""" + annotation_origin = getattr(annotation, "__origin__", None) + if getattr(annotation, "__metadata__", None) is not None and annotation_origin is not None: + return _union_branch_label(annotation_origin) + origin = get_origin(annotation) + if origin in (Union, UnionType): + return f"Union[{','.join(_union_branch_label(arg) for arg in get_args(annotation))}]" + if origin is not None: + origin_name = getattr(origin, "__name__", str(origin).removeprefix("typing.")) + args = ",".join(_union_branch_label(arg) for arg in get_args(annotation)) + return f"{origin_name}[{args}]" + if annotation is Ellipsis: + return "..." + if isinstance(annotation, str): + return repr(annotation) + return getattr(annotation, "__name__", str(annotation)) + + +def _descend_classes(annotation: Any) -> tuple[Any | None, Any | None]: + """Return the model class and annotation for the current location. + + A nullable union with one non-None alternative unwraps to that alternative. + Other union annotations stay intact until a synthetic branch label identifies + the branch. Containers keep their complete annotation until a key or index + consumes that level, including when a list's element is itself a tuple. + """ + annotation_origin = getattr(annotation, "__origin__", None) + if getattr(annotation, "__metadata__", None) is not None and annotation_origin is not None: + return _descend_classes(annotation_origin) + origin = get_origin(annotation) + if origin is Union or origin is UnionType: + non_none_args = tuple(arg for arg in get_args(annotation) if arg is not type(None)) + if len(non_none_args) == 1: + return _descend_classes(non_none_args[0]) + return annotation, annotation + if origin is not None: + return None, annotation + if annotation is Any or annotation in (str, bytes) or not isinstance(annotation, type): + return None, None + return annotation, annotation + + +def _list_item_annotation(annotation: Any, index: int) -> Any: + """Select the annotation consumed by one sequence index.""" + origin = get_origin(annotation) + args = get_args(annotation) + if origin is not tuple: + return args[0] if origin is not None and args else annotation + if len(args) == 2 and args[1] is Ellipsis: + return args[0] + return args[index] if index < len(args) else None + + +def _location_tree(errors: Sequence[Mapping[str, Any]]) -> _LocationTree | None: + """Collapse validation-error locations into a tree of segments to restore. + + A deeper location supersedes a shallower one on the same path. When pydantic + blames both ``child`` and ``child.message``, only ``child.message`` is + repaired, because restoring ``child`` would again sweep up its siblings. + """ + tree: _LocationTree = {} + found = False + for error in errors: + location = cast("Sequence[Any] | None", error.get("loc")) + if location is None or not location: + continue + node: _LocationTree = tree + for segment in location[:-1]: + child = node.get(segment) + subtree: _LocationTree = cast("_LocationTree", child) if isinstance(child, dict) else {} + node[segment] = subtree + node = subtree + last = location[-1] + if not isinstance(node.get(last), dict): + node[last] = _RESTORE_LEAF + found = True + return tree if found else None + + +def _restore_union(value: Any, tree: Mapping[Any, Any], annotation: Any, path: str) -> tuple[Any, bool]: + """Repair one union branch at a time, always starting from the original value.""" + from pydantic import BaseModel, ConfigDict, TypeAdapter + + for segment, sub in tree.items(): + matching_branches = tuple(arg for arg in get_args(annotation) if _union_branch_label(arg) == segment) + # Pydantic also uses is-instance labels and discriminator values. When + # the label is not a type name, branch validation identifies the candidate + # without guessing the schema-specific label format. Duplicate class names + # are not unique labels, so every matching branch gets an independent try. + candidates = matching_branches or get_args(annotation) + for candidate in candidates: + restored = value + try: + restored, changed = _restore_at_loc_tree( + value, + sub, + classes=_descend_classes(candidate), + path=f"{path}.{segment}", + ) + if not changed: + continue + config_candidate: Any = candidate + annotation_origin = getattr(config_candidate, "__origin__", None) + if getattr(config_candidate, "__metadata__", None) is not None and annotation_origin is not None: + config_candidate = annotation_origin + owns_validation_config = False + if isinstance(config_candidate, type): + candidate_type = cast(Any, config_candidate) + owns_validation_config = ( + issubclass(candidate_type, BaseModel) + or is_dataclass(candidate_type) + or typing_extensions.is_typeddict(candidate_type) + ) + config = None if owns_validation_config else ConfigDict(arbitrary_types_allowed=True) + TypeAdapter(candidate, config=config).validate_python(restored) + except ValueError: + # Registered codecs are application extension points. A failed + # candidate must not prevent a later branch from succeeding. + changed = False + if changed: + return restored, True + return value, False + + +def _restore_at_loc_tree( + value: Any, tree: Any, *, classes: tuple[Any | None, Any | None], path: str +) -> tuple[Any, bool]: + keyed_cls, item_annotation = classes + if tree is _RESTORE_LEAF: + return _deserialize_value(value, path=path), True + subtree = cast("_LocationTree | None", tree) + if subtree is None or not subtree: + return value, False + if get_origin(keyed_cls) in (Union, UnionType): + return _restore_union(value, subtree, keyed_cls, path) + if isinstance(value, Mapping): + mapping = cast("Mapping[str, Any]", value) + if ( + keyed_cls is not None + and _STATE_CLASS_REGISTRY.get(keyed_cls) is not None + and _STATE_TYPE_REGISTRY.get(str(mapping.get("type", ""))) is not None + ): + # The location reaches inside a payload owned by a registered codec. + # Only that codec knows the shape, so restore the value as a whole. + return _deserialize_value(mapping, path=path), True + return _restore_mapping(mapping, subtree, keyed_cls=keyed_cls, item_annotation=item_annotation, path=path) + if isinstance(value, list): + return _restore_list(cast("list[Any]", value), subtree, item_annotation=item_annotation, path=path) + return value, False + + +def _restore_mapping( + value: Mapping[str, Any], + tree: Mapping[Any, Any], + *, + keyed_cls: Any, + item_annotation: Any, + path: str, +) -> tuple[Any, bool]: + fields = _model_fields(keyed_cls) + args = get_args(item_annotation) + value_annotation = args[1] if get_origin(item_annotation) in (dict, Mapping) and len(args) == 2 else item_annotation + out = dict(value) + changed = False + for segment, sub in tree.items(): + field_name, field = next( + ( + (name, candidate) + for name, candidate in fields.items() + if name == segment or segment in _field_alias_names(candidate) + ), + (None, None), + ) + candidates = [segment] + if field_name is not None: + candidates.append(field_name) + candidates.extend(_field_alias_names(field)) + raw_key = next((key for key in candidates if key in value), None) + if raw_key is None: + continue + restored, key_changed = _restore_at_loc_tree( + out[raw_key], + sub, + classes=_descend_classes(getattr(field, "annotation", None) if field is not None else value_annotation), + path=f"{path}.{raw_key}", + ) + if key_changed: + out[raw_key] = restored + changed = True + return (out, True) if changed else (value, False) + + +def _restore_list( + value: Sequence[Any], tree: Mapping[Any, Any], *, item_annotation: Any, path: str +) -> tuple[Any, bool]: + out = list(value) + changed = False + for segment, sub in tree.items(): + if not isinstance(segment, int) or not 0 <= segment < len(out): + continue + restored, item_changed = _restore_at_loc_tree( + out[segment], + sub, + classes=_descend_classes(_list_item_annotation(item_annotation, segment)), + path=f"{path}[{segment}]", + ) + if item_changed: + out[segment] = restored + changed = True + return (out, True) if changed else (value, False) + + +def _restore_failed_values( + cls: type[Any], raw: Mapping[str, Any], errors: Sequence[Mapping[str, Any]], *, path: str +) -> Mapping[str, Any] | None: + """Repair only the values pydantic blamed, or ``None`` when none can be located.""" + tree = _location_tree(errors) + if tree is None: + return None + restored, changed = _restore_at_loc_tree(raw, tree, classes=(cls, cls), path=path) + return cast(Mapping[str, Any], restored) if changed else None + + def _default_state_decoder(cls: type[Any]) -> StateDecoder: """Create the default decoder for one explicitly registered state type.""" if callable(getattr(cls, "from_dict", None)): @@ -266,12 +526,28 @@ def decode_from_dict(payload: Mapping[str, Any]) -> Any: return decode_from_dict - from pydantic import BaseModel + from pydantic import BaseModel, ValidationError if issubclass(cls, BaseModel): def decode_pydantic(payload: Mapping[str, Any]) -> Any: - return cls.model_validate({key: value for key, value in payload.items() if key != "type"}) + raw = {key: value for key, value in payload.items() if key != "type"} + try: + return cls.model_validate(raw) + except ValidationError as exc: + # The encoder's payload items went through _serialize_value, + # so a nested registered value (e.g. Message) sits in the + # payload as its tagged dict. Restore only the values pydantic + # actually blames: the complete error location is walked, so a + # failure deep inside a nested model or a container repairs that + # one value and leaves every sibling untouched. A sibling that + # legitimately holds a tag-shaped dict (e.g. plain + # dict[str, Any] data) therefore keeps its payload instead of + # being converted or rejected by the retry. + restored = _restore_failed_values(cls, raw, exc.errors(), path=cls.__name__) + if restored is None: + raise + return cls.model_validate(restored) return decode_pydantic diff --git a/python/packages/core/tests/core/test_sessions.py b/python/packages/core/tests/core/test_sessions.py index ce757f66158..83aa73ec880 100644 --- a/python/packages/core/tests/core/test_sessions.py +++ b/python/packages/core/tests/core/test_sessions.py @@ -910,6 +910,178 @@ class PydanticState(BaseModel): assert isinstance(restored.state["value"], PydanticState) assert restored.state["value"].value == "ok" + def test_registered_pydantic_state_restores_nested_registered_values(self) -> None: + from pydantic import BaseModel, ConfigDict + + class PydanticMessageState(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + + register_state_type(PydanticMessageState, type_id="pydantic_message_state_test") + session = AgentSession(session_id="nested-message") + session.state["value"] = PydanticMessageState(message=Message(role="user", contents=["persisted"])) + + restored = AgentSession.from_dict(session.to_dict()) + + assert isinstance(restored.state["value"], PydanticMessageState) + assert isinstance(restored.state["value"].message, Message) + assert restored.state["value"].message.text == "persisted" + + def test_registered_pydantic_state_keeps_tag_shaped_dict_fields_raw(self) -> None: + from pydantic import BaseModel + + class PydanticDictState(BaseModel): + data: dict[str, Any] + + register_state_type(PydanticDictState, type_id="pydantic_dict_state_test") + session = AgentSession(session_id="dict-tag-shaped") + # Ordinary dict data whose "type" happens to name a registered state + # type is data, not an encoded nested value. + session.state["value"] = PydanticDictState(data={"type": "message", "note": "plain data"}) + + restored = AgentSession.from_dict(session.to_dict()) + + assert isinstance(restored.state["value"], PydanticDictState) + assert restored.state["value"].data == {"type": "message", "note": "plain data"} + + def test_registered_pydantic_state_restores_only_failed_fields(self) -> None: + """A mixed model restores the broken nested field and keeps valid tag-shaped data raw.""" + from pydantic import BaseModel, ConfigDict + + class PydanticMixedState(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: dict[str, Any] + + register_state_type(PydanticMixedState, type_id="pydantic_mixed_state_test") + session = AgentSession(session_id="mixed-restore") + # `message` fails raw validation (its payload is the tagged dict), while + # `data` validates raw; the retry must restore only `message`. + session.state["value"] = PydanticMixedState( + message=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + + restored = AgentSession.from_dict(session.to_dict()) + + assert isinstance(restored.state["value"], PydanticMixedState) + assert isinstance(restored.state["value"].message, Message) + assert restored.state["value"].message.text == "persisted" + assert restored.state["value"].data == {"type": "message", "note": "plain data"} + + def test_registered_pydantic_state_restores_only_the_failing_nested_value(self) -> None: + """A nested failure restores that nested value only, not its tag-shaped sibling.""" + from pydantic import BaseModel, ConfigDict + + class NestedMixed(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: dict[str, Any] + + class WithNestedMixed(BaseModel): + child: NestedMixed + + register_state_type(WithNestedMixed, type_id="pydantic_nested_mixed_state_test") + session = AgentSession(session_id="nested-mixed-restore") + # Pydantic blames `child.message` only. Restoring the whole `child` + # would also run the codec over `child.data`, whose `type` merely + # happens to name a registered type, and either convert it or fail. + session.state["value"] = WithNestedMixed( + child=NestedMixed( + message=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + ) + + restored = AgentSession.from_dict(session.to_dict()) + + assert isinstance(restored.state["value"], WithNestedMixed) + assert isinstance(restored.state["value"].child.message, Message) + assert restored.state["value"].child.message.text == "persisted" + assert restored.state["value"].child.data == {"type": "message", "note": "plain data"} + + def test_registered_pydantic_state_restores_nested_value_behind_alias_and_index(self) -> None: + """The failing value is found through a container index and a serialized alias.""" + from pydantic import BaseModel, ConfigDict, Field + + class AliasedItem(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class AliasedWrapper(BaseModel): + model_config = ConfigDict(serialize_by_alias=True, loc_by_alias=False) + + items: list[AliasedItem] + + register_state_type(AliasedWrapper, type_id="pydantic_aliased_wrapper_state_test") + session = AgentSession(session_id="aliased-wrapper-restore") + # The error loc reports the field name `last_message` while the payload + # holds the alias `lastMessage`, two levels down past a list index. + session.state["value"] = AliasedWrapper( + items=[ + AliasedItem( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + ] + ) + + restored = AgentSession.from_dict(session.to_dict()) + + assert isinstance(restored.state["value"], AliasedWrapper) + item = restored.state["value"].items[0] + assert isinstance(item.last_message, Message) + assert item.last_message.text == "persisted" + assert item.data == {"type": "message", "note": "plain data"} + + def test_registered_pydantic_state_restores_value_inside_a_keyed_container(self) -> None: + """A keyed container resolves aliases on its value type, not against the key.""" + from pydantic import BaseModel, ConfigDict, Field + + class KeyedItem(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class KeyedWrapper(BaseModel): + model_config = ConfigDict(serialize_by_alias=True, loc_by_alias=False) + + by_key: dict[str, KeyedItem] + + register_state_type(KeyedWrapper, type_id="pydantic_keyed_wrapper_state_test") + session = AgentSession(session_id="keyed-wrapper-restore") + # The key is application data; the class governing the value is what + # resolves `last_message` onto the serialized `lastMessage`. + session.state["value"] = KeyedWrapper( + by_key={ + "first": KeyedItem( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + } + ) + + restored = AgentSession.from_dict(session.to_dict()) + + item = restored.state["value"].by_key["first"] + assert isinstance(item.last_message, Message) + assert item.last_message.text == "persisted" + assert item.data == {"type": "message", "note": "plain data"} + def test_conflicting_type_identifier_is_rejected(self) -> None: class FirstState: def to_dict(self) -> dict[str, Any]: @@ -1155,6 +1327,796 @@ async def test_round_trips_session_across_store_instances(self, tmp_path: Path) assert files[0].suffix == ".json" assert json.loads(files[0].read_bytes())["version"] == "1.0" + async def test_round_trips_registered_pydantic_state_with_nested_message(self, tmp_path: Path) -> None: + from pydantic import BaseModel, ConfigDict + + class PydanticFileMessageState(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + + register_state_type(PydanticFileMessageState, type_id="pydantic_file_message_state_test") + session = AgentSession(session_id="file-nested-message") + session.state["value"] = PydanticFileMessageState(message=Message(role="user", contents=["persisted"])) + + await FileSessionStore(tmp_path).set("tenant_file-nested-message", session) + restored = await FileSessionStore(tmp_path).get("tenant_file-nested-message") + + assert restored is not None + assert isinstance(restored.state["value"], PydanticFileMessageState) + assert isinstance(restored.state["value"].message, Message) + assert restored.state["value"].message.text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_registered_pydantic_state_with_aliased_nested_message( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class PydanticAliasedMessageState(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + + register_state_type( + PydanticAliasedMessageState, + type_id=f"pydantic_aliased_message_state_{serialization_format}_test", + ) + session = AgentSession(session_id=f"aliased-{serialization_format}") + session.state["value"] = PydanticAliasedMessageState(lastMessage=Message(role="user", contents=["persisted"])) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_aliased-message", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_aliased-message" + ) + + assert restored is not None + assert isinstance(restored.state["value"], PydanticAliasedMessageState) + assert isinstance(restored.state["value"].last_message, Message) + assert restored.state["value"].last_message.text == "persisted" + files = await asyncio.to_thread(lambda: list(tmp_path.iterdir())) + assert len(files) == 1 + serialized = await asyncio.to_thread(files[0].read_bytes) + assert b"lastMessage" in serialized + assert b"last_message" not in serialized + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_nested_message_behind_union_branch_label( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + class Item(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: dict[str, Any] + + class Other(BaseModel): + other: str + + class UnionWrapper(BaseModel): + child: Item | Other + + register_state_type(UnionWrapper, type_id=f"pydantic_union_branch_{serialization_format}_test") + session = AgentSession(session_id=f"union-branch-{serialization_format}") + session.state["value"] = UnionWrapper( + child=Item( + message=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set("tenant_union-branch", session) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_union-branch" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + assert child.data == {"type": "message", "note": "plain data"} + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_union_branch_repairs_start_from_the_original_value( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + class Item(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: dict[str, Any] + + class Other(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: Message + + class UnionWrapper(BaseModel): + child: Item | Other + + register_state_type(UnionWrapper, type_id=f"pydantic_union_isolation_{serialization_format}_test") + raw_data = Message(role="user", contents=["plain data"]).to_dict() + session = AgentSession(session_id=f"union-isolation-{serialization_format}") + session.state["value"] = UnionWrapper( + child=Item(message=Message(role="user", contents=["persisted"]), data=raw_data) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_union-isolation", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_union-isolation" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Item) + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + assert child.data == raw_data + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_failed_union_branch_does_not_contaminate_fallback( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + class Item(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: Message + required: int + + class Other(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + message: Message + data: dict[str, Any] + + class UnionWrapper(BaseModel): + child: Item | Other + + register_state_type(UnionWrapper, type_id=f"pydantic_union_fallback_{serialization_format}_test") + raw_data = Message(role="user", contents=["plain data"]).to_dict() + session = AgentSession(session_id=f"union-fallback-{serialization_format}") + session.state["value"] = UnionWrapper( + child=Other(message=Message(role="user", contents=["persisted"]), data=raw_data) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_union-fallback", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_union-fallback" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Other) + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + assert child.data == raw_data + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_arbitrary_type_union_branch( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + class Other(BaseModel): + other: str + + class ArbitraryUnionWrapper(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + child: Message | Other + + register_state_type(ArbitraryUnionWrapper, type_id=f"pydantic_arbitrary_union_{serialization_format}_test") + session = AgentSession(session_id=f"arbitrary-union-{serialization_format}") + session.state["value"] = ArbitraryUnionWrapper(child=Message(role="user", contents=["persisted"])) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_arbitrary-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_arbitrary-union" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Message) + assert child.text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_nested_message_inside_discriminated_union( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Cat(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + kind: Literal["cat"] + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class Dog(BaseModel): + kind: Literal["dog"] + name: str + + class DiscriminatedUnionWrapper(BaseModel): + child: Cat | Dog = Field(discriminator="kind") + + register_state_type( + DiscriminatedUnionWrapper, + type_id=f"pydantic_discriminated_union_{serialization_format}_test", + ) + raw_data = {"type": "message", "note": "plain data"} + session = AgentSession(session_id=f"discriminated-union-{serialization_format}") + session.state["value"] = DiscriminatedUnionWrapper( + child=Cat( + kind="cat", + lastMessage=Message(role="user", contents=["persisted"]), + data=raw_data, + ) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_discriminated-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_discriminated-union" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Cat) + assert isinstance(child.last_message, Message) + assert child.last_message.text == "persisted" + assert child.data == raw_data + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_annotated_model_union_branch( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from typing import Annotated + + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + kind: Literal["item"] + message: Message + + class Other(BaseModel): + kind: Literal["other"] + other: str + + class AnnotatedUnionWrapper(BaseModel): + child: Annotated[Item, Field(description="tagged model")] | Other + + register_state_type( + AnnotatedUnionWrapper, + type_id=f"pydantic_annotated_union_{serialization_format}_test", + ) + session = AgentSession(session_id=f"annotated-union-{serialization_format}") + session.state["value"] = AnnotatedUnionWrapper( + child=Item(kind="item", message=Message(role="user", contents=["persisted"])) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_annotated-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_annotated-union" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Item) + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_dataclass_union_branch( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + @dataclass + class Item: + __pydantic_config__ = ConfigDict(arbitrary_types_allowed=True) + + kind: Literal["item"] + message: Message + + class Other(BaseModel): + kind: Literal["other"] + other: str + + class DataclassUnionWrapper(BaseModel): + child: Item | Other + + register_state_type( + DataclassUnionWrapper, + type_id=f"pydantic_dataclass_union_{serialization_format}_test", + ) + session = AgentSession(session_id=f"dataclass-union-{serialization_format}") + session.state["value"] = DataclassUnionWrapper( + child=Item(kind="item", message=Message(role="user", contents=["persisted"])) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_dataclass-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_dataclass-union" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Item) + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_typed_dict_union_branch( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + from typing_extensions import TypedDict + + class Item(TypedDict): + kind: Literal["item"] + message: Message + + # This is TypedDict metadata, not a field. Compute the attribute name + # so formatters do not turn it into an invalid direct class assignment. + setattr(Item, "__pydantic" + "_config__", ConfigDict(arbitrary_types_allowed=True)) + + class Other(BaseModel): + kind: Literal["other"] + other: str + + class TypedDictUnionWrapper(BaseModel): + child: Item | Other + + register_state_type( + TypedDictUnionWrapper, + type_id=f"pydantic_typed_dict_union_{serialization_format}_test", + ) + session = AgentSession(session_id=f"typed-dict-union-{serialization_format}") + session.state["value"] = TypedDictUnionWrapper( + child=Item(kind="item", message=Message(role="user", contents=["persisted"])) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_typed-dict-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_typed-dict-union" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, dict) + assert isinstance(child["message"], Message) + assert child["message"].text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_same_named_union_branches_try_each_matching_candidate( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + class FirstResult(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + kind: Literal["a"] = "a" + message: Message + + class SecondResult(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + kind: Literal["b"] = "b" + message: Message + + class DistinctResult(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + kind: Literal["b"] = "b" + message: Message + + FirstResult.__name__ = "Result" + FirstResult.__module__ = "provider_a" + SecondResult.__name__ = "Result" + SecondResult.__module__ = "provider_b" + DistinctResult.__module__ = "provider_b" + + class SameNameWrapper(BaseModel): + child: FirstResult | SecondResult + + class DistinctNameWrapper(BaseModel): + child: FirstResult | DistinctResult + + async def round_trip(wrapper_type: type[BaseModel], type_id: str, child: Any, storage_key: str) -> Any: + register_state_type(wrapper_type, type_id=type_id) + session = AgentSession(session_id=storage_key) + session.state["value"] = wrapper_type.model_validate({"child": child}) + store = FileSessionStore(tmp_path, serialization_format=serialization_format) + await store.set(storage_key, session) + restored = await store.get(storage_key) + assert restored is not None + return restored.state["value"].child + + first = await round_trip( + SameNameWrapper, + f"pydantic_same_name_first_{serialization_format}_test", + FirstResult(message=Message(role="user", contents=["first"])), + f"tenant_same-name-first-{serialization_format}", + ) + assert isinstance(first, FirstResult) + assert first.message.text == "first" + + second = await round_trip( + SameNameWrapper, + f"pydantic_same_name_first_{serialization_format}_test", + SecondResult(message=Message(role="user", contents=["second"])), + f"tenant_same-name-second-{serialization_format}", + ) + assert isinstance(second, SecondResult) + assert second.message.text == "second" + + distinct = await round_trip( + DistinctNameWrapper, + f"pydantic_distinct_name_{serialization_format}_test", + DistinctResult(message=Message(role="user", contents=["distinct"])), + f"tenant_distinct-name-{serialization_format}", + ) + assert isinstance(distinct, DistinctResult) + assert distinct.message.text == "distinct" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_union_candidate_codec_failure_does_not_abort_fallback( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict + + # A dataclass would let Pydantic construct this branch without invoking its codec. + class Fragile: # ruff:ignore[class-as-data-structure] + def __init__(self, value: str) -> None: + self.value = value + + fragile_type_id = f"fragile_union_candidate_{serialization_format}_test" + + def fail_fragile_decode(_value: Mapping[str, Any]) -> Fragile: + raise ValueError("candidate codec failed") + + register_state_type( + Fragile, + type_id=fragile_type_id, + encoder=lambda value: {"value": value.value}, + decoder=fail_fragile_decode, + ) + + class BrokenCandidate(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + value: Fragile + message: Message + + class Fallback(BaseModel): + model_config = ConfigDict(arbitrary_types_allowed=True) + + value: dict[str, Any] + message: Message + + class CodecFailureUnionWrapper(BaseModel): + child: BrokenCandidate | Fallback + + register_state_type( + CodecFailureUnionWrapper, + type_id=f"pydantic_union_codec_failure_{serialization_format}_test", + ) + raw_data = {"type": fragile_type_id, "value": "plain data"} + session = AgentSession(session_id=f"union-codec-failure-{serialization_format}") + session.state["value"] = CodecFailureUnionWrapper( + child=Fallback(value=raw_data, message=Message(role="user", contents=["persisted"])) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_union-codec-failure", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_union-codec-failure" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child, Fallback) + assert child.value == raw_data + assert isinstance(child.message, Message) + assert child.message.text == "persisted" + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_aliased_nested_message_inside_nullable_union( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class OptionalWrapper(BaseModel): + child: Item | None + + register_state_type(OptionalWrapper, type_id=f"pydantic_optional_alias_{serialization_format}_test") + session = AgentSession(session_id=f"optional-alias-{serialization_format}") + session.state["value"] = OptionalWrapper( + child=Item( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_optional-alias", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_optional-alias" + ) + + assert restored is not None + child = restored.state["value"].child + assert isinstance(child.last_message, Message) + assert child.last_message.text == "persisted" + assert child.data == {"type": "message", "note": "plain data"} + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + @pytest.mark.parametrize("container_kind", ["mapping", "sequence"]) + async def test_round_trips_nested_message_inside_container_union_branch( + self, + tmp_path: Path, + serialization_format: Literal["json", "msgpack"], + container_kind: Literal["mapping", "sequence"], + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class Other(BaseModel): + other: str + + item = Item( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + session = AgentSession(session_id=f"{container_kind}-union-{serialization_format}") + if container_kind == "mapping": + + class MappingUnionWrapper(BaseModel): + child: dict[str, Item] | Other + + register_state_type( + MappingUnionWrapper, + type_id=f"pydantic_{container_kind}_union_{serialization_format}_test", + ) + session.state["value"] = MappingUnionWrapper(child={"first": item}) + else: + + class SequenceUnionWrapper(BaseModel): + child: list[Item] | Other + + register_state_type( + SequenceUnionWrapper, + type_id=f"pydantic_{container_kind}_union_{serialization_format}_test", + ) + session.state["value"] = SequenceUnionWrapper(child=[item]) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + f"tenant_{container_kind}-union", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + f"tenant_{container_kind}-union" + ) + + assert restored is not None + child = restored.state["value"].child + restored_item = child["first"] if container_kind == "mapping" else child[0] + assert isinstance(restored_item.last_message, Message) + assert restored_item.last_message.text == "persisted" + assert restored_item.data == {"type": "message", "note": "plain data"} + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_nested_message_in_integer_keyed_mapping( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class MappingWrapper(BaseModel): + by_key: dict[int, Item] + + register_state_type(MappingWrapper, type_id=f"pydantic_integer_mapping_{serialization_format}_test") + session = AgentSession(session_id=f"integer-mapping-{serialization_format}") + session.state["value"] = MappingWrapper( + by_key={ + 7: Item( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + } + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set( + "tenant_integer-mapping", session + ) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get( + "tenant_integer-mapping" + ) + + assert restored is not None + item = restored.state["value"].by_key[7] + assert isinstance(item.last_message, Message) + assert item.last_message.text == "persisted" + assert item.data == {"type": "message", "note": "plain data"} + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + async def test_round_trips_nested_message_at_fixed_tuple_index( + self, tmp_path: Path, serialization_format: Literal["json", "msgpack"] + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + class TupleWrapper(BaseModel): + pair: tuple[int, Item] + + register_state_type(TupleWrapper, type_id=f"pydantic_fixed_tuple_{serialization_format}_test") + session = AgentSession(session_id=f"fixed-tuple-{serialization_format}") + session.state["value"] = TupleWrapper( + pair=( + 7, + Item( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ), + ) + ) + + await FileSessionStore(tmp_path, serialization_format=serialization_format).set("tenant_fixed-tuple", session) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get("tenant_fixed-tuple") + + assert restored is not None + item = restored.state["value"].pair[1] + assert isinstance(item.last_message, Message) + assert item.last_message.text == "persisted" + assert item.data == {"type": "message", "note": "plain data"} + + @pytest.mark.parametrize("serialization_format", ["json", "msgpack"]) + @pytest.mark.parametrize( + "container_kind", ["mapping_list", "mapping_mapping", "sequence_tuple", "mapping_tuple_list"] + ) + async def test_round_trips_nested_container_annotations( + self, + tmp_path: Path, + serialization_format: Literal["json", "msgpack"], + container_kind: str, + ) -> None: + from pydantic import BaseModel, ConfigDict, Field + + class Item(BaseModel): + model_config = ConfigDict( + arbitrary_types_allowed=True, + serialize_by_alias=True, + loc_by_alias=False, + ) + + last_message: Message = Field(alias="lastMessage") + data: dict[str, Any] + + item = Item( + lastMessage=Message(role="user", contents=["persisted"]), + data={"type": "message", "note": "plain data"}, + ) + value: BaseModel + if container_kind == "mapping_list": + + class MappingListState(BaseModel): + child: dict[str, list[Item]] + + value = MappingListState(child={"first": [item]}) + elif container_kind == "mapping_mapping": + + class MappingMappingState(BaseModel): + child: dict[str, dict[str, Item]] + + value = MappingMappingState(child={"first": {"second": item}}) + elif container_kind == "sequence_tuple": + + class SequenceTupleState(BaseModel): + child: list[tuple[int, Item]] + + value = SequenceTupleState(child=[(7, item)]) + else: + + class MappingTupleListState(BaseModel): + child: dict[str, tuple[int, list[Item]]] + + value = MappingTupleListState(child={"first": (7, [item])}) + + register_state_type(type(value), type_id=f"pydantic_nested_{container_kind}_{serialization_format}_test") + session = AgentSession(session_id=f"nested-{container_kind}-{serialization_format}") + session.state["value"] = value + await FileSessionStore(tmp_path, serialization_format=serialization_format).set("nested-annotation", session) + restored = await FileSessionStore(tmp_path, serialization_format=serialization_format).get("nested-annotation") + + assert restored is not None + child = restored.state["value"].child + if container_kind == "mapping_list": + restored_item = child["first"][0] + elif container_kind == "mapping_mapping": + restored_item = child["first"]["second"] + elif container_kind == "sequence_tuple": + assert child[0][0] == 7 + restored_item = child[0][1] + else: + assert child["first"][0] == 7 + restored_item = child["first"][1][0] + assert isinstance(restored_item, Item) + assert isinstance(restored_item.last_message, Message) + assert restored_item.last_message.text == "persisted" + assert restored_item.data == {"type": "message", "note": "plain data"} + async def test_round_trips_binary_messagepack_session(self, tmp_path: Path) -> None: store = FileSessionStore(tmp_path, serialization_format="msgpack") session = AgentSession(session_id="binary-session")