google / google/adk-python-community
feat: Add BufferedFirestoreSessionService (batched, buffered Firestore session backend)
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
BufferedFirestoreSessionServiceingoogle.adk_community.sessions- Configurable buffer size, flush interval, retry behaviour
durable_mode=Trueflag to fall back to per-event writes (same as builtin)flat_layout=Trueoption for a flatroot_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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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