Implement Typesense-based session service

[amedeorizzo]

Closes: #3226

Introduce a new session service utilizing Typesense for state management and session handling.

Testing Plan
I've written 14 comprehensive unit tests in tests/unittests/sessions/test_typesense_session_service.py that cover all the functionality of TypesenseSessionService. The tests verify initialization with different protocols (HTTP and HTTPS), all CRUD operations for sessions and events, state management with the different prefixes (app:, user:, and session-level), pagination for large datasets, and proper error handling.

You can run the tests with:
pytest tests/unittests/sessions/test_typesense_session_service.py -v

Integration Testing
I've tested the service against a real Typesense server running locally in Docker. This involved creating sessions with complex nested state, adding events with various metadata, listing sessions for users with large numbers of sessions (to verify pagination works), and verifying that all data persists correctly.
I also tested against Typesense Cloud using HTTPS to make sure it works in production cloud environments, not just locally. The service connected successfully and all operations worked as expected.

For large datasets, I created 1000 sessions with 10 events each and verified that pagination works correctly in list_sessions.

Migration Script Testing
I tested the migration script by setting up a PostgreSQL database with sample data created using DatabaseSessionService, then running the migration script in dry-run mode first to verify it detects the correct number of records, and finally performing the actual migration. After migration, I verified data integrity by checking document counts in each Typesense collection and spot-checking that the data was transformed correctly.

Production Testing
I tested the implementation in a real-world scenario using my private implementation of adk-python. This involved building a Docker image that bundles the modified ADK code, running the agent in a container connected to Typesense, and verifying that sessions persist correctly across container restarts and multi-turn conversations work properly.

The Docker build process works correctly with the local ADK changes, and the agent successfully initializes
TypesenseSessionService and uses it for all session storage operations.

Backward Compatibility
I verified that when the typesense package is not installed, ADK still imports successfully and the other session services
(DatabaseSessionService and InMemorySessionService) continue to work normally.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @amedeorizzo, I'm Gemini Code Assist¹! 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 application's session management capabilities by integrating Typesense as a new, highly performant session service. This provides an alternative to the existing database-backed solution, offering flexibility in choosing the underlying storage for session data and events. The change also includes a refactoring of common state manipulation utilities, making them reusable across different session service implementations.

Highlights

• New Session Service: Introduced a new TypesenseSessionService for managing session state and events using Typesense as the backend.
• Dependency Update: Added typesense>=1.1.1 as a new dependency in pyproject.toml to support the new service.
• State Utility Refactoring: Moved state extraction and merging logic (extract_state_delta and merge_state) from database_session_service.py into _session_util.py to be shared across different session service implementations.
• Database Session Service Update: The existing DatabaseSessionService was updated to use the newly refactored state utility functions from _session_util.py.

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 👍 and 👎 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.

Footnotes

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. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new TypesenseSessionService for session management and refactors some shared state logic into a utility module. The implementation is quite thorough. My review focuses on a critical security vulnerability related to the use of pickle, a high-severity bug in session listing that could lead to data truncation, and several medium-severity suggestions to improve code consistency, clarity, and adherence to best practices.

[adk-bot]

Response from ADK Triaging Agent

Hello @amedeorizzo, thank you for your contribution!

To help us review this PR, could you please associate it with a GitHub issue? If one doesn't exist, please create one.

Also, could you please add a testing plan section to your PR description to detail how you've tested these changes?

This information is very helpful for our review process. Thanks!

[adk-bot]

Response from ADK Triaging Agent

Hello @amedeorizzo, thank you for creating this PR and for adding the detailed testing plan!

I've noticed a couple of things that need to be addressed before we can proceed with the review:

• Could you please associate a GitHub issue with this PR? If one doesn't exist, please create one. This helps us track the work.
• It looks like the Contributor License Agreement (CLA) hasn't been signed yet. You can find more information about it in the PR checks.

Addressing these items will help us move forward with the review process. Thanks!