feat: add S3ArtifactService with native async and atomic versioning (#115)

* feat: add S3ArtifactService with native async and atomic versioning

Adds S3ArtifactService to the artifacts module, providing:
- Native async I/O via aioboto3 (no asyncio.to_thread wrappers)
- Atomic versioning using S3 IfNoneMatch conditional writes
- Session-scoped and user-scoped artifact namespacing
- Custom metadata (JSON-serialised in S3 user-metadata)
- Batch delete (1000 keys per request) for efficient cleanup
- Paginated listing for large artifact collections
- Parallel head_object calls in list_artifact_versions
- Optional [s3] dependency group (aioboto3>=13.0.0)
- Comprehensive test suite with full async mock infrastructure

Closes #37
Closes #71

* style: match codebase conventions for docstrings and comments

- Remove section comment banners (# --- heading --- patterns)
- Simplify module and class docstrings to one-liners
- Move Args section to __init__ docstring (matches RedisSessionService)
- Shorten method docstrings to single line
- Remove explanatory inline comments
- Clean up blank lines left from removals

* chore: remove accidental tests/__init__.py

* feat: add S3ArtifactService using aioboto3

Adds S3-backed artifact storage with:
- Atomic versioning via IfNoneMatch conditional writes
- Async-safe session initialization with asyncio.Lock
- Bounded concurrent head_object calls (semaphore=10)
- S3 metadata size validation (2KB limit)
- User-scoped artifact namespace support
- Full test coverage with mocked S3 client

* refactor(s3): address PR review comments

- Metadata size check now accounts for S3 x-amz-meta- prefix overhead
  (~11 bytes per key) in the 2KB limit calculation.
- Replace unconventional iter(int, 1) infinite loop with while True and
  add exponential backoff (100ms, 200ms, ... capped at 5s) between
  version conflict retries.
- list_artifact_keys now uses S3 Delimiter='/' with CommonPrefixes for
  O(unique-keys) efficiency instead of listing every version object.
- load_artifact returns Part.from_text() for text/* content types so
  consumers can check part.text consistently.

* fix(test): add importorskip guard for S3 optional dependencies

The S3 artifact tests require aioboto3 and botocore which are only
installed with the [s3] extra. CI runs with --extra test only, so
these tests fail with ModuleNotFoundError on collection.

Adding pytest.importorskip() at module level gracefully skips the
entire test file when the S3 dependencies aren't available.

* fix: address remaining review comments

- Consolidate aioboto3 import: cache module ref on self._aioboto3 in
  __init__, remove duplicate import in _get_session
- Default save_max_retries to 10 (safe cap) instead of -1 (infinite)
- Normalize metadata keys to lowercase in _flatten_metadata with
  case-collision warning (S3 metadata keys are case-insensitive)
- Handle ClientError in _head helper: return None for objects deleted
  between list_objects_v2 and head_object calls, skip in result loop

Author: miyannishar

pyproject.toml

@@ -24,12 +24,12 @@ classifiers = [ # List of https://pypi.org/classifiers/
 ]
 dependencies = [
   # go/keep-sorted start
-  "google-genai>=1.21.1, <2.0.0", # Google GenAI SDK
   "google-adk", # Google ADK
+  "google-genai>=1.21.1, <2.0.0", # Google GenAI SDK
   "httpx>=0.27.0, <1.0.0", # For OpenMemory service
+  "orjson>=3.11.3",
   "redis>=5.0.0, <6.0.0", # Redis for session storage
   # go/keep-sorted end
-  "orjson>=3.11.3",
 ]
 dynamic = ["version"]
 
@@ -40,6 +40,9 @@ changelog = "https://github.com/google/adk-python-community/blob/main/CHANGELOG.
 documentation = "https://google.github.io/adk-docs/"
 
 [project.optional-dependencies]
+s3 = [
+    "aioboto3>=13.0.0",  # For S3ArtifactService
+]
 test = [
     "pytest>=8.4.2",
     "pytest-asyncio>=1.2.0",

src/google/adk_community/__init__.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from . import artifacts
 from . import memory
 from . import sessions
 from . import version

src/google/adk_community/artifacts/README.md

@@ -0,0 +1,38 @@
+# Community Artifact Services
+
+This module contains community-contributed artifact service implementations for ADK.
+
+## Available Services
+
+### S3ArtifactService
+
+Production-ready artifact storage using Amazon S3 (or any S3-compatible service such as MinIO, DigitalOcean Spaces, etc.).
+
+**Installation:**
+```bash
+pip install google-adk-community[s3]
+```
+
+**Usage:**
+```python
+from google.adk_community.artifacts import S3ArtifactService
+
+artifact_service = S3ArtifactService(
+    bucket_name="my-adk-artifacts",
+    aws_configs={"region_name": "us-east-1"},
+)
+```
+
+**Features:**
+- Native async I/O via `aioboto3` (no `asyncio.to_thread` wrappers)
+- Atomic versioning using S3 conditional writes (`IfNoneMatch`)
+- Session-scoped and user-scoped artifacts
+- Automatic version management
+- Custom metadata support (JSON-serialised)
+- Batch delete for efficient cleanup
+- Paginated listing for large artifact collections
+- Works with S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
+
+**See Also:**
+- [S3ArtifactService Implementation](./s3_artifact_service.py)
+- [Tests](../../../tests/unittests/artifacts/test_s3_artifact_service.py)

src/google/adk_community/artifacts/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .s3_artifact_service import S3ArtifactService
+
+__all__ = [
+    'S3ArtifactService',
+]