google / google/adk-python-community

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

Đang mở
#159 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.