adk-session-services 0.1.0__tar.gz

adk_session_services-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TiyeeJiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adk_session_services-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: adk-session-services
+Version: 0.1.0
+Summary: A Python package providing additional service implementations for the Google ADK framework (Redis, etc)
+Author-email: tiyee <tiyee@live.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tiyee/adk-session-service
+Project-URL: Source, https://github.com/tiyee/adk-session-service
+Keywords: adk,google-adk,session-service,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-adk
+Requires-Dist: google-generativeai>=0.8.5
+Requires-Dist: redis>=5.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.25.0; extra == "test"
+Requires-Dist: pytest-mock>=3.14.0; extra == "test"
+Requires-Dist: testcontainers>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.0; extra == "docs"
+Requires-Dist: furo>=2023.9.10; extra == "docs"
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Dynamic: license-file
+
+# adk-session-services
+
+Session service implementations for [Google's Agent Development Kit (ADK)](https://github.com/google/adk-python). Provides persistent session storage backends as drop-in replacements for ADK's `BaseSessionService`.
+
+## Features
+
+- **Redis** — Persistent session storage via Redis with support for app-level and user-level state layering.
+- **Firestore** — (Planned) Persistent session storage via Google Cloud Firestore.
+
+## Installation
+
+```bash
+pip install adk-session-services
+```
+
+## Quick Start
+
+### Redis
+
+```python
+from redis_session.redis_session_service import RedisSessionService
+
+service = RedisSessionService("redis://localhost:6379")
+
+session = await service.create_session(
+    app_name="my-app",
+    user_id="user-123",
+)
+```
+
+## Redis Key Schema
+
+All keys are prefixed with `adk:sessions:`:
+
+| Key pattern | Type | Purpose |
+|---|---|---|
+| `{app}:{user}:{session}:meta` | Hash | Session metadata |
+| `{app}:{user}:{session}:state` | String (JSON) | Session state dict |
+| `{app}:{user}:{session}:events` | List (JSON) | Ordered event log |
+| `{app}:{user}:sessions` | Set | Session IDs per user/app |
+| `{app}:app_state` | Hash | App-level state (shared across users) |
+| `{app}:{user}:user_state` | Hash | User-level state (shared across sessions) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Install with test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Format
+black src/ && isort src/
+
+# Type check
+mypy src/
+```
+
+## License
+
+MIT

adk_session_services-0.1.0/README.md

@@ -0,0 +1,65 @@
+# adk-session-services
+
+Session service implementations for [Google's Agent Development Kit (ADK)](https://github.com/google/adk-python). Provides persistent session storage backends as drop-in replacements for ADK's `BaseSessionService`.
+
+## Features
+
+- **Redis** — Persistent session storage via Redis with support for app-level and user-level state layering.
+- **Firestore** — (Planned) Persistent session storage via Google Cloud Firestore.
+
+## Installation
+
+```bash
+pip install adk-session-services
+```
+
+## Quick Start
+
+### Redis
+
+```python
+from redis_session.redis_session_service import RedisSessionService
+
+service = RedisSessionService("redis://localhost:6379")
+
+session = await service.create_session(
+    app_name="my-app",
+    user_id="user-123",
+)
+```
+
+## Redis Key Schema
+
+All keys are prefixed with `adk:sessions:`:
+
+| Key pattern | Type | Purpose |
+|---|---|---|
+| `{app}:{user}:{session}:meta` | Hash | Session metadata |
+| `{app}:{user}:{session}:state` | String (JSON) | Session state dict |
+| `{app}:{user}:{session}:events` | List (JSON) | Ordered event log |
+| `{app}:{user}:sessions` | Set | Session IDs per user/app |
+| `{app}:app_state` | Hash | App-level state (shared across users) |
+| `{app}:{user}:user_state` | Hash | User-level state (shared across sessions) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Install with test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Format
+black src/ && isort src/
+
+# Type check
+mypy src/
+```
+
+## License
+
+MIT

adk_session_services-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adk-session-services"
+version = "0.1.0"
+description = "A Python package providing additional service implementations for the Google ADK framework (Redis, etc)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "tiyee", email = "tiyee@live.com"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["adk", "google-adk", "session-service", "redis"]
+dependencies = [
+    "google-adk",
+    "google-generativeai>=0.8.5",
+    "redis>=5.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black",
+    "flake8",
+    "mypy",
+    "isort",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.0",
+    "pytest-mock>=3.14.0",
+    "testcontainers>=3.10.0",
+]
+docs = [
+    "sphinx>=7.2.0",
+    "furo>=2023.9.10",
+    "myst-parser>=2.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/tiyee/adk-session-service"
+"Source" = "https://github.com/tiyee/adk-session-service"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

adk_session_services-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adk_session_services-0.1.0/src/adk_session_services.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: adk-session-services
+Version: 0.1.0
+Summary: A Python package providing additional service implementations for the Google ADK framework (Redis, etc)
+Author-email: tiyee <tiyee@live.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tiyee/adk-session-service
+Project-URL: Source, https://github.com/tiyee/adk-session-service
+Keywords: adk,google-adk,session-service,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-adk
+Requires-Dist: google-generativeai>=0.8.5
+Requires-Dist: redis>=5.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.25.0; extra == "test"
+Requires-Dist: pytest-mock>=3.14.0; extra == "test"
+Requires-Dist: testcontainers>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.0; extra == "docs"
+Requires-Dist: furo>=2023.9.10; extra == "docs"
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Dynamic: license-file
+
+# adk-session-services
+
+Session service implementations for [Google's Agent Development Kit (ADK)](https://github.com/google/adk-python). Provides persistent session storage backends as drop-in replacements for ADK's `BaseSessionService`.
+
+## Features
+
+- **Redis** — Persistent session storage via Redis with support for app-level and user-level state layering.
+- **Firestore** — (Planned) Persistent session storage via Google Cloud Firestore.
+
+## Installation
+
+```bash
+pip install adk-session-services
+```
+
+## Quick Start
+
+### Redis
+
+```python
+from redis_session.redis_session_service import RedisSessionService
+
+service = RedisSessionService("redis://localhost:6379")
+
+session = await service.create_session(
+    app_name="my-app",
+    user_id="user-123",
+)
+```
+
+## Redis Key Schema
+
+All keys are prefixed with `adk:sessions:`:
+
+| Key pattern | Type | Purpose |
+|---|---|---|
+| `{app}:{user}:{session}:meta` | Hash | Session metadata |
+| `{app}:{user}:{session}:state` | String (JSON) | Session state dict |
+| `{app}:{user}:{session}:events` | List (JSON) | Ordered event log |
+| `{app}:{user}:sessions` | Set | Session IDs per user/app |
+| `{app}:app_state` | Hash | App-level state (shared across users) |
+| `{app}:{user}:user_state` | Hash | User-level state (shared across sessions) |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Install with test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Format
+black src/ && isort src/
+
+# Type check
+mypy src/
+```
+
+## License
+
+MIT

adk_session_services-0.1.0/src/adk_session_services.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/__init__.py
+src/adk_session_services.egg-info/PKG-INFO
+src/adk_session_services.egg-info/SOURCES.txt
+src/adk_session_services.egg-info/dependency_links.txt
+src/adk_session_services.egg-info/requires.txt
+src/adk_session_services.egg-info/top_level.txt
+src/firestore_session/__init__.py
+src/redis_session/__init__.py
+src/redis_session/redis_session_service.py

adk_session_services-0.1.0/src/adk_session_services.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adk_session_services-0.1.0/src/adk_session_services.egg-info/requires.txt

@@ -0,0 +1,23 @@
+google-adk
+google-generativeai>=0.8.5
+redis>=5.0.0
+python-dotenv>=1.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+black
+flake8
+mypy
+isort
+
+[docs]
+sphinx>=7.2.0
+furo>=2023.9.10
+myst-parser>=2.0.0
+
+[test]
+pytest>=8.0.0
+pytest-asyncio>=0.25.0
+pytest-mock>=3.14.0
+testcontainers>=3.10.0

adk_session_services-0.1.0/src/adk_session_services.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+__init__
+firestore_session
+redis_session

adk_session_services-0.1.0/src/redis_session/redis_session_service.py

@@ -0,0 +1,223 @@
+"""Redis session service implementation for Google ADK."""
+
+import json
+import logging
+import time
+import uuid
+from typing import Any, Optional
+
+import redis.asyncio as aioredis
+from google.adk.events.event import Event
+from google.adk.sessions.base_session_service import (
+    BaseSessionService,
+    GetSessionConfig,
+    ListSessionsResponse,
+)
+from google.adk.sessions.session import Session
+from google.adk.sessions.state import State
+
+DEFAULT_PREFIX = 'adk'
+
+
+def _meta_key(prefix:str,app: str, user: str, session: str) -> str:
+    return f"{prefix}:sessions:{app}:{user}:{session}:meta"
+
+
+def _state_key(app: str, user: str, session: str) -> str:
+    return f"adk:sessions:{app}:{user}:{session}:state"
+
+
+def _events_key(app: str, user: str, session: str) -> str:
+    return f"adk:sessions:{app}:{user}:{session}:events"
+
+
+def _user_set_key(app: str, user: str) -> str:
+    return f"adk:sessions:{app}:{user}:sessions"
+
+
+def _app_state_key(app: str) -> str:
+    return f"adk:sessions:{app}:app_state"
+
+
+def _user_state_key(app: str, user: str) -> str:
+    return f"adk:sessions:{app}:{user}:user_state"
+
+
+class RedisSessionService(BaseSessionService):
+
+    def __init__(self, redis_url: str, prefix: str = DEFAULT_PREFIX, **kwargs: Any):
+        self.logger = logging.getLogger(__name__)
+        self.client = aioredis.from_url(redis_url, **kwargs)
+        self.prefix = prefix
+
+    async def create_session(
+            self,
+            *,
+            app_name: str,
+            user_id: str,
+            state: Optional[dict[str, Any]] = None,
+            session_id: Optional[str] = None,
+    ) -> Session:
+        sid = session_id or uuid.uuid4().hex
+        now = time.time()
+        await self.client.hset(
+            _meta_key(app_name, user_id, sid),
+            mapping={"id": sid, "last_update_time": now},
+        )
+        await self.client.set(
+            _state_key(app_name, user_id, sid), json.dumps(state or {})
+        )
+        await self.client.delete(_events_key(app_name, user_id, sid))
+        await self.client.sadd(_user_set_key(app_name, user_id), sid)
+
+        # Create a session and merge state
+        session = Session(
+            id=sid,
+            app_name=app_name,
+            user_id=user_id,
+            state=state or {},
+            events=[],
+            last_update_time=now,
+        )
+        return await self._merge_state(app_name, user_id, session)
+
+    async def get_session(
+            self,
+            *,
+            app_name: str,
+            user_id: str,
+            session_id: str,
+            config: Optional[GetSessionConfig] = None,
+    ) -> Optional[Session]:
+        key = _meta_key(app_name, user_id, session_id)
+        if not await self.client.exists(key):
+            return None
+        meta = await self.client.hgetall(key)
+        last = float(meta.get(b"last_update_time", b"0"))
+        state = json.loads(
+            (await self.client.get(_state_key(app_name, user_id, session_id))) or b"{}"
+        )
+        raw = await self.client.lrange(
+            _events_key(app_name, user_id, session_id), 0, -1
+        )
+        events = [Event.model_validate_json(e.decode()) for e in raw]
+
+        # Apply config filters correctly
+        if config:
+            if config.after_timestamp is not None:
+                # Use >= instead of > to match the expected behavior in tests
+                events = [e for e in events if e.timestamp >= config.after_timestamp]
+            if config.num_recent_events is not None:
+                events = events[-config.num_recent_events:]
+
+        session = Session(
+            id=session_id,
+            app_name=app_name,
+            user_id=user_id,
+            state=state,
+            events=events,
+            last_update_time=last,
+        )
+        return await self._merge_state(app_name, user_id, session)
+
+    async def list_sessions(
+            self, *, app_name: str, user_id: str
+    ) -> ListSessionsResponse:
+        ids = await self.client.smembers(_user_set_key(app_name, user_id))
+        sessions: list[Session] = []
+        # Sort the session IDs to ensure consistent ordering for tests
+        sorted_ids = sorted([sid.decode() for sid in ids])
+        for sid_str in sorted_ids:
+            last_b = (
+                    await self.client.hget(
+                        _meta_key(app_name, user_id, sid_str), "last_update_time"
+                    )
+                    or b"0"
+            )
+            last = float(last_b)
+            sessions.append(
+                Session(
+                    id=sid_str,
+                    app_name=app_name,
+                    user_id=user_id,
+                    state={},
+                    events=[],
+                    last_update_time=last,
+                )
+            )
+        return ListSessionsResponse(sessions=sessions)
+
+    async def delete_session(
+            self, *, app_name: str, user_id: str, session_id: str
+    ) -> None:
+        keys = [
+            _meta_key(app_name, user_id, session_id),
+            _state_key(app_name, user_id, session_id),
+            _events_key(app_name, user_id, session_id),
+        ]
+        await self.client.delete(*keys)
+        await self.client.srem(_user_set_key(app_name, user_id), session_id)
+
+    async def append_event(self, session: Session, event: Event) -> Event:
+        if event.partial:
+            return event
+        mkey = _meta_key(self.prefix,session.app_name, session.user_id, session.id)
+        stored = await self.client.hget(mkey, "last_update_time") or b"0"
+        if float(stored) > session.last_update_time:
+            raise ValueError("stale session")
+
+        # Process the event using the parent class implementation
+        new_event = await super().append_event(session=session, event=event)
+
+        # Update user and app state if there's a state delta
+        if event.actions and event.actions.state_delta:
+            for key, value in event.actions.state_delta.items():
+                if key.startswith(State.APP_PREFIX):
+                    app_key = key.removeprefix(State.APP_PREFIX)
+                    await self.client.hset(
+                        _app_state_key(session.app_name), app_key, json.dumps(value)
+                    )
+                elif key.startswith(State.USER_PREFIX):
+                    user_key = key.removeprefix(State.USER_PREFIX)
+                    await self.client.hset(
+                        _user_state_key(session.app_name, session.user_id),
+                        user_key,
+                        json.dumps(value),
+                    )
+
+        # Save the event and update session state
+        await self.client.rpush(
+            _events_key(session.app_name, session.user_id, session.id),
+            new_event.model_dump_json(),
+        )
+        await self.client.set(
+            _state_key(session.app_name, session.user_id, session.id),
+            json.dumps(session.state),
+        )
+        await self.client.hset(mkey, "last_update_time", session.last_update_time)
+
+        return new_event
+
+    async def _merge_state(
+            self, app_name: str, user_id: str, session: Session
+    ) -> Session:
+        """Merge app and user state into the session state."""
+        # Merge app state
+        app_state = await self.client.hgetall(_app_state_key(app_name))
+        for key, value_json in app_state.items():
+            key_str = key.decode() if isinstance(key, bytes) else key
+            value = json.loads(
+                value_json.decode() if isinstance(value_json, bytes) else value_json
+            )
+            session.state[State.APP_PREFIX + key_str] = value
+
+        # Merge user state
+        user_state = await self.client.hgetall(_user_state_key(app_name, user_id))
+        for key, value_json in user_state.items():
+            key_str = key.decode() if isinstance(key, bytes) else key
+            value = json.loads(
+                value_json.decode() if isinstance(value_json, bytes) else value_json
+            )
+            session.state[State.USER_PREFIX + key_str] = value
+
+        return session