feat: add Update Session State Delta Endpoint with PATCH functionality

[japerry911]

feat: add Update Session State Delta Endpoint with PATCH functionality

• mimics Python-ADK Update Session functionality in REST API
  • ADK docs pointing to this endpoint, here

GitHub Issue

This PR addresses and closes #444

Notes on Changes

• Update .gitignore to exclude JetBrains IntelliJ IDE configuration files

• Add update session endpoint and state delta patch support

• Add support for PATCH method in CORS and API route handler

• Wire up UpdateSessionHandler for session update endpoint

• Improve PatchSessionStateDelta to accept stateDelta parameter and add request body validation

• Add PatchState method to session services with associated tests and handler wiring

• adding some doc strings

Notes on CURL commands for new endpoint

curl --location --request PATCH 'http://localhost:8080/api/apps/<APP-NAME>/users/<USER-ID>/sessions/<SESSION-ID> \
--header 'Content-Type: application/json' \
--data '{
    "stateDelta": {
        "test": "123"
    }
}'

• returns 200, and entire state that is patched if successful

[gemini-code-assist]

Summary of Changes

Hello @japerry911, 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 introduces a new PATCH endpoint for updating session state, providing a flexible mechanism to modify session, user, and application-level state without generating new events. This enhancement aligns the API server's session management capabilities with the Python-ADK, allowing for granular control over state attributes, including the ability to add, overwrite, or delete specific keys.

Highlights

• New Session State Delta Endpoint: Introduced a PATCH endpoint to update session state, mirroring Python-ADK functionality.
• CORS and Routing Support: Added PATCH method support to CORS configuration and API routing.
• State Delta Processing: Implemented logic to normalize state delta requests, including handling special directives for deleting state keys.
• Service Layer Integration: Integrated the PatchState method into both in-memory and database session services for persistent and temporary state updates.
• Comprehensive Testing: Added unit tests for the PatchState functionality in the in-memory service to ensure correctness.
• IDE Ignore: Updated .gitignore to exclude JetBrains IntelliJ IDE configuration files.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

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 PATCH endpoint for updating session state, which mimics the Python-ADK functionality. The changes include adding the endpoint, handler, service-layer logic for both database and in-memory implementations, and corresponding tests. My review focuses on correctness, consistency between implementations, and maintainability. I've identified a bug in the in-memory service implementation where it doesn't correctly handle deletions for app/user state. I've also suggested improvements to test coverage and code structure to reduce duplication.

[japerry911]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new PATCH endpoint for updating a session's state, which is a valuable addition for mimicking the Python-ADK functionality. The implementation is thorough, covering changes in the API router, CORS configuration, controllers, and both database and in-memory session services. The inclusion of comprehensive tests for the new PatchState functionality and state deletion semantics is excellent. I've identified a critical issue that could lead to a panic in the database service implementation and a high-severity performance concern related to fetching all session events in the PATCH response. Addressing these points will make the implementation more robust and efficient.

[baptmont]

Hi @japerry911 thank you for the contribution. It seems like your current implementation is modifying the state directly, without requiring an event. However we want for the history of state modifications to be persisted in the events, not only is this important for observability but it is required for upcoming features such as branching and reverting a session to a previous moment.
Looking at the ADK python patch implementation a new event is being created and appended to the session using the service's appendEvent method https://github.com/google/adk-python/blob/07bb1647588a781e701257c4c379736537029ea0/src/google/adk/cli/adk_web_server.py#L879 and this would be the desired approach.
Once again thank you for your contribution and let us know if you can pick this up!

[japerry911]

Hi @japerry911 thank you for the contribution. It seems like your current implementation is modifying the state directly, without requiring an event. However we want for the history of state modifications to be persisted in the events, not only is this important for observability but it is required for upcoming features such as branching and reverting a session to a previous moment.

Looking at the ADK python patch implementation a new event is being created and appended to the session using the service's appendEvent method https://github.com/google/adk-python/blob/07bb1647588a781e701257c4c379736537029ea0/src/google/adk/cli/adk_web_server.py#L879 and this would be the desired approach.

Once again thank you for your contribution and let us know if you can pick this up!

Hello @baptmont , yes , I see what you are saying. I misread ADK Python and thought it did not append event for this endpoint. Apologies on that, I will get an update pushed and tested before next week.

Thank you for the feedback.

[japerry911]

Hello @baptmont ,

Once again thank you for the great feedback and guiding me to follow the ADK architecture correctly 🙏 .

I have pushed an update that utilizes 'append events' functionality instead of direct state manipulation.

Below is a screenshot of a Postgres events example where state was updated 3 times.

My only question, should a "null" value passed in state, completely remove the state variable key/value, or should it stay as null? Currently in this implementation it stays as null.

Thank you.

[japerry911]

@baptmont just bumping this, it's ready for review again. let me know any other feedback. We have been using it in our Alpha environment for ADK Agent, and it's been working well thus far.

[japerry911]

@baptmont , any update? Do I need to change and improve anything else in this PR?

Thank you