google-adk-extras 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

google_adk_extras/streaming/__init__.py

@@ -0,0 +1,12 @@
+"""Streaming support (SSE/WebSocket) for google-adk-extras.
+
+This package provides an optional, persistent bi-directional streaming layer
+with strict ADK type parity by default. It complements ADK's built-in
+`/run`, `/run_sse`, and `/run_live` endpoints by offering per-channel
+subscription and send semantics for chat-style UIs.
+"""
+
+from .streaming_controller import StreamingConfig, StreamingController
+
+__all__ = ["StreamingConfig", "StreamingController"]
+

google_adk_extras/streaming/streaming_controller.py

@@ -0,0 +1,262 @@
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Callable, Awaitable
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+from google.adk.events.event import Event
+from google.adk.runners import Runner
+
+
+class StreamingConfig(BaseModel):
+    enable_streaming: bool = False
+    streaming_path_base: str = "/stream"
+    strict_types: bool = True
+    create_session_on_open: bool = True
+    ttl_seconds: int = 900
+    max_queue_size: int = 128
+    max_channels_per_user: int = 20
+    heartbeat_interval: Optional[float] = 20.0
+    reuse_session_policy: str = "per_channel"  # "per_channel" or "external"
+
+
+@dataclass
+class _Subscriber:
+    queue: "asyncio.Queue[str]"
+    kind: str  # "sse" | "ws"
+
+
+@dataclass
+class _Channel:
+    channel_id: str
+    app_name: str
+    user_id: str
+    session_id: str
+    in_q: "asyncio.Queue[Any]" = field(default_factory=asyncio.Queue)
+    subscribers: list[_Subscriber] = field(default_factory=list)
+    worker_task: Optional[asyncio.Task] = None
+    created_at: float = field(default_factory=lambda: time.time())
+    last_activity: float = field(default_factory=lambda: time.time())
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+
+class StreamingController:
+    """Manages streaming channels and workers.
+
+    This controller binds a channel to (app_name, user_id, session_id) and
+    runs a background worker per channel to execute streamed runs and push
+    ADK Event JSON to all subscribers.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: StreamingConfig,
+        get_runner_async: Callable[[str], Awaitable[Runner]],
+        session_service,
+    ) -> None:
+        self._config = config
+        self._get_runner_async = get_runner_async
+        self._session_service = session_service
+        self._channels: Dict[str, _Channel] = {}
+        self._gc_task: Optional[asyncio.Task] = None
+
+    def start(self) -> None:
+        if self._gc_task is None:
+            self._gc_task = asyncio.create_task(self._gc_loop())
+
+    async def stop(self) -> None:
+        if self._gc_task:
+            self._gc_task.cancel()
+            with asyncio.CancelledError:
+                pass
+            self._gc_task = None
+        # Cancel workers
+        for ch in list(self._channels.values()):
+            if ch.worker_task and not ch.worker_task.done():
+                ch.worker_task.cancel()
+        self._channels.clear()
+
+    def _ensure_user_limit(self, user_id: str) -> None:
+        if self._config.max_channels_per_user <= 0:
+            return
+        count = sum(1 for c in self._channels.values() if c.user_id == user_id)
+        if count >= self._config.max_channels_per_user:
+            raise HTTPException(status_code=429, detail="Too many channels for this user")
+
+    async def open_or_bind_channel(
+        self,
+        *,
+        channel_id: str,
+        app_name: str,
+        user_id: str,
+        session_id: Optional[str],
+    ) -> _Channel:
+        # Existing channel validation/match
+        if channel_id in self._channels:
+            ch = self._channels[channel_id]
+            if ch.app_name != app_name or ch.user_id != user_id:
+                raise HTTPException(status_code=409, detail="Channel binding conflict")
+            if session_id and session_id != ch.session_id:
+                raise HTTPException(status_code=409, detail="Channel already bound to different session")
+            ch.last_activity = time.time()
+            return ch
+
+        # New channel
+        self._ensure_user_limit(user_id)
+        if not session_id:
+            if not self._config.create_session_on_open:
+                raise HTTPException(status_code=400, detail="sessionId required for this channel")
+            # Create a fresh ADK session
+            create = getattr(self._session_service, "create_session", None)
+            if create is None:
+                # Older ADK interfaces may expose sync variant
+                create = getattr(self._session_service, "create_session_sync", None)
+            if create is None:
+                raise HTTPException(status_code=500, detail="Session service does not support create_session")
+            if asyncio.iscoroutinefunction(create):
+                session = await create(app_name=app_name, user_id=user_id)
+            else:
+                # Call sync and wrap
+                session = create(app_name=app_name, user_id=user_id)
+            session_id = session.id
+        else:
+            # Validate existing session
+            session = await self._session_service.get_session(app_name=app_name, user_id=user_id, session_id=session_id)
+            if not session:
+                raise HTTPException(status_code=404, detail="Session not found")
+
+        ch = _Channel(
+            channel_id=channel_id,
+            app_name=app_name,
+            user_id=user_id,
+            session_id=session_id,
+            in_q=asyncio.Queue(),
+        )
+        self._channels[channel_id] = ch
+        ch.worker_task = asyncio.create_task(self._worker(ch))
+        return ch
+
+    def subscribe(self, channel_id: str, kind: str) -> asyncio.Queue[str]:
+        if channel_id not in self._channels:
+            raise HTTPException(status_code=404, detail="Channel not found")
+        q: asyncio.Queue[str] = asyncio.Queue(maxsize=self._config.max_queue_size)
+        self._channels[channel_id].subscribers.append(_Subscriber(queue=q, kind=kind))
+        self._channels[channel_id].last_activity = time.time()
+        return q
+
+    def unsubscribe(self, channel_id: str, q: asyncio.Queue[str]) -> None:
+        ch = self._channels.get(channel_id)
+        if not ch:
+            return
+        ch.subscribers = [s for s in ch.subscribers if s.queue is not q]
+        ch.last_activity = time.time()
+
+    async def enqueue(self, channel_id: str, req: Any) -> None:
+        ch = self._channels.get(channel_id)
+        if not ch:
+            raise HTTPException(status_code=404, detail="Channel not found")
+        # Validate binding
+        if getattr(req, "app_name", None) != ch.app_name or getattr(req, "user_id", None) != ch.user_id or getattr(req, "session_id", None) != ch.session_id:
+            raise HTTPException(status_code=409, detail="Request does not match channel binding")
+        await ch.in_q.put(req)
+        ch.last_activity = time.time()
+
+    async def _worker(self, ch: _Channel) -> None:
+        try:
+            while True:
+                req = await ch.in_q.get()
+                ch.last_activity = time.time()
+                try:
+                    runner = await self._get_runner_async(ch.app_name)
+                    # Stream events for this request
+                    async with _aclosing(
+                        runner.run_async(
+                            user_id=ch.user_id,
+                            session_id=ch.session_id,
+                            new_message=req.new_message,
+                            state_delta=getattr(req, "state_delta", None),
+                            run_config=_maybe_run_config_streaming(True),
+                        )
+                    ) as agen:
+                        async for event in agen:
+                            await self._broadcast_event(ch, event)
+                except Exception as e:  # pragma: no cover - safety
+                    await self._broadcast_error(ch, str(e))
+        except asyncio.CancelledError:  # worker shutdown
+            return
+
+    async def _broadcast_event(self, ch: _Channel, event: Event) -> None:
+        payload = event.model_dump_json(exclude_none=True, by_alias=True)
+        for sub in list(ch.subscribers):
+            try:
+                sub.queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                # Drop subscriber on backpressure
+                ch.subscribers = [s for s in ch.subscribers if s is not sub]
+        ch.last_activity = time.time()
+
+    async def _broadcast_heartbeat(self, ch: _Channel) -> None:
+        if self._config.heartbeat_interval is None:
+            return
+        payload = '{"event":"heartbeat"}'
+        for sub in list(ch.subscribers):
+            try:
+                sub.queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                ch.subscribers = [s for s in ch.subscribers if s is not sub]
+
+    async def _broadcast_error(self, ch: _Channel, message: str) -> None:
+        payload = '{"error": %s}' % _json_escape(message)
+        for sub in list(ch.subscribers):
+            try:
+                sub.queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                ch.subscribers = [s for s in ch.subscribers if s is not sub]
+
+    async def _gc_loop(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(min(10, max(1, int(self._config.ttl_seconds / 3))))
+                now = time.time()
+                for cid, ch in list(self._channels.items()):
+                    idle = now - ch.last_activity
+                    if idle >= self._config.ttl_seconds and not ch.subscribers and ch.in_q.empty():
+                        if ch.worker_task and not ch.worker_task.done():
+                            ch.worker_task.cancel()
+                        self._channels.pop(cid, None)
+        except asyncio.CancelledError:
+            return
+
+
+# Utilities (avoid importing optional internals at module import time)
+def _maybe_run_config_streaming(enabled: bool):
+    # Support multiple ADK versions by resolving RunConfig/StreamingMode from
+    # either google.adk.runners or google.adk.agents.run_config
+    try:
+        from google.adk.runners import RunConfig  # type: ignore
+    except Exception:  # pragma: no cover - version fallback
+        from google.adk.agents.run_config import RunConfig  # type: ignore
+    try:
+        from google.adk.agents.run_config import StreamingMode  # type: ignore
+    except Exception:  # pragma: no cover - defensive
+        StreamingMode = type("StreamingMode", (), {"SSE": "sse", "NONE": None})  # minimal stub
+    return RunConfig(streaming_mode=StreamingMode.SSE if enabled else StreamingMode.NONE)
+
+
+class _aclosing:
+    def __init__(self, agen):
+        self._agen = agen
+    async def __aenter__(self):
+        return self._agen
+    async def __aexit__(self, exc_type, exc, tb):
+        try:
+            await self._agen.aclose()
+        except Exception:
+            pass
+
+
+def _json_escape(s: str) -> str:
+    return '"' + s.replace('\\', '\\\\').replace('"', '\\"') + '"'

{google_adk_extras-0.2.5.dist-info → google_adk_extras-0.2.7.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: google-adk-extras
-Version: 0.2.5
-Summary: Production-ready services, credentials, and FastAPI wiring for Google ADK
+Version: 0.2.7
+Summary: Production-ready services and FastAPI wiring for Google ADK
 Home-page: https://github.com/DeadMeme5441/google-adk-extras
 Author: DeadMeme5441
 Author-email: DeadMeme5441 <deadunderscorememe@gmail.com>
@@ -49,7 +49,7 @@ Dynamic: requires-python
 [![Docs](https://img.shields.io/badge/docs-site-brightgreen)](https://deadmeme5441.github.io/google-adk-extras/)
 [![Docs Build](https://github.com/DeadMeme5441/google-adk-extras/actions/workflows/docs.yml/badge.svg)](https://github.com/DeadMeme5441/google-adk-extras/actions/workflows/docs.yml)
 
-Production-ready extensions for Google ADK (Agent Development Kit). This library adds durable service backends (sessions, artifacts, memory), practical credential services (OAuth2/JWT/Basic), and clean FastAPI wiring so you can run ADK agents with real storage and auth.
+Production-ready extensions for Google ADK (Agent Development Kit). This library adds durable service backends (sessions, artifacts, memory) and clean FastAPI wiring (with optional streaming) so you can run ADK agents with real storage.
 
 What this is not: a fork of ADK. It builds on ADK’s core runtime, agents, tools and callbacks, and drops in where ADK expects services and a web server.
 
@@ -58,10 +58,9 @@ What this is not: a fork of ADK. It builds on ADK’s core runtime, agents, tool
 
 ADK provides the core primitives (Runner, Session/State, MemoryService, ArtifactService, CredentialService, Agents/Tools, callbacks, Dev UI, and deployment paths). See the official ADK docs for concepts and APIs.
 
-This package focuses on three gaps common in real apps:
+This package focuses on a few gaps common in real apps:
 - Durable storage backends beyond in‑memory defaults
-- Usable credential flows (Google/GitHub/Microsoft/X OAuth2, JWT, Basic)
-- FastAPI integration that accepts your credential service without hacks
+- FastAPI integration with optional streaming (SSE/WS)
 
 
 ## Features
@@ -69,8 +68,7 @@ This package focuses on three gaps common in real apps:
 - Session services: SQL (SQLite/Postgres/MySQL), MongoDB, Redis, YAML files
 - Artifact services: Local folder (versioned), S3‑compatible, SQL, MongoDB
 - Memory services: SQL, MongoDB, Redis, YAML files (term search over text parts)
-- Credential services: Google/GitHub/Microsoft/X (OAuth2), JWT, HTTP Basic
-- Enhanced FastAPI wiring that respects a provided credential service
+- Enhanced FastAPI wiring for ADK apps (with optional streaming)
 - Fluent builder (`AdkBuilder`) to assemble a FastAPI app or a Runner
  - A2A helpers for exposing/consuming agents (see below)
 
@@ -95,17 +93,17 @@ If you plan to use specific backends, also install their clients (examples):
 - MongoDB: `uv pip install pymongo`
 - Redis: `uv pip install redis`
 - S3: `uv pip install boto3`
-- JWT: `uv pip install PyJWT`
+  
+Note on credentials (0.2.7): This release removes custom credential services and URI helpers from this package. For outbound credentials used by tools, rely on ADK’s experimental BaseCredentialService (e.g., InMemory/SessionState) or your own ADK-compatible implementation. Inbound API authentication (protecting /run and streaming routes) will be provided as an optional FastAPI layer separately.
 
 
 ## Quickstart (FastAPI)
 
-Use the fluent builder to wire services and credentials. Then run with uvicorn.
+Use the fluent builder to wire services. Then run with uvicorn.
 
 ```python
 # app.py
 from google_adk_extras import AdkBuilder
-from google_adk_extras.credentials import GoogleOAuth2CredentialService
 
 app = (
     AdkBuilder()
@@ -113,11 +111,7 @@ app = (
     .with_session_service("sqlite:///./sessions.db")      # or: mongodb://, redis://, yaml://
     .with_artifact_service("local://./artifacts")         # or: s3://bucket, mongodb://, sql://
     .with_memory_service("yaml://./memory")               # or: redis://, mongodb://, sql://
-    .with_credential_service(GoogleOAuth2CredentialService(
-        client_id="…apps.googleusercontent.com",
-        client_secret="…",
-        scopes=["openid", "email", "profile"],
-    ))
+    # credentials: rely on ADK defaults or pass an ADK BaseCredentialService if needed
     .with_web_ui(True)     # serve ADK’s dev UI if assets available
     .with_agent_reload(True)
     .build_fastapi_app()
@@ -251,24 +245,8 @@ app = (
 ```
 
 
-## Credential URI cheatsheet (optional)
-
-If you prefer URIs instead of constructing services:
-
-- Google OAuth2: `oauth2-google://client_id:secret@scopes=openid,email,profile`
-- GitHub OAuth2: `oauth2-github://client_id:secret@scopes=user,repo`
-- Microsoft OAuth2: `oauth2-microsoft://<tenant>/<client_id>:<secret>@scopes=User.Read`
-- X OAuth2: `oauth2-x://client_id:secret@scopes=tweet.read,users.read`
-- JWT: `jwt://<secret>@algorithm=HS256&issuer=my-app&audience=api.example.com&expiration_minutes=60`
-- Basic: `basic-auth://username:password@realm=My%20API`
-
-```python
-cred = (
-    AdkBuilder()
-    .with_credential_service_uri("jwt://secret@issuer=my-app")
-    ._create_credential_service()
-)
-```
+<!-- Credential URI helpers removed. Use ADK’s BaseCredentialService directly if needed,
+     and handle inbound API authentication at FastAPI level. -->
 
 
 ## Notes & limitations

google_adk_extras-0.2.7.dist-info/RECORD

@@ -0,0 +1,32 @@
+google_adk_extras/__init__.py,sha256=NnpXFV1q3Y50qmHhbvVp-7wxpd6esrk_gooU7LaHiFM,851
+google_adk_extras/adk_builder.py,sha256=Ax5e_NegGZcdb_xm4t4e18gpJjcR5ICn0Zefy6VuLh4,30068
+google_adk_extras/custom_agent_loader.py,sha256=e_sgA58RmDzCUHCySAi3Hruxumtozw3UScZV2vxlCbw,5991
+google_adk_extras/enhanced_adk_web_server.py,sha256=4QxTADlQv6oXaAEVMQc7-bpf84jCrTkN6pJC6R2jmww,5348
+google_adk_extras/enhanced_fastapi.py,sha256=U7g24_c5-uQidCSs4Z158FWqR7qflW8O5EY9kqfuLqE,28202
+google_adk_extras/enhanced_runner.py,sha256=b7O1a9-4S49LduILOEDs6IxjCI4w_E39sc-Hs4y3Rys,1410
+google_adk_extras/artifacts/__init__.py,sha256=_IsKDgf6wanWR0HXvSpK9SiLa3n5URKLtazkKyH1P-o,931
+google_adk_extras/artifacts/base_custom_artifact_service.py,sha256=O9rkc250B3yDRYbyDI0EvTrCKvnih5_DQas5OF-hRMY,9721
+google_adk_extras/artifacts/local_folder_artifact_service.py,sha256=7oepQIHYimXxSjGl3-i1HgZ595H9hZWa3OptsMeyqgU,12509
+google_adk_extras/artifacts/mongo_artifact_service.py,sha256=K46Ycl7gkzCbCweVL0GrWsFxCcJ3T7JnE9gpIamfd6Y,7099
+google_adk_extras/artifacts/s3_artifact_service.py,sha256=inIc2KL3OdIQGkCA_HYJE0ZfGFQ3YcX_SFZEFVUb0T8,15655
+google_adk_extras/artifacts/sql_artifact_service.py,sha256=OovKSzM0nib2c-pzkv7NYyiHi8kFK-k3SFOMi92U4Mk,11980
+google_adk_extras/credentials/base_custom_credential_service.py,sha256=iYHacJAsZmDfpxLOPYx4tQpbtWTbwC75tRp6hlZFoSg,4014
+google_adk_extras/memory/__init__.py,sha256=2FFJXw9CZHctKXmCuc-lrdETeQ5xqdivy3oarHJz5gs,994
+google_adk_extras/memory/base_custom_memory_service.py,sha256=TRQMaXiRg2LXFwYZnFHoL-yBVtecuX1ownyPBJf6Xww,3613
+google_adk_extras/memory/mongo_memory_service.py,sha256=toXp7lg0el247zxY8HURY_7VxoaAPViZKnbvLCUxdWU,6747
+google_adk_extras/memory/redis_memory_service.py,sha256=P6vYvP8gv6kCH1lRB0SQld3mzS_JVKMUDtKifXDfu38,7400
+google_adk_extras/memory/sql_memory_service.py,sha256=cvAOsBZCFN3ruj0weuwvihgAnnvRJMO6HYMZX58rG9k,10760
+google_adk_extras/memory/yaml_file_memory_service.py,sha256=yx-nPqxXWxg9RI4OiwMAbdXs-eX1nBb1LzSWvib28S0,9909
+google_adk_extras/sessions/__init__.py,sha256=VgHyPULLzjJD7ShsyABz98rWVND0mOoM6qX74MrTJwA,915
+google_adk_extras/sessions/base_custom_session_service.py,sha256=npwrSNAtgqN6K7C8e4idiWkFNr_3pcOAiFYpGXu3NnI,8912
+google_adk_extras/sessions/mongo_session_service.py,sha256=Wo_dnsbnEex5rWeGOj5RABRhMICeaa4x--QBJPSur-4,8317
+google_adk_extras/sessions/redis_session_service.py,sha256=0G4yHWCngZz5w3UnQEigHXhgAqwttE8BTTYiDA1Hl7c,10428
+google_adk_extras/sessions/sql_session_service.py,sha256=TaOeEVWnwQ_8nvDZBW7e3qhzR_ecuGsjvZ_kh6Guq8g,14558
+google_adk_extras/sessions/yaml_file_session_service.py,sha256=g65ptJWAMVN4XQmCxQ0UwnSC2GU1NJ6QRvrwfzSK_xo,11797
+google_adk_extras/streaming/__init__.py,sha256=rcjmlCJHTlvUiCrx6qNGw5ObCnEtfENkGTvzfEiGL0M,461
+google_adk_extras/streaming/streaming_controller.py,sha256=Z72k5QgvWBIU2YP8iXlc3D3oWxDYWJo9eygj_KzALYA,10489
+google_adk_extras-0.2.7.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+google_adk_extras-0.2.7.dist-info/METADATA,sha256=ff9M_h1T_1bvq9RPCrd7z0eI_a9CWX_vnXmLH1qNTMA,10121
+google_adk_extras-0.2.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+google_adk_extras-0.2.7.dist-info/top_level.txt,sha256=DDWgVkz8G8ihPzznxAWyKa2jgJW3F6Fwy__qMddoKTs,18
+google_adk_extras-0.2.7.dist-info/RECORD,,

google_adk_extras/credentials/__init__.py

@@ -1,34 +0,0 @@
-"""Custom credential service implementations for Google ADK.
-
-Optional services are imported lazily to avoid import-time failures when
-their third-party dependencies are not installed.
-"""
-
-from .base_custom_credential_service import BaseCustomCredentialService
-from .google_oauth2_credential_service import GoogleOAuth2CredentialService
-from .github_oauth2_credential_service import GitHubOAuth2CredentialService
-from .microsoft_oauth2_credential_service import MicrosoftOAuth2CredentialService
-from .x_oauth2_credential_service import XOAuth2CredentialService
-from .http_basic_auth_credential_service import (
-    HTTPBasicAuthCredentialService,
-    HTTPBasicAuthWithCredentialsService,
-)
-
-# Optional: JWT (requires PyJWT)
-try:
-    from .jwt_credential_service import JWTCredentialService  # type: ignore
-except Exception:  # ImportError or transitive import errors
-    JWTCredentialService = None  # type: ignore
-
-__all__ = [
-    "BaseCustomCredentialService",
-    "GoogleOAuth2CredentialService",
-    "GitHubOAuth2CredentialService",
-    "MicrosoftOAuth2CredentialService",
-    "XOAuth2CredentialService",
-    "HTTPBasicAuthCredentialService",
-    "HTTPBasicAuthWithCredentialsService",
-]
-
-if JWTCredentialService is not None:
-    __all__.append("JWTCredentialService")

google_adk_extras/credentials/github_oauth2_credential_service.py

@@ -1,213 +0,0 @@
-"""GitHub OAuth2 credential service implementation."""
-
-from typing import Optional, List
-import logging
-
-from google.adk.auth.credential_service.session_state_credential_service import SessionStateCredentialService
-from google.adk.auth.credential_service.base_credential_service import CallbackContext
-from google.adk.auth import AuthConfig, AuthCredential, AuthCredentialTypes
-from google.adk.auth.auth_credential import OAuth2Auth
-from fastapi.openapi.models import OAuth2
-from fastapi.openapi.models import OAuthFlowAuthorizationCode, OAuthFlows
-
-from .base_custom_credential_service import BaseCustomCredentialService
-
-logger = logging.getLogger(__name__)
-
-
-class GitHubOAuth2CredentialService(BaseCustomCredentialService):
-    """GitHub OAuth2 credential service for handling GitHub authentication flows.
-    
-    This service provides pre-configured OAuth2 flows for GitHub APIs including
-    repository access, user information, and organization management.
-    
-    Args:
-        client_id: The GitHub OAuth2 client ID from GitHub Developer Settings.
-        client_secret: The GitHub OAuth2 client secret from GitHub Developer Settings.
-        scopes: List of OAuth2 scopes to request. Common scopes include:
-            - "user" - Access to user profile information
-            - "user:email" - Access to user email addresses
-            - "repo" - Full access to repositories
-            - "public_repo" - Access to public repositories only
-            - "admin:org" - Full access to organization data
-            - "read:org" - Read access to organization data
-            - "notifications" - Access to notifications
-        use_session_state: If True, stores credentials in session state. If False,
-            uses in-memory storage. Default is True for persistence.
-    
-    Example:
-        ```python
-        credential_service = GitHubOAuth2CredentialService(
-            client_id="your-github-client-id",
-            client_secret="your-github-client-secret", 
-            scopes=["user", "repo", "read:org"]
-        )
-        await credential_service.initialize()
-        
-        # Use with Runner
-        runner = Runner(
-            agent=agent,
-            session_service=session_service,
-            credential_service=credential_service,
-            app_name="my_app"
-        )
-        ```
-    """
-
-    # GitHub OAuth2 endpoints
-    GITHUB_AUTH_URL = "https://github.com/login/oauth/authorize"
-    GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token"
-    
-    # Common GitHub OAuth2 scopes
-    COMMON_SCOPES = {
-        "user": "Access to user profile information",
-        "user:email": "Access to user email addresses", 
-        "user:follow": "Access to follow/unfollow users",
-        "repo": "Full access to public and private repositories",
-        "public_repo": "Access to public repositories only",
-        "repo:status": "Access to commit status",
-        "repo_deployment": "Access to deployment status",
-        "admin:org": "Full control of orgs and teams, read/write org projects",
-        "write:org": "Read and write access to organization membership and projects",
-        "read:org": "Read-only access to organization membership and projects",
-        "admin:public_key": "Full control of user public keys",
-        "write:public_key": "Write access to user public keys",
-        "read:public_key": "Read access to user public keys",
-        "admin:repo_hook": "Full control of repository hooks",
-        "write:repo_hook": "Write access to repository hooks",
-        "read:repo_hook": "Read access to repository hooks",
-        "admin:org_hook": "Full control of organization hooks",
-        "gist": "Write access to gists",
-        "notifications": "Access to notifications",
-        "delete_repo": "Delete repositories",
-        "write:packages": "Upload packages to GitHub Package Registry",
-        "read:packages": "Download packages from GitHub Package Registry",
-        "workflow": "Update GitHub Action workflows"
-    }
-
-    def __init__(
-        self,
-        client_id: str,
-        client_secret: str,
-        scopes: Optional[List[str]] = None,
-        use_session_state: bool = True
-    ):
-        """Initialize the GitHub OAuth2 credential service.
-        
-        Args:
-            client_id: GitHub OAuth2 client ID.
-            client_secret: GitHub OAuth2 client secret.
-            scopes: List of OAuth2 scopes to request.
-            use_session_state: Whether to use session state for credential storage.
-        """
-        super().__init__()
-        self.client_id = client_id
-        self.client_secret = client_secret
-        self.scopes = scopes or ["user", "repo"]
-        self.use_session_state = use_session_state
-        
-        # Underlying credential service for storage
-        if use_session_state:
-            self._storage_service = SessionStateCredentialService()
-        else:
-            from google.adk.auth.credential_service.in_memory_credential_service import InMemoryCredentialService
-            self._storage_service = InMemoryCredentialService()
-
-    async def _initialize_impl(self) -> None:
-        """Initialize the GitHub OAuth2 credential service.
-        
-        Validates the client credentials and sets up the OAuth2 auth scheme.
-        
-        Raises:
-            ValueError: If client_id or client_secret is missing.
-        """
-        if not self.client_id:
-            raise ValueError("GitHub OAuth2 client_id is required")
-        if not self.client_secret:
-            raise ValueError("GitHub OAuth2 client_secret is required")
-        if not self.scopes:
-            raise ValueError("At least one OAuth2 scope is required")
-            
-        # Validate scopes against known GitHub scopes
-        unknown_scopes = set(self.scopes) - set(self.COMMON_SCOPES.keys())
-        if unknown_scopes:
-            logger.warning(f"Unknown GitHub OAuth2 scopes: {unknown_scopes}")
-            
-        logger.info(f"Initialized GitHub OAuth2 credential service with scopes: {self.scopes}")
-
-    def create_auth_config(self) -> AuthConfig:
-        """Create an AuthConfig for GitHub OAuth2 authentication.
-        
-        Returns:
-            AuthConfig: Configured auth config for GitHub OAuth2 flow.
-        """
-        self._check_initialized()
-        
-        # Create OAuth2 auth scheme
-        auth_scheme = OAuth2(
-            flows=OAuthFlows(
-                authorizationCode=OAuthFlowAuthorizationCode(
-                    authorizationUrl=self.GITHUB_AUTH_URL,
-                    tokenUrl=self.GITHUB_TOKEN_URL,
-                    scopes={
-                        scope: self.COMMON_SCOPES.get(scope, f"GitHub scope: {scope}")
-                        for scope in self.scopes
-                    }
-                )
-            )
-        )
-        
-        # Create OAuth2 credential
-        auth_credential = AuthCredential(
-            auth_type=AuthCredentialTypes.OAUTH2,
-            oauth2=OAuth2Auth(
-                client_id=self.client_id,
-                client_secret=self.client_secret
-            )
-        )
-        
-        return AuthConfig(
-            auth_scheme=auth_scheme,
-            raw_auth_credential=auth_credential
-        )
-
-    async def load_credential(
-        self,
-        auth_config: AuthConfig,
-        callback_context: CallbackContext,
-    ) -> Optional[AuthCredential]:
-        """Load GitHub OAuth2 credential from storage.
-        
-        Args:
-            auth_config: The auth config containing credential key information.
-            callback_context: The current callback context.
-            
-        Returns:
-            Optional[AuthCredential]: The stored credential or None if not found.
-        """
-        self._check_initialized()
-        return await self._storage_service.load_credential(auth_config, callback_context)
-
-    async def save_credential(
-        self,
-        auth_config: AuthConfig,
-        callback_context: CallbackContext,
-    ) -> None:
-        """Save GitHub OAuth2 credential to storage.
-        
-        Args:
-            auth_config: The auth config containing the credential to save.
-            callback_context: The current callback context.
-        """
-        self._check_initialized()
-        await self._storage_service.save_credential(auth_config, callback_context)
-        
-        logger.info(f"Saved GitHub OAuth2 credential for user {callback_context._invocation_context.user_id}")
-
-    def get_supported_scopes(self) -> dict:
-        """Get dictionary of supported GitHub OAuth2 scopes and their descriptions.
-        
-        Returns:
-            dict: Mapping of scope names to descriptions.
-        """
-        return self.COMMON_SCOPES.copy()