google / google/adk-python-community
feat: Add BufferedFirestoreSessionService (batched, buffered Firestore session backend)
- Ngôn ngữ chính
- Python
- Star
- 182
- Fork
- 75
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
## 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
Hướng dẫn đóng góp
Hướng nghiên cứu
Rà soát PR #160 cùng với entry point google.adk_community.sessions được đề xuất. Kiểm tra 20 unit test đã mô tả và extra tùy chọn của Firestore, sau đó xác minh rằng hành vi buffered, timer, shutdown, durable-mode, layout, collection và retry khớp với issue trước khi coi công việc đã hoàn tất.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- google-cloud, python
- Lĩnh vực
- database
- Loại issue
- Tính năng
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 25/100