Add Python serialization examples

[Sakeeb91]

Summary

• add a lightweight Serializer/Serializable implementation for the Python SDK so the docs can point at runnable snippets
• replace the "Example coming soon" placeholders in docs/modules/serialization.mdx with concrete Python and TypeScript examples that follow existing codegroup conventions
• add focused pytest coverage for the new serializer behavior and surface the Python examples under python/examples/serialization

Design Decisions

• kept the serializer API intentionally minimal (registry-based with JSON payloads) to mirror the TypeScript shape without pulling in heavy dependencies
• registered core backend message types lazily so docs examples (and deserialization) work without forcing global imports
• stored Python examples alongside existing samples to stay consistent with the docs embedding workflow

Testing

• python/.venv/bin/python -m pytest python/tests/serialization/test_serializer.py
• python/.venv/bin/python -m pytest -m unit (fails: missing optional deps deepeval, outlines)

Closes #1200.

[gemini-code-assist[bot]]

Summary of Changes

Hello @Sakeeb91, I'm Gemini Code Assist[^1]! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Python SDK by introducing a robust, yet lightweight, serialization framework. The primary goal is to provide concrete, runnable examples within the documentation, improving clarity and usability for developers. This involves not only the creation of the serialization mechanism itself but also its integration into existing core components and the addition of comprehensive examples and tests to validate its functionality.

Highlights

• New Serialization Framework: Introduced a lightweight Serializer and Serializable implementation for the Python SDK, designed to be registry-based with JSON payloads and a minimal API.
• Documentation Examples: Replaced 'Example coming soon' placeholders in docs/modules/serialization.mdx with concrete, runnable Python and TypeScript serialization examples, following existing codegroup conventions.
• Core Component Serialization: Implemented serialization capabilities for key framework components, including datetime objects and memory classes (UnconstrainedMemory, TokenMemory), by integrating them with the new Serializable mixin.
• Lazy Registration of Message Types: Core backend message types are now registered lazily with the serializer, ensuring that documentation examples and deserialization work without forcing global imports.
• New Test Coverage: Added focused pytest coverage for the new serializer behavior, including tests for datetime roundtrips, memory serialization, custom class registration, and Serializable subclass functionality.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with :thumbsup: and :thumbsdown: on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

[^1]: Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

[Sakeeb91]

Thanks for the thorough review! I pushed a follow-up that:

• adds reference tracking/__ref support to the Python serializer so shared instances and cycles survive a round trip (with new identity + cycle tests)
• tightens the backend message deserializer to validate the 'type' field explicitly
• switches Serializable.from_snapshot to use __new__ instead of assuming a no-arg __init__
• updates the context example to ship a real serialized payload and list both UserMessage and AssistantMessage in extra_classes

Let me know if you spot anything else!

[sandijean90]

@Sakeeb91 thanks for your work here! We're excited to have you on board as a contributor. I've assigned to @Tomas2D to review/comment before merging.

[Tomas2D]

Thank you for your hard work! I am thinking if there is a more Pythonic way of doing that (pickling). What do you think?

[Sakeeb91]

@Tomas2D thanks for the thoughtful suggestion! I explored pickle early on, but stuck with this JSON serializer for a couple reasons: it keeps deserialization side-effect free (pickle executes arbitrary code), the snapshots need to round-trip through our JavaScript SDK, and JSON is a lot easier to diff/debug in docs and tooling. With the reference tracking and tighter registry in this patch we close the identity gaps the review pointed out while staying interoperable.

[Tomas2D]

I see your point. Thank you for the research. Before we merge this, can you verify that some basic examples work in both TS and Python so that one can use dump from TS and use it in Python, and vice versa?

[Sakeeb91]

Verified the TS ↔︎ Python round-trip with runnable snippets:

• TS → Py: Serializer.serialize(UnconstrainedMemory) snapshot restores via UnconstrainedMemory.from_serialized(...), yielding the original UserMessage/AssistantMessage texts.
• Py → TS: Python memory.serialize() payload hydrates in TypeScript by deserializing the memory and resolving each serializer node (same message types/text).

Commands + outputs are in reviewer_verification.md (above). I also reran poetry run pytest tests/serialization/test_serializer.py. Let me know if you’d like the raw dumps or any additional coverage.

[Tomas2D]

Hello @Sakeeb91. Would you be willing to address the comments I mentioned? I am ready to help if you need me. Thank you!

[Sakeeb91]

@Tomas2D Thank you for the buzz. I may have overlooked your previous comments and gone on with my life. I have addressed the changes. I hope they are alright!