Skip to content

Python: fix(serialization): serialize tuple values to JSON-compatible lists in _serialize_value - #10374

Open
Hardik K (hardikkaurani) wants to merge 6 commits into
microsoft:mainfrom
hardikkaurani:fix/serialization-tuple-support
Open

Hardik K (hardikkaurani) wants to merge 6 commits into
microsoft:mainfrom
hardikkaurani:fix/serialization-tuple-support

Conversation

@hardikkaurani

Copy link
Copy Markdown
Contributor

Motivation & Context

In Python, SerializationMixin objects serialize their attributes to JSON-compatible dictionaries via to_dict(). However, _serialize_value previously checked only if isinstance(value, list): when handling sequences. Because tuple is not included in _DIRECT_JSON_TYPES or _JSON_SCALAR_TYPES, any attribute or container item typed as a tuple (e.g., coordinates: tuple[float, float] or tags: tuple[str, ...]) was treated as non-serializable and dropped (_SKIP_SERIALIZATION), silently omitting those fields during serialization.

This PR extends sequence serialization in _serialize_value to support tuple alongside list, converting tuple values into JSON-compatible lists consistently with make_json_safe and _sessions.py.

Description & Review Guide

  • What are the major changes?
    • Updated _serialize_value in packages/core/agent_framework/_serialization.py to accept (list, tuple) and cast to list[Any] | tuple[Any, ...].
    • Added unit tests in test_serializable_mixin.py covering tuple model attributes, nested tuples within lists and dictionaries, empty and single-element tuples, and mixed sequence structures.
  • What is the impact of these changes?
    • Tuple attributes on classes inheriting from SerializationMixin are now correctly serialized into JSON-compatible lists instead of being silently dropped.
    • No breaking changes; existing list and scalar serialization behavior is fully preserved.
  • What do you want reviewers to focus on?
    • Verification that converting tuples to JSON-compatible lists aligns with the serialization conventions elsewhere in the repository.

Related Issue

N/A - trivial change: Resolves silent omission of tuple attributes during SerializationMixin.to_dict() serialization.

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Used AI assistance for drafting test cases and verification.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Eduard van Valkenburg (@eavanvalkenburg),

Could you please take a look when you have a moment?

This PR addresses an issue where tuple attributes and tuple elements within containers were silently omitted by _serialize_value during SerializationMixin.to_dict() because only list was handled in sequence serialization. The fix extends sequence checks to (list, tuple) so tuples are consistently serialized to JSON-compatible lists, matching the behavior in make_json_safe and _sessions.py.

All unit tests and lint checks are passing locally. Thank you for your time and feedback!

@agent-framework-automation agent-framework-automation Bot added the python Usage: [Issues, PRs], Target: Python label Nov 15, 2026

@surlymochan Nick (surlymochan) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified the tuple handling end to end and the tests cover the shapes that matter (flat, nested, empty/single-element, mixed list-of-tuples and tuple-of-lists). Two questions, both about the round trip rather than the serialization itself:

  1. to_dict() now emits tuples as JSON lists, but from_dict() restores them as lists, so a tuple attribute does not survive a round trip (coordinates comes back a list, not a tuple). Consumers doing isinstance(x, tuple) or unpacking with tuple-only expectations would see a type change after a save/load cycle. Is list-only round-tripping the accepted contract here, or should from_dict restore tuples where the model declares tuple fields? If it is accepted, a one-line note in the docstring would save the next reader the same question.
  2. The circular-reference guard keys on id() of the container. That is safe while the container is alive on the recursion stack, and the new tests show the guard still trips correctly — but a tuple can (transitively) contain itself via a mutable element, e.g. t = ([],); t[0].append(t). Is that case covered anywhere, or worth a regression test to pin the ValueError rather than a RecursionError?

Non-blocking: the change is minimal and the added tests are well targeted.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Nick (@surlymochan),

Thanks for the great feedback and for digging into these details!

  1. Tuple -> List round-trip: Yes, list-only is currently the accepted contract across SerializationMixin. Because JSON and to_dict() have no native tuple primitive, sequences serialize to JSON-compatible lists, and from_dict() reconstructs directly from that dictionary payload without inspecting class type annotations to coerce sequences back to tuples (unless a model's __init__ does it explicitly). Adding a note in the docstring about this is a great call—I'll keep that in mind for doc updates!
  2. Circular references with tuples: Because isinstance(value, (list, tuple)) shares the same active container tracking, a transitive cycle like t = ([],); t[0].append(t) is caught when the recursion enters t[0] and re-encounters id(t), so it reliably raises ValueError("Circular reference detected") rather than recursing.

Really appreciate the thoughtful review and sanity check!

This branch was successfully deployed

No deployments
github-app-auth — e5dda4bf Deployed Nov 15, 2026 by hardikkaurani via team_check #9503
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants