google-adk 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

google/adk/sessions/in_memory_session_service.py

@@ -0,0 +1,206 @@
+# 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.
+
+import copy
+import time
+from typing import Any
+from typing import Optional
+import uuid
+
+from typing_extensions import override
+
+from ..events.event import Event
+from .base_session_service import BaseSessionService
+from .base_session_service import GetSessionConfig
+from .base_session_service import ListEventsResponse
+from .base_session_service import ListSessionsResponse
+from .session import Session
+from .state import State
+
+
+class InMemorySessionService(BaseSessionService):
+  """An in-memory implementation of the session service."""
+
+  def __init__(self):
+    # A map from app name to a map from user ID to a map from session ID to session.
+    self.sessions: dict[str, dict[str, dict[str, Session]]] = {}
+    # A map from app name to a map from user ID to a map from key to the value.
+    self.user_state: dict[str, dict[str, dict[str, Any]]] = {}
+    # A map from app name to a map from key to the value.
+    self.app_state: dict[str, dict[str, Any]] = {}
+
+  @override
+  def create_session(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      state: Optional[dict[str, Any]] = None,
+      session_id: Optional[str] = None,
+  ) -> Session:
+    session_id = (
+        session_id.strip()
+        if session_id and session_id.strip()
+        else str(uuid.uuid4())
+    )
+    session = Session(
+        app_name=app_name,
+        user_id=user_id,
+        id=session_id,
+        state=state or {},
+        last_update_time=time.time(),
+    )
+
+    if app_name not in self.sessions:
+      self.sessions[app_name] = {}
+    if user_id not in self.sessions[app_name]:
+      self.sessions[app_name][user_id] = {}
+    self.sessions[app_name][user_id][session_id] = session
+
+    copied_session = copy.deepcopy(session)
+    return self._merge_state(app_name, user_id, copied_session)
+
+  @override
+  def get_session(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      config: Optional[GetSessionConfig] = None,
+  ) -> Session:
+    if app_name not in self.sessions:
+      return None
+    if user_id not in self.sessions[app_name]:
+      return None
+    if session_id not in self.sessions[app_name][user_id]:
+      return None
+
+    session = self.sessions[app_name][user_id].get(session_id)
+    copied_session = copy.deepcopy(session)
+
+    if config:
+      if config.num_recent_events:
+        copied_session.events = copied_session.events[
+            -config.num_recent_events :
+        ]
+      elif config.after_timestamp:
+        i = len(session.events) - 1
+        while i >= 0:
+          if copied_session.events[i].timestamp < config.after_timestamp:
+            break
+          i -= 1
+        if i >= 0:
+          copied_session.events = copied_session.events[i:]
+
+    return self._merge_state(app_name, user_id, copied_session)
+
+  def _merge_state(self, app_name: str, user_id: str, copied_session: Session):
+    # Merge app state
+    if app_name in self.app_state:
+      for key in self.app_state[app_name].keys():
+        copied_session.state[State.APP_PREFIX + key] = self.app_state[app_name][
+            key
+        ]
+
+    if (
+        app_name not in self.user_state
+        or user_id not in self.user_state[app_name]
+    ):
+      return copied_session
+
+    # Merge session state with user state.
+    for key in self.user_state[app_name][user_id].keys():
+      copied_session.state[State.USER_PREFIX + key] = self.user_state[app_name][
+          user_id
+      ][key]
+    return copied_session
+
+  @override
+  def list_sessions(
+      self, *, app_name: str, user_id: str
+  ) -> ListSessionsResponse:
+    empty_response = ListSessionsResponse()
+    if app_name not in self.sessions:
+      return empty_response
+    if user_id not in self.sessions[app_name]:
+      return empty_response
+
+    sessions_without_events = []
+    for session in self.sessions[app_name][user_id].values():
+      copied_session = copy.deepcopy(session)
+      copied_session.events = []
+      copied_session.state = {}
+      sessions_without_events.append(copied_session)
+    return ListSessionsResponse(sessions=sessions_without_events)
+
+  @override
+  def delete_session(
+      self, *, app_name: str, user_id: str, session_id: str
+  ) -> None:
+    if (
+        self.get_session(
+            app_name=app_name, user_id=user_id, session_id=session_id
+        )
+        is None
+    ):
+      return None
+
+    self.sessions[app_name][user_id].pop(session_id)
+
+  @override
+  def append_event(self, session: Session, event: Event) -> Event:
+    # Update the in-memory session.
+    super().append_event(session=session, event=event)
+    session.last_update_time = event.timestamp
+
+    # Update the storage session
+    app_name = session.app_name
+    user_id = session.user_id
+    session_id = session.id
+    if app_name not in self.sessions:
+      return event
+    if user_id not in self.sessions[app_name]:
+      return event
+    if session_id not in self.sessions[app_name][user_id]:
+      return event
+
+    if event.actions and event.actions.state_delta:
+      for key in event.actions.state_delta:
+        if key.startswith(State.APP_PREFIX):
+          self.app_state.setdefault(app_name, {})[
+              key.removeprefix(State.APP_PREFIX)
+          ] = event.actions.state_delta[key]
+
+        if key.startswith(State.USER_PREFIX):
+          self.user_state.setdefault(app_name, {}).setdefault(user_id, {})[
+              key.removeprefix(State.USER_PREFIX)
+          ] = event.actions.state_delta[key]
+
+    storage_session = self.sessions[app_name][user_id].get(session_id)
+    super().append_event(session=storage_session, event=event)
+
+    storage_session.last_update_time = event.timestamp
+
+    return event
+
+  @override
+  def list_events(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+  ) -> ListEventsResponse:
+    raise NotImplementedError()

google/adk/sessions/session.py

@@ -0,0 +1,54 @@
+# 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 typing import Any
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from ..events.event import Event
+
+
+class Session(BaseModel):
+  """Represents a series of interactions between a user and agents.
+
+  Attributes:
+    id: The unique identifier of the session.
+    app_name: The name of the app.
+    user_id: The id of the user.
+    state: The state of the session.
+    events: The events of the session, e.g. user input, model response, function
+      call/response, etc.
+    last_update_time: The last update time of the session.
+  """
+
+  model_config = ConfigDict(
+      extra='forbid',
+      arbitrary_types_allowed=True,
+  )
+
+  id: str
+  """The unique identifier of the session."""
+  app_name: str
+  """The name of the app."""
+  user_id: str
+  """The id of the user."""
+  state: dict[str, Any] = Field(default_factory=dict)
+  """The state of the session."""
+  events: list[Event] = Field(default_factory=list)
+  """The events of the session, e.g. user input, model response, function
+  call/response, etc."""
+  last_update_time: float = 0.0
+  """The last update time of the session."""

google/adk/sessions/state.py

@@ -0,0 +1,71 @@
+# 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 typing import Any
+
+
+class State:
+  """A state dict that maintain the current value and the pending-commit delta."""
+
+  APP_PREFIX = "app:"
+  USER_PREFIX = "user:"
+  TEMP_PREFIX = "temp:"
+
+  def __init__(self, value: dict[str, Any], delta: dict[str, Any]):
+    """
+    Args:
+      value: The current value of the state dict.
+      delta: The delta change to the current value that hasn't been commited.
+    """
+    self._value = value
+    self._delta = delta
+
+  def __getitem__(self, key: str) -> Any:
+    """Returns the value of the state dict for the given key."""
+    if key in self._delta:
+      return self._delta[key]
+    return self._value[key]
+
+  def __setitem__(self, key: str, value: Any):
+    """Sets the value of the state dict for the given key."""
+    # TODO: make new change only store in delta, so that self._value is only
+    #   updated at the storage commit time.
+    self._value[key] = value
+    self._delta[key] = value
+
+  def __contains__(self, key: str) -> bool:
+    """Whether the state dict contains the given key."""
+    return key in self._value or key in self._delta
+
+  def has_delta(self) -> bool:
+    """Whether the state has pending detla."""
+    return bool(self._delta)
+
+  def get(self, key: str, default: Any = None) -> Any:
+    """Returns the value of the state dict for the given key."""
+    if key not in self:
+      return default
+    return self[key]
+
+  def update(self, delta: dict[str, Any]):
+    """Updates the state dict with the given delta."""
+    self._value.update(delta)
+    self._delta.update(delta)
+
+  def to_dict(self) -> dict[str, Any]:
+    """Returns the state dict."""
+    result = {}
+    result.update(self._value)
+    result.update(self._delta)
+    return result

google/adk/sessions/vertex_ai_session_service.py

@@ -0,0 +1,356 @@
+# 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.
+import logging
+import re
+import time
+from typing import Any
+from typing import Optional
+
+from dateutil.parser import isoparse
+from google import genai
+from typing_extensions import override
+
+from ..events.event import Event
+from ..events.event_actions import EventActions
+from .base_session_service import BaseSessionService
+from .base_session_service import GetSessionConfig
+from .base_session_service import ListEventsResponse
+from .base_session_service import ListSessionsResponse
+from .session import Session
+
+logger = logging.getLogger(__name__)
+
+
+class VertexAiSessionService(BaseSessionService):
+  """Connects to the managed Vertex AI Session Service."""
+
+  def __init__(
+      self,
+      project: str = None,
+      location: str = None,
+  ):
+    self.project = project
+    self.location = location
+
+    client = genai.Client(vertexai=True, project=project, location=location)
+    self.api_client = client._api_client
+
+  @override
+  def create_session(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      state: Optional[dict[str, Any]] = None,
+      session_id: Optional[str] = None,
+  ) -> Session:
+    reasoning_engine_id = _parse_reasoning_engine_id(app_name)
+
+    session_json_dict = {'user_id': user_id}
+    if state:
+      session_json_dict['session_state'] = state
+
+    api_response = self.api_client.request(
+        http_method='POST',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions',
+        request_dict=session_json_dict,
+    )
+    logger.info(f'Create Session response {api_response}')
+
+    session_id = api_response['name'].split('/')[-3]
+    operation_id = api_response['name'].split('/')[-1]
+
+    max_retry_attempt = 5
+    while max_retry_attempt >= 0:
+      lro_response = self.api_client.request(
+          http_method='GET',
+          path=f'operations/{operation_id}',
+          request_dict={},
+      )
+
+      if lro_response.get('done', None):
+        break
+
+      time.sleep(1)
+      max_retry_attempt -= 1
+
+    # Get session resource
+    get_session_api_response = self.api_client.request(
+        http_method='GET',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}',
+        request_dict={},
+    )
+
+    update_timestamp = isoparse(
+        get_session_api_response['updateTime']
+    ).timestamp()
+    session = Session(
+        app_name=str(app_name),
+        user_id=str(user_id),
+        id=str(session_id),
+        state=get_session_api_response.get('sessionState', {}),
+        last_update_time=update_timestamp,
+    )
+    return session
+
+  @override
+  def get_session(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+      config: Optional[GetSessionConfig] = None,
+  ) -> Session:
+    reasoning_engine_id = _parse_reasoning_engine_id(app_name)
+
+    # Get session resource
+    get_session_api_response = self.api_client.request(
+        http_method='GET',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}',
+        request_dict={},
+    )
+
+    session_id = get_session_api_response['name'].split('/')[-1]
+    update_timestamp = isoparse(
+        get_session_api_response['updateTime']
+    ).timestamp()
+    session = Session(
+        app_name=str(app_name),
+        user_id=str(user_id),
+        id=str(session_id),
+        state=get_session_api_response.get('sessionState', {}),
+        last_update_time=update_timestamp,
+    )
+
+    list_events_api_response = self.api_client.request(
+        http_method='GET',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}/events',
+        request_dict={},
+    )
+
+    # Handles empty response case
+    if list_events_api_response.get('httpHeaders', None):
+      return session
+
+    session.events = [
+        _from_api_event(event)
+        for event in list_events_api_response['sessionEvents']
+    ]
+    session.events = [
+        event for event in session.events if event.timestamp <= update_timestamp
+    ]
+    session.events.sort(key=lambda event: event.timestamp)
+
+    if config:
+      if config.num_recent_events:
+        session.events = session.events[-config.num_recent_events :]
+      elif config.after_timestamp:
+        i = len(session.events) - 1
+        while i >= 0:
+          if session.events[i].timestamp < config.after_timestamp:
+            break
+          i -= 1
+        if i >= 0:
+          session.events = session.events[i:]
+
+    return session
+
+  @override
+  def list_sessions(
+      self, *, app_name: str, user_id: str
+  ) -> ListSessionsResponse:
+    reasoning_engine_id = _parse_reasoning_engine_id(app_name)
+
+    api_response = self.api_client.request(
+        http_method='GET',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions?filter=user_id={user_id}',
+        request_dict={},
+    )
+
+    # Handles empty response case
+    if api_response.get('httpHeaders', None):
+      return ListSessionsResponse()
+
+    sessions = []
+    for api_session in api_response['sessions']:
+      session = Session(
+          app_name=app_name,
+          user_id=user_id,
+          id=api_session['name'].split('/')[-1],
+          state={},
+          last_update_time=isoparse(api_session['updateTime']).timestamp(),
+      )
+      sessions.append(session)
+    return ListSessionsResponse(sessions=sessions)
+
+  def delete_session(
+      self, *, app_name: str, user_id: str, session_id: str
+  ) -> None:
+    reasoning_engine_id = _parse_reasoning_engine_id(app_name)
+    self.api_client.request(
+        http_method='DELETE',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}',
+        request_dict={},
+    )
+
+  @override
+  def list_events(
+      self,
+      *,
+      app_name: str,
+      user_id: str,
+      session_id: str,
+  ) -> ListEventsResponse:
+    reasoning_engine_id = _parse_reasoning_engine_id(app_name)
+    api_response = self.api_client.request(
+        http_method='GET',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}/events',
+        request_dict={},
+    )
+
+    logger.info(f'List events response {api_response}')
+
+    # Handles empty response case
+    if api_response.get('httpHeaders', None):
+      return ListEventsResponse()
+
+    session_events = api_response['sessionEvents']
+
+    return ListEventsResponse(
+        events=[_from_api_event(event) for event in session_events]
+    )
+
+  @override
+  def append_event(self, session: Session, event: Event) -> Event:
+    # Update the in-memory session.
+    super().append_event(session=session, event=event)
+
+    reasoning_engine_id = _parse_reasoning_engine_id(session.app_name)
+    self.api_client.request(
+        http_method='POST',
+        path=f'reasoningEngines/{reasoning_engine_id}/sessions/{session.id}:appendEvent',
+        request_dict=_convert_event_to_json(event),
+    )
+
+    return event
+
+
+def _convert_event_to_json(event: Event):
+  metadata_json = {
+      'partial': event.partial,
+      'turn_complete': event.turn_complete,
+      'interrupted': event.interrupted,
+      'branch': event.branch,
+      'long_running_tool_ids': (
+          list(event.long_running_tool_ids)
+          if event.long_running_tool_ids
+          else None
+      ),
+  }
+  if event.grounding_metadata:
+    metadata_json['grounding_metadata'] = event.grounding_metadata.model_dump(
+        exclude_none=True
+    )
+
+  event_json = {
+      'author': event.author,
+      'invocation_id': event.invocation_id,
+      'timestamp': {
+          'seconds': int(event.timestamp),
+          'nanos': int(
+              (event.timestamp - int(event.timestamp)) * 1_000_000_000
+          ),
+      },
+      'error_code': event.error_code,
+      'error_message': event.error_message,
+      'event_metadata': metadata_json,
+  }
+
+  if event.actions:
+    actions_json = {
+        'skip_summarization': event.actions.skip_summarization,
+        'state_delta': event.actions.state_delta,
+        'artifact_delta': event.actions.artifact_delta,
+        'transfer_agent': event.actions.transfer_to_agent,
+        'escalate': event.actions.escalate,
+        'requested_auth_configs': event.actions.requested_auth_configs,
+    }
+    event_json['actions'] = actions_json
+  if event.content:
+    event_json['content'] = event.content.model_dump(exclude_none=True)
+  if event.error_code:
+    event_json['error_code'] = event.error_code
+  if event.error_message:
+    event_json['error_message'] = event.error_message
+  return event_json
+
+
+def _from_api_event(api_event: dict) -> Event:
+  event_actions = EventActions()
+  if api_event.get('actions', None):
+    event_actions = EventActions(
+        skip_summarization=api_event['actions'].get('skipSummarization', None),
+        state_delta=api_event['actions'].get('stateDelta', {}),
+        artifact_delta=api_event['actions'].get('artifactDelta', {}),
+        transfer_to_agent=api_event['actions'].get('transferAgent', None),
+        escalate=api_event['actions'].get('escalate', None),
+        requested_auth_configs=api_event['actions'].get(
+            'requestedAuthConfigs', {}
+        ),
+    )
+
+  event = Event(
+      id=api_event['name'].split('/')[-1],
+      invocation_id=api_event['invocationId'],
+      author=api_event['author'],
+      actions=event_actions,
+      content=api_event.get('content', None),
+      timestamp=isoparse(api_event['timestamp']).timestamp(),
+      error_code=api_event.get('errorCode', None),
+      error_message=api_event.get('errorMessage', None),
+  )
+
+  if api_event.get('eventMetadata', None):
+    long_running_tool_ids_list = api_event['eventMetadata'].get(
+        'longRunningToolIds', None
+    )
+    event.partial = api_event['eventMetadata'].get('partial', None)
+    event.turn_complete = api_event['eventMetadata'].get('turnComplete', None)
+    event.interrupted = api_event['eventMetadata'].get('interrupted', None)
+    event.branch = api_event['eventMetadata'].get('branch', None)
+    event.grounding_metadata = api_event['eventMetadata'].get(
+        'groundingMetadata', None
+    )
+    event.long_running_tool_ids = (
+        set(long_running_tool_ids_list) if long_running_tool_ids_list else None
+    )
+
+  return event
+
+
+def _parse_reasoning_engine_id(app_name: str):
+  if app_name.isdigit():
+    return app_name
+
+  pattern = r'^projects/([a-zA-Z0-9-_]+)/locations/([a-zA-Z0-9-_]+)/reasoningEngines/(\d+)$'
+  match = re.fullmatch(pattern, app_name)
+
+  if not bool(match):
+    raise ValueError(
+        f'App name {app_name} is not valid. It should either be the full'
+        ' ReasoningEngine resource name, or the reasoning engine id.'
+    )
+
+  return match.groups()[-1]