google / google/adk-python-community

feat: Add BufferedFirestoreSessionService (batched, buffered Firestore session backend)

Open
#159 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
184
Forks
76
PR merge metrics
No merged PRs in 30d

Description

What this is

ADK already ships a Firestore session service (google.adk.integrations.firestore.FirestoreSessionService). It works well, but it does one Firestore transaction per event — so if 10 messages fire 10 events, that's 10 separate writes, each touching the session document to bump its revision.

This adds a BufferedFirestoreSessionService to the community package that holds events in memory and flushes them all in a single transaction when the buffer fills up (or on a timer, or on shutdown). The session document gets updated once instead of 10 times, and the state docs get merged once.

When to use it

You want this if:

  • You're on a budget and Firestore costs matter (fewer writes = lower bill)
  • Your service runs stably and you can afford to lose the last few seconds of events if it crashes

You want the builtin instead if:

  • You need every event durable the moment it happens
  • You're running in an environment where the process can be killed without warning

Both services use the same Firestore layout, so they're compatible with each other's data.

What's in the PR

  • BufferedFirestoreSessionService in google.adk_community.sessions
  • Configurable buffer size, flush interval, retry behaviour
  • durable_mode=True flag to fall back to per-event writes (same as builtin)
  • flat_layout=True option for a flat root_collection/{session_id} layout instead of the default ADK nested path
  • All collection names configurable if your Firestore uses a custom structure
  • 20 unit tests, no external dependencies
  • New [firestore] optional extra (google-cloud-firestore>=2.11,<3, matching ADK's own constraint)

PR: #160

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review PR #160 alongside the proposed google.adk_community.sessions entry point. Check the 20 described unit tests and the Firestore optional extra, then verify buffered, timer, shutdown, durable-mode, layout, collection, and retry behavior match the issue before considering the work done.

Written by the indexing model from the issue text.

Assessment

Tech stack
google-cloud, python
Domain
database
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.