google-adk 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

google/adk/runners.py

@@ -108,7 +108,7 @@ class Runner:
     """Runs the agent.
 
     NOTE: This sync interface is only for local testing and convenience purpose.
-    Consider to use `run_async` for production usage.
+    Consider using `run_async` for production usage.
 
     Args:
       user_id: The user ID of the session.

google/adk/sessions/database_session_service.py

@@ -12,23 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import base64
 import copy
 from datetime import datetime
 import json
 import logging
-from typing import Any
-from typing import Optional
+from typing import Any, Optional
 import uuid
 
+from google.genai import types
+from sqlalchemy import Boolean
 from sqlalchemy import delete
 from sqlalchemy import Dialect
 from sqlalchemy import ForeignKeyConstraint
 from sqlalchemy import func
-from sqlalchemy import select
 from sqlalchemy import Text
 from sqlalchemy.dialects import postgresql
 from sqlalchemy.engine import create_engine
 from sqlalchemy.engine import Engine
+from sqlalchemy.exc import ArgumentError
 from sqlalchemy.ext.mutable import MutableDict
 from sqlalchemy.inspection import inspect
 from sqlalchemy.orm import DeclarativeBase
@@ -53,6 +55,7 @@ from .base_session_service import ListSessionsResponse
 from .session import Session
 from .state import State
 
+
 logger = logging.getLogger(__name__)
 
 
@@ -102,7 +105,7 @@ class StorageSession(Base):
       String, primary_key=True, default=lambda: str(uuid.uuid4())
   )
 
-  state: Mapped[dict] = mapped_column(
+  state: Mapped[MutableDict[str, Any]] = mapped_column(
       MutableDict.as_mutable(DynamicJSON), default={}
   )
 
@@ -133,8 +136,20 @@ class StorageEvent(Base):
   author: Mapped[str] = mapped_column(String)
   branch: Mapped[str] = mapped_column(String, nullable=True)
   timestamp: Mapped[DateTime] = mapped_column(DateTime(), default=func.now())
-  content: Mapped[dict] = mapped_column(DynamicJSON)
-  actions: Mapped[dict] = mapped_column(PickleType)
+  content: Mapped[dict[str, Any]] = mapped_column(DynamicJSON, nullable=True)
+  actions: Mapped[MutableDict[str, Any]] = mapped_column(PickleType)
+
+  long_running_tool_ids_json: Mapped[Optional[str]] = mapped_column(
+      Text, nullable=True
+  )
+  grounding_metadata: Mapped[dict[str, Any]] = mapped_column(
+      DynamicJSON, nullable=True
+  )
+  partial: Mapped[bool] = mapped_column(Boolean, nullable=True)
+  turn_complete: Mapped[bool] = mapped_column(Boolean, nullable=True)
+  error_code: Mapped[str] = mapped_column(String, nullable=True)
+  error_message: Mapped[str] = mapped_column(String, nullable=True)
+  interrupted: Mapped[bool] = mapped_column(Boolean, nullable=True)
 
   storage_session: Mapped[StorageSession] = relationship(
       "StorageSession",
@@ -149,13 +164,28 @@ class StorageEvent(Base):
       ),
   )
 
+  @property
+  def long_running_tool_ids(self) -> set[str]:
+    return (
+        set(json.loads(self.long_running_tool_ids_json))
+        if self.long_running_tool_ids_json
+        else set()
+    )
+
+  @long_running_tool_ids.setter
+  def long_running_tool_ids(self, value: set[str]):
+    if value is None:
+      self.long_running_tool_ids_json = None
+    else:
+      self.long_running_tool_ids_json = json.dumps(list(value))
+
 
 class StorageAppState(Base):
   """Represents an app state stored in the database."""
   __tablename__ = "app_states"
 
   app_name: Mapped[str] = mapped_column(String, primary_key=True)
-  state: Mapped[dict] = mapped_column(
+  state: Mapped[MutableDict[str, Any]] = mapped_column(
       MutableDict.as_mutable(DynamicJSON), default={}
   )
   update_time: Mapped[DateTime] = mapped_column(
@@ -169,7 +199,7 @@ class StorageUserState(Base):
 
   app_name: Mapped[str] = mapped_column(String, primary_key=True)
   user_id: Mapped[str] = mapped_column(String, primary_key=True)
-  state: Mapped[dict] = mapped_column(
+  state: Mapped[MutableDict[str, Any]] = mapped_column(
       MutableDict.as_mutable(DynamicJSON), default={}
   )
   update_time: Mapped[DateTime] = mapped_column(
@@ -187,15 +217,22 @@ class DatabaseSessionService(BaseSessionService):
     """
     # 1. Create DB engine for db connection
     # 2. Create all tables based on schema
-    # 3. Initialize all properies
-
-    supported_dialects = ["postgresql", "mysql", "sqlite"]
-    dialect = db_url.split("://")[0]
+    # 3. Initialize all properties
 
-    if dialect in supported_dialects:
+    try:
       db_engine = create_engine(db_url)
-    else:
-      raise ValueError(f"Unsupported database URL: {db_url}")
+    except Exception as e:
+      if isinstance(e, ArgumentError):
+        raise ValueError(
+            f"Invalid database URL format or argument '{db_url}'."
+        ) from e
+      if isinstance(e, ImportError):
+        raise ValueError(
+            f"Database related module not found for URL '{db_url}'."
+        ) from e
+      raise ValueError(
+          f"Failed to create database engine for URL '{db_url}'"
+      ) from e
 
     # Get the local timezone
     local_timezone = get_localzone()
@@ -287,7 +324,6 @@ class DatabaseSessionService(BaseSessionService):
           last_update_time=storage_session.update_time.timestamp(),
       )
       return session
-    return None
 
   @override
   def get_session(
@@ -301,7 +337,6 @@ class DatabaseSessionService(BaseSessionService):
     # 1. Get the storage session entry from session table
     # 2. Get all the events based on session id and filtering config
     # 3. Convert and return the session
-    session: Session = None
     with self.DatabaseSessionFactory() as sessionFactory:
       storage_session = sessionFactory.get(
           StorageSession, (app_name, user_id, session_id)
@@ -348,13 +383,19 @@ class DatabaseSessionService(BaseSessionService):
               author=e.author,
               branch=e.branch,
               invocation_id=e.invocation_id,
-              content=e.content,
+              content=_decode_content(e.content),
               actions=e.actions,
               timestamp=e.timestamp.timestamp(),
+              long_running_tool_ids=e.long_running_tool_ids,
+              grounding_metadata=e.grounding_metadata,
+              partial=e.partial,
+              turn_complete=e.turn_complete,
+              error_code=e.error_code,
+              error_message=e.error_message,
+              interrupted=e.interrupted,
           )
           for e in storage_events
       ]
-
     return session
 
   @override
@@ -379,7 +420,6 @@ class DatabaseSessionService(BaseSessionService):
         )
         sessions.append(session)
       return ListSessionsResponse(sessions=sessions)
-    raise ValueError("Failed to retrieve sessions.")
 
   @override
   def delete_session(
@@ -398,7 +438,7 @@ class DatabaseSessionService(BaseSessionService):
   def append_event(self, session: Session, event: Event) -> Event:
     logger.info(f"Append event: {event} to session {session.id}")
 
-    if event.partial and not event.content:
+    if event.partial:
       return event
 
     # 1. Check if timestamp is stale
@@ -447,19 +487,34 @@ class DatabaseSessionService(BaseSessionService):
       storage_user_state.state = user_state
       storage_session.state = session_state
 
-      encoded_content = event.content.model_dump(exclude_none=True)
       storage_event = StorageEvent(
           id=event.id,
           invocation_id=event.invocation_id,
           author=event.author,
           branch=event.branch,
-          content=encoded_content,
           actions=event.actions,
           session_id=session.id,
           app_name=session.app_name,
           user_id=session.user_id,
           timestamp=datetime.fromtimestamp(event.timestamp),
+          long_running_tool_ids=event.long_running_tool_ids,
+          grounding_metadata=event.grounding_metadata,
+          partial=event.partial,
+          turn_complete=event.turn_complete,
+          error_code=event.error_code,
+          error_message=event.error_message,
+          interrupted=event.interrupted,
       )
+      if event.content:
+        encoded_content = event.content.model_dump(exclude_none=True)
+        # Workaround for multimodal Content throwing JSON not serializable
+        # error with SQLAlchemy.
+        for p in encoded_content["parts"]:
+          if "inline_data" in p:
+            p["inline_data"]["data"] = (
+                base64.b64encode(p["inline_data"]["data"]).decode("utf-8"),
+            )
+        storage_event.content = encoded_content
 
       sessionFactory.add(storage_event)
 
@@ -481,8 +536,7 @@ class DatabaseSessionService(BaseSessionService):
       user_id: str,
       session_id: str,
   ) -> ListEventsResponse:
-    pass
-
+    raise NotImplementedError()
 
 def convert_event(event: StorageEvent) -> Event:
   """Converts a storage event to an event."""
@@ -497,7 +551,7 @@ def convert_event(event: StorageEvent) -> Event:
   )
 
 
-def _extract_state_delta(state: dict):
+def _extract_state_delta(state: dict[str, Any]):
   app_state_delta = {}
   user_state_delta = {}
   session_state_delta = {}
@@ -520,3 +574,14 @@ def _merge_state(app_state, user_state, session_state):
   for key in user_state.keys():
     merged_state[State.USER_PREFIX + key] = user_state[key]
   return merged_state
+
+
+def _decode_content(
+    content: Optional[dict[str, Any]],
+) -> Optional[types.Content]:
+  if not content:
+    return None
+  for p in content["parts"]:
+    if "inline_data" in p:
+      p["inline_data"]["data"] = base64.b64decode(p["inline_data"]["data"][0])
+  return types.Content.model_validate(content)

google/adk/sessions/state.py

@@ -26,7 +26,7 @@ class State:
     """
     Args:
       value: The current value of the state dict.
-      delta: The delta change to the current value that hasn't been commited.
+      delta: The delta change to the current value that hasn't been committed.
     """
     self._value = value
     self._delta = delta
@@ -49,7 +49,7 @@ class State:
     return key in self._value or key in self._delta
 
   def has_delta(self) -> bool:
-    """Whether the state has pending detla."""
+    """Whether the state has pending delta."""
     return bool(self._delta)
 
   def get(self, key: str, default: Any = None) -> Any:

google/adk/telemetry.py

@@ -16,8 +16,8 @@
 #
 #    We expect that the underlying GenAI SDK will provide a certain
 #    level of tracing and logging telemetry aligned with Open Telemetry
-#    Semantic Conventions (such as logging prompts, respones, request
-#    properties, etc.) and so the information that is recorded by the
+#    Semantic Conventions (such as logging prompts, responses,
+#    request properties, etc.) and so the information that is recorded by the
 #    Agent Development Kit should be focused on the higher-level
 #    constructs of the framework that are not observable by the SDK.
 

google/adk/tools/agent_tool.py

@@ -45,10 +45,9 @@ class AgentTool(BaseTool):
     skip_summarization: Whether to skip summarization of the agent output.
   """
 
-  def __init__(self, agent: BaseAgent):
+  def __init__(self, agent: BaseAgent, skip_summarization: bool = False):
     self.agent = agent
-    self.skip_summarization: bool = False
-    """Whether to skip summarization of the agent output."""
+    self.skip_summarization: bool = skip_summarization
 
     super().__init__(name=agent.name, description=agent.description)
 

google/adk/tools/application_integration_tool/clients/integration_client.py

@@ -196,11 +196,12 @@ class IntegrationClient:
       action_details = connections_client.get_action_schema(action)
       input_schema = action_details["inputSchema"]
       output_schema = action_details["outputSchema"]
-      action_display_name = action_details["displayName"]
+      # Remove spaces from the display name to generate valid spec
+      action_display_name = action_details["displayName"].replace(" ", "")
       operation = "EXECUTE_ACTION"
       if action == "ExecuteCustomQuery":
         connector_spec["components"]["schemas"][
-            f"{action}_Request"
+            f"{action_display_name}_Request"
         ] = connections_client.execute_custom_query_request()
         operation = "EXECUTE_QUERY"
       else:

google/adk/tools/base_tool.py

@@ -73,7 +73,7 @@ class BaseTool(ABC):
 
     Args:
       args: The LLM-filled arguments.
-      ctx: The context of the tool.
+      tool_context: The context of the tool.
 
     Returns:
       The result of running the tool.

google/adk/tools/function_parameter_parse_util.py

@@ -53,7 +53,7 @@ def _raise_for_any_of_if_mldev(schema: types.Schema):
 
 def _update_for_default_if_mldev(schema: types.Schema):
   if schema.default is not None:
-    # TODO(kech): Remove this walkaround once mldev supports default value.
+    # TODO(kech): Remove this workaround once mldev supports default value.
     schema.default = None
     logger.warning(
         'Default value is not supported in function declaration schema for'
@@ -291,7 +291,7 @@ def _parse_schema_from_parameter(
     return schema
   raise ValueError(
       f'Failed to parse the parameter {param} of function {func_name} for'
-      ' automatic function calling.Automatic function calling works best with'
+      ' automatic function calling. Automatic function calling works best with'
       ' simpler function signature schema,consider manually parse your'
       f' function declaration for function {func_name}.'
   )

google/adk/tools/google_api_tool/__init__.py

@@ -11,4 +11,77 @@
 # 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 .google_api_tool_sets import calendar_tool_set
+__all__ = [
+    'bigquery_tool_set',
+    'calendar_tool_set',
+    'gmail_tool_set',
+    'youtube_tool_set',
+    'slides_tool_set',
+    'sheets_tool_set',
+    'docs_tool_set',
+]
+
+# Nothing is imported here automatically
+# Each tool set will only be imported when accessed
+
+_bigquery_tool_set = None
+_calendar_tool_set = None
+_gmail_tool_set = None
+_youtube_tool_set = None
+_slides_tool_set = None
+_sheets_tool_set = None
+_docs_tool_set = None
+
+
+def __getattr__(name):
+  global _bigquery_tool_set, _calendar_tool_set, _gmail_tool_set, _youtube_tool_set, _slides_tool_set, _sheets_tool_set, _docs_tool_set
+
+  match name:
+    case 'bigquery_tool_set':
+      if _bigquery_tool_set is None:
+        from .google_api_tool_sets import bigquery_tool_set as bigquery
+
+        _bigquery_tool_set = bigquery
+      return _bigquery_tool_set
+
+    case 'calendar_tool_set':
+      if _calendar_tool_set is None:
+        from .google_api_tool_sets import calendar_tool_set as calendar
+
+        _calendar_tool_set = calendar
+      return _calendar_tool_set
+
+    case 'gmail_tool_set':
+      if _gmail_tool_set is None:
+        from .google_api_tool_sets import gmail_tool_set as gmail
+
+        _gmail_tool_set = gmail
+      return _gmail_tool_set
+
+    case 'youtube_tool_set':
+      if _youtube_tool_set is None:
+        from .google_api_tool_sets import youtube_tool_set as youtube
+
+        _youtube_tool_set = youtube
+      return _youtube_tool_set
+
+    case 'slides_tool_set':
+      if _slides_tool_set is None:
+        from .google_api_tool_sets import slides_tool_set as slides
+
+        _slides_tool_set = slides
+      return _slides_tool_set
+
+    case 'sheets_tool_set':
+      if _sheets_tool_set is None:
+        from .google_api_tool_sets import sheets_tool_set as sheets
+
+        _sheets_tool_set = sheets
+      return _sheets_tool_set
+
+    case 'docs_tool_set':
+      if _docs_tool_set is None:
+        from .google_api_tool_sets import docs_tool_set as docs
+
+        _docs_tool_set = docs
+      return _docs_tool_set

google/adk/tools/google_api_tool/google_api_tool_set.py

@@ -11,10 +11,12 @@
 # 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 __future__ import annotations
+
 import inspect
 import os
 from typing import Any
-from typing import Dict
 from typing import Final
 from typing import List
 from typing import Optional
@@ -28,6 +30,7 @@ from .googleapi_to_openapi_converter import GoogleApiToOpenApiConverter
 
 
 class GoogleApiToolSet:
+  """Google API Tool Set."""
 
   def __init__(self, tools: List[RestApiTool]):
     self.tools: Final[List[GoogleApiTool]] = [
@@ -45,10 +48,10 @@ class GoogleApiToolSet:
 
   @staticmethod
   def _load_tool_set_with_oidc_auth(
-      spec_file: str = None,
-      spec_dict: Dict[str, Any] = None,
-      scopes: list[str] = None,
-  ) -> Optional[OpenAPIToolset]:
+      spec_file: Optional[str] = None,
+      spec_dict: Optional[dict[str, Any]] = None,
+      scopes: Optional[list[str]] = None,
+  ) -> OpenAPIToolset:
     spec_str = None
     if spec_file:
       # Get the frame of the caller
@@ -90,18 +93,18 @@ class GoogleApiToolSet:
 
   @classmethod
   def load_tool_set(
-      cl: Type['GoogleApiToolSet'],
+      cls: Type[GoogleApiToolSet],
       api_name: str,
       api_version: str,
-  ) -> 'GoogleApiToolSet':
+  ) -> GoogleApiToolSet:
     spec_dict = GoogleApiToOpenApiConverter(api_name, api_version).convert()
     scope = list(
         spec_dict['components']['securitySchemes']['oauth2']['flows'][
             'authorizationCode'
         ]['scopes'].keys()
     )[0]
-    return cl(
-        cl._load_tool_set_with_oidc_auth(
+    return cls(
+        cls._load_tool_set_with_oidc_auth(
             spec_dict=spec_dict, scopes=[scope]
         ).get_tools()
     )

google/adk/tools/google_api_tool/google_api_tool_sets.py

@@ -19,37 +19,94 @@ from .google_api_tool_set import GoogleApiToolSet
 
 logger = logging.getLogger(__name__)
 
-calendar_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="calendar",
-    api_version="v3",
-)
-
-bigquery_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="bigquery",
-    api_version="v2",
-)
-
-gmail_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="gmail",
-    api_version="v1",
-)
-
-youtube_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="youtube",
-    api_version="v3",
-)
-
-slides_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="slides",
-    api_version="v1",
-)
-
-sheets_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="sheets",
-    api_version="v4",
-)
-
-docs_tool_set = GoogleApiToolSet.load_tool_set(
-    api_name="docs",
-    api_version="v1",
-)
+_bigquery_tool_set = None
+_calendar_tool_set = None
+_gmail_tool_set = None
+_youtube_tool_set = None
+_slides_tool_set = None
+_sheets_tool_set = None
+_docs_tool_set = None
+
+
+def __getattr__(name):
+  """This method dynamically loads and returns GoogleApiToolSet instances for
+
+  various Google APIs. It uses a lazy loading approach, initializing each
+  tool set only when it is first requested. This avoids unnecessary loading
+  of tool sets that are not used in a given session.
+
+  Args:
+      name (str): The name of the tool set to retrieve (e.g.,
+        "bigquery_tool_set").
+
+  Returns:
+      GoogleApiToolSet: The requested tool set instance.
+
+  Raises:
+      AttributeError: If the requested tool set name is not recognized.
+  """
+  global _bigquery_tool_set, _calendar_tool_set, _gmail_tool_set, _youtube_tool_set, _slides_tool_set, _sheets_tool_set, _docs_tool_set
+
+  match name:
+    case "bigquery_tool_set":
+      if _bigquery_tool_set is None:
+        _bigquery_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="bigquery",
+            api_version="v2",
+        )
+
+      return _bigquery_tool_set
+
+    case "calendar_tool_set":
+      if _calendar_tool_set is None:
+        _calendar_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="calendar",
+            api_version="v3",
+        )
+
+      return _calendar_tool_set
+
+    case "gmail_tool_set":
+      if _gmail_tool_set is None:
+        _gmail_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="gmail",
+            api_version="v1",
+        )
+
+      return _gmail_tool_set
+
+    case "youtube_tool_set":
+      if _youtube_tool_set is None:
+        _youtube_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="youtube",
+            api_version="v3",
+        )
+
+      return _youtube_tool_set
+
+    case "slides_tool_set":
+      if _slides_tool_set is None:
+        _slides_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="slides",
+            api_version="v1",
+        )
+
+      return _slides_tool_set
+
+    case "sheets_tool_set":
+      if _sheets_tool_set is None:
+        _sheets_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="sheets",
+            api_version="v4",
+        )
+
+      return _sheets_tool_set
+
+    case "docs_tool_set":
+      if _docs_tool_set is None:
+        _docs_tool_set = GoogleApiToolSet.load_tool_set(
+            api_name="docs",
+            api_version="v1",
+        )
+
+      return _docs_tool_set

google/adk/tools/google_api_tool/googleapi_to_openapi_converter.py

@@ -311,7 +311,9 @@ class GoogleApiToOpenApiConverter:
 
       # Determine the actual endpoint path
       # Google often has the format something like 'users.messages.list'
-      rest_path = method_data.get("path", "/")
+      # flatPath is preferred as it provides the actual path, while path
+      # might contain variables like {+projectId}
+      rest_path = method_data.get("flatPath", method_data.get("path", "/"))
       if not rest_path.startswith("/"):
         rest_path = "/" + rest_path
 

google/adk/tools/load_artifacts_tool.py

@@ -89,7 +89,7 @@ class LoadArtifactsTool(BaseTool):
   than the function call.
   """])
 
-    # Attache the content of the artifacts if the model requests them.
+    # Attach the content of the artifacts if the model requests them.
     # This only adds the content to the model request, instead of the session.
     if llm_request.contents and llm_request.contents[-1].parts:
       function_response = llm_request.contents[-1].parts[0].function_response