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

google/adk/tools/function_parameter_parse_util.py

@@ -0,0 +1,307 @@
+# Copyright 2024 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 inspect
+import logging
+import types as typing_types
+from typing import _GenericAlias
+from typing import Any
+from typing import get_args
+from typing import get_origin
+from typing import Literal
+from typing import Union
+
+from google.genai import types
+import pydantic
+
+_py_builtin_type_to_schema_type = {
+    str: types.Type.STRING,
+    int: types.Type.INTEGER,
+    float: types.Type.NUMBER,
+    bool: types.Type.BOOLEAN,
+    list: types.Type.ARRAY,
+    dict: types.Type.OBJECT,
+}
+
+logger = logging.getLogger(__name__)
+
+
+def _is_builtin_primitive_or_compound(
+    annotation: inspect.Parameter.annotation,
+) -> bool:
+  return annotation in _py_builtin_type_to_schema_type.keys()
+
+
+def _raise_for_any_of_if_mldev(schema: types.Schema):
+  if schema.any_of:
+    raise ValueError(
+        'AnyOf is not supported in function declaration schema for Google AI.'
+    )
+
+
+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.
+    schema.default = None
+    logger.warning(
+        'Default value is not supported in function declaration schema for'
+        ' Google AI.'
+    )
+
+
+def _raise_if_schema_unsupported(variant: str, schema: types.Schema):
+  if not variant == 'VERTEX_AI':
+    _raise_for_any_of_if_mldev(schema)
+    _update_for_default_if_mldev(schema)
+
+
+def _is_default_value_compatible(
+    default_value: Any, annotation: inspect.Parameter.annotation
+) -> bool:
+  # None type is expected to be handled external to this function
+  if _is_builtin_primitive_or_compound(annotation):
+    return isinstance(default_value, annotation)
+
+  if (
+      isinstance(annotation, _GenericAlias)
+      or isinstance(annotation, typing_types.GenericAlias)
+      or isinstance(annotation, typing_types.UnionType)
+  ):
+    origin = get_origin(annotation)
+    if origin in (Union, typing_types.UnionType):
+      return any(
+          _is_default_value_compatible(default_value, arg)
+          for arg in get_args(annotation)
+      )
+
+    if origin is dict:
+      return isinstance(default_value, dict)
+
+    if origin is list:
+      if not isinstance(default_value, list):
+        return False
+      # most tricky case, element in list is union type
+      # need to apply any logic within all
+      # see test case test_generic_alias_complex_array_with_default_value
+      # a: typing.List[int | str | float | bool]
+      # default_value: [1, 'a', 1.1, True]
+      return all(
+          any(
+              _is_default_value_compatible(item, arg)
+              for arg in get_args(annotation)
+          )
+          for item in default_value
+      )
+
+    if origin is Literal:
+      return default_value in get_args(annotation)
+
+  # return False for any other unrecognized annotation
+  # let caller handle the raise
+  return False
+
+
+def _parse_schema_from_parameter(
+    variant: str, param: inspect.Parameter, func_name: str
+) -> types.Schema:
+  """parse schema from parameter.
+
+  from the simplest case to the most complex case.
+  """
+  schema = types.Schema()
+  default_value_error_msg = (
+      f'Default value {param.default} of parameter {param} of function'
+      f' {func_name} is not compatible with the parameter annotation'
+      f' {param.annotation}.'
+  )
+  if _is_builtin_primitive_or_compound(param.annotation):
+    if param.default is not inspect.Parameter.empty:
+      if not _is_default_value_compatible(param.default, param.annotation):
+        raise ValueError(default_value_error_msg)
+      schema.default = param.default
+    schema.type = _py_builtin_type_to_schema_type[param.annotation]
+    _raise_if_schema_unsupported(variant, schema)
+    return schema
+  if (
+      get_origin(param.annotation) is Union
+      # only parse simple UnionType, example int | str | float | bool
+      # complex types.UnionType will be invoked in raise branch
+      and all(
+          (_is_builtin_primitive_or_compound(arg) or arg is type(None))
+          for arg in get_args(param.annotation)
+      )
+  ):
+    schema.type = types.Type.OBJECT
+    schema.any_of = []
+    unique_types = set()
+    for arg in get_args(param.annotation):
+      if arg.__name__ == 'NoneType':  # Optional type
+        schema.nullable = True
+        continue
+      schema_in_any_of = _parse_schema_from_parameter(
+          variant,
+          inspect.Parameter(
+              'item', inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=arg
+          ),
+          func_name,
+      )
+      if (
+          schema_in_any_of.model_dump_json(exclude_none=True)
+          not in unique_types
+      ):
+        schema.any_of.append(schema_in_any_of)
+        unique_types.add(schema_in_any_of.model_dump_json(exclude_none=True))
+    if len(schema.any_of) == 1:  # param: list | None -> Array
+      schema.type = schema.any_of[0].type
+      schema.any_of = None
+    if (
+        param.default is not inspect.Parameter.empty
+        and param.default is not None
+    ):
+      if not _is_default_value_compatible(param.default, param.annotation):
+        raise ValueError(default_value_error_msg)
+      schema.default = param.default
+    _raise_if_schema_unsupported(variant, schema)
+    return schema
+  if isinstance(param.annotation, _GenericAlias) or isinstance(
+      param.annotation, typing_types.GenericAlias
+  ):
+    origin = get_origin(param.annotation)
+    args = get_args(param.annotation)
+    if origin is dict:
+      schema.type = types.Type.OBJECT
+      if param.default is not inspect.Parameter.empty:
+        if not _is_default_value_compatible(param.default, param.annotation):
+          raise ValueError(default_value_error_msg)
+        schema.default = param.default
+      _raise_if_schema_unsupported(variant, schema)
+      return schema
+    if origin is Literal:
+      if not all(isinstance(arg, str) for arg in args):
+        raise ValueError(
+            f'Literal type {param.annotation} must be a list of strings.'
+        )
+      schema.type = types.Type.STRING
+      schema.enum = list(args)
+      if param.default is not inspect.Parameter.empty:
+        if not _is_default_value_compatible(param.default, param.annotation):
+          raise ValueError(default_value_error_msg)
+        schema.default = param.default
+      _raise_if_schema_unsupported(variant, schema)
+      return schema
+    if origin is list:
+      schema.type = types.Type.ARRAY
+      schema.items = _parse_schema_from_parameter(
+          variant,
+          inspect.Parameter(
+              'item',
+              inspect.Parameter.POSITIONAL_OR_KEYWORD,
+              annotation=args[0],
+          ),
+          func_name,
+      )
+      if param.default is not inspect.Parameter.empty:
+        if not _is_default_value_compatible(param.default, param.annotation):
+          raise ValueError(default_value_error_msg)
+        schema.default = param.default
+      _raise_if_schema_unsupported(variant, schema)
+      return schema
+    if origin is Union:
+      schema.any_of = []
+      schema.type = types.Type.OBJECT
+      unique_types = set()
+      for arg in args:
+        if arg.__name__ == 'NoneType':  # Optional type
+          schema.nullable = True
+          continue
+        schema_in_any_of = _parse_schema_from_parameter(
+            variant,
+            inspect.Parameter(
+                'item',
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=arg,
+            ),
+            func_name,
+        )
+        if (
+            len(param.annotation.__args__) == 2
+            and type(None) in param.annotation.__args__
+        ):  # Optional type
+          for optional_arg in param.annotation.__args__:
+            if (
+                hasattr(optional_arg, '__origin__')
+                and optional_arg.__origin__ is list
+            ):
+              # Optional type with list, for example Optional[list[str]]
+              schema.items = schema_in_any_of.items
+        if (
+            schema_in_any_of.model_dump_json(exclude_none=True)
+            not in unique_types
+        ):
+          schema.any_of.append(schema_in_any_of)
+          unique_types.add(schema_in_any_of.model_dump_json(exclude_none=True))
+      if len(schema.any_of) == 1:  # param: Union[List, None] -> Array
+        schema.type = schema.any_of[0].type
+        schema.any_of = None
+      if (
+          param.default is not None
+          and param.default is not inspect.Parameter.empty
+      ):
+        if not _is_default_value_compatible(param.default, param.annotation):
+          raise ValueError(default_value_error_msg)
+        schema.default = param.default
+      _raise_if_schema_unsupported(variant, schema)
+      return schema
+      # all other generic alias will be invoked in raise branch
+  if (
+      inspect.isclass(param.annotation)
+      # for user defined class, we only support pydantic model
+      and issubclass(param.annotation, pydantic.BaseModel)
+  ):
+    if (
+        param.default is not inspect.Parameter.empty
+        and param.default is not None
+    ):
+      schema.default = param.default
+    schema.type = types.Type.OBJECT
+    schema.properties = {}
+    for field_name, field_info in param.annotation.model_fields.items():
+      schema.properties[field_name] = _parse_schema_from_parameter(
+          variant,
+          inspect.Parameter(
+              field_name,
+              inspect.Parameter.POSITIONAL_OR_KEYWORD,
+              annotation=field_info.annotation,
+          ),
+          func_name,
+      )
+    _raise_if_schema_unsupported(variant, schema)
+    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'
+      ' simpler function signature schema,consider manually parse your'
+      f' function declaration for function {func_name}.'
+  )
+
+
+def _get_required_fields(schema: types.Schema) -> list[str]:
+  if not schema.properties:
+    return
+  return [
+      field_name
+      for field_name, field_schema in schema.properties.items()
+      if not field_schema.nullable and field_schema.default is None
+  ]

google/adk/tools/function_tool.py

@@ -0,0 +1,87 @@
+# 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 inspect
+from typing import Any
+from typing import Callable
+from typing import Optional
+
+from google.genai import types
+from typing_extensions import override
+
+from ._automatic_function_calling_util import build_function_declaration
+from .base_tool import BaseTool
+from .tool_context import ToolContext
+
+
+class FunctionTool(BaseTool):
+  """A tool that wraps a user-defined Python function.
+
+  Attributes:
+    func: The function to wrap.
+  """
+
+  def __init__(self, func: Callable[..., Any]):
+    super().__init__(name=func.__name__, description=func.__doc__)
+    self.func = func
+
+  @override
+  def _get_declaration(self) -> Optional[types.FunctionDeclaration]:
+    function_decl = types.FunctionDeclaration.model_validate(
+        build_function_declaration(
+            func=self.func,
+            # The model doesn't understand the function context.
+            # input_stream is for streaming tool
+            ignore_params=['tool_context', 'input_stream'],
+            variant=self._api_variant,
+        )
+    )
+
+    return function_decl
+
+  @override
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: ToolContext
+  ) -> Any:
+    args_to_call = args.copy()
+    signature = inspect.signature(self.func)
+    if 'tool_context' in signature.parameters:
+      args_to_call['tool_context'] = tool_context
+
+    if inspect.iscoroutinefunction(self.func):
+      return await self.func(**args_to_call) or {}
+    else:
+      return self.func(**args_to_call) or {}
+
+  # TODO(hangfei): fix call live for function stream.
+  async def _call_live(
+      self,
+      *,
+      args: dict[str, Any],
+      tool_context: ToolContext,
+      invocation_context,
+  ) -> Any:
+    args_to_call = args.copy()
+    signature = inspect.signature(self.func)
+    if (
+        self.name in invocation_context.active_streaming_tools
+        and invocation_context.active_streaming_tools[self.name].stream
+    ):
+      args_to_call['input_stream'] = invocation_context.active_streaming_tools[
+          self.name
+      ].stream
+    if 'tool_context' in signature.parameters:
+      args_to_call['tool_context'] = tool_context
+    async for item in self.func(**args_to_call):
+      yield item

google/adk/tools/get_user_choice_tool.py

@@ -0,0 +1,28 @@
+# 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 Optional
+from .long_running_tool import LongRunningFunctionTool
+from .tool_context import ToolContext
+
+
+def get_user_choice(
+    options: list[str], tool_context: ToolContext
+) -> Optional[str]:
+  """Provides the options to the user and asks them to choose one."""
+  tool_context.actions.skip_summarization = True
+  return None
+
+
+get_user_choice_tool = LongRunningFunctionTool(func=get_user_choice)

google/adk/tools/google_api_tool/__init__.py

@@ -0,0 +1,14 @@
+# 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 .google_api_tool_sets import calendar_tool_set

google/adk/tools/google_api_tool/google_api_tool.py

@@ -0,0 +1,59 @@
+# 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 typing import Dict
+from typing import Optional
+
+from google.genai.types import FunctionDeclaration
+from typing_extensions import override
+
+from ...auth import AuthCredential
+from ...auth import AuthCredentialTypes
+from ...auth import OAuth2Auth
+from .. import BaseTool
+from ..openapi_tool import RestApiTool
+from ..tool_context import ToolContext
+
+
+class GoogleApiTool(BaseTool):
+
+  def __init__(self, rest_api_tool: RestApiTool):
+    super().__init__(
+        name=rest_api_tool.name,
+        description=rest_api_tool.description,
+        is_long_running=rest_api_tool.is_long_running,
+    )
+    self.rest_api_tool = rest_api_tool
+
+  @override
+  def _get_declaration(self) -> FunctionDeclaration:
+    return self.rest_api_tool._get_declaration()
+
+  @override
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: Optional[ToolContext]
+  ) -> Dict[str, Any]:
+    return await self.rest_api_tool.run_async(
+        args=args, tool_context=tool_context
+    )
+
+  def configure_auth(self, client_id: str, client_secret: str):
+    self.rest_api_tool.auth_credential = AuthCredential(
+        auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
+        oauth2=OAuth2Auth(
+            client_id=client_id,
+            client_secret=client_secret,
+        ),
+    )

google/adk/tools/google_api_tool/google_api_tool_set.py

@@ -0,0 +1,107 @@
+# 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 inspect
+import os
+from typing import Any
+from typing import Dict
+from typing import Final
+from typing import List
+from typing import Optional
+from typing import Type
+
+from ...auth import OpenIdConnectWithConfig
+from ..openapi_tool import OpenAPIToolset
+from ..openapi_tool import RestApiTool
+from .google_api_tool import GoogleApiTool
+from .googleapi_to_openapi_converter import GoogleApiToOpenApiConverter
+
+
+class GoogleApiToolSet:
+
+  def __init__(self, tools: List[RestApiTool]):
+    self.tools: Final[List[GoogleApiTool]] = [
+        GoogleApiTool(tool) for tool in tools
+    ]
+
+  def get_tools(self) -> List[GoogleApiTool]:
+    """Get all tools in the toolset."""
+    return self.tools
+
+  def get_tool(self, tool_name: str) -> Optional[GoogleApiTool]:
+    """Get a tool by name."""
+    matching_tool = filter(lambda t: t.name == tool_name, self.tools)
+    return next(matching_tool, None)
+
+  @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_str = None
+    if spec_file:
+      # Get the frame of the caller
+      caller_frame = inspect.stack()[1]
+      # Get the filename of the caller
+      caller_filename = caller_frame.filename
+      # Get the directory of the caller
+      caller_dir = os.path.dirname(os.path.abspath(caller_filename))
+      # Join the directory path with the filename
+      yaml_path = os.path.join(caller_dir, spec_file)
+      with open(yaml_path, 'r', encoding='utf-8') as file:
+        spec_str = file.read()
+    tool_set = OpenAPIToolset(
+        spec_dict=spec_dict,
+        spec_str=spec_str,
+        spec_str_type='yaml',
+        auth_scheme=OpenIdConnectWithConfig(
+            authorization_endpoint=(
+                'https://accounts.google.com/o/oauth2/v2/auth'
+            ),
+            token_endpoint='https://oauth2.googleapis.com/token',
+            userinfo_endpoint=(
+                'https://openidconnect.googleapis.com/v1/userinfo'
+            ),
+            revocation_endpoint='https://oauth2.googleapis.com/revoke',
+            token_endpoint_auth_methods_supported=[
+                'client_secret_post',
+                'client_secret_basic',
+            ],
+            grant_types_supported=['authorization_code'],
+            scopes=scopes,
+        ),
+    )
+    return tool_set
+
+  def configure_auth(self, client_id: str, client_secret: str):
+    for tool in self.tools:
+      tool.configure_auth(client_id, client_secret)
+
+  @classmethod
+  def load_tool_set(
+      cl: Type['GoogleApiToolSet'],
+      api_name: str,
+      api_version: str,
+  ) -> '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(
+            spec_dict=spec_dict, scopes=[scope]
+        ).get_tools()
+    )

google/adk/tools/google_api_tool/google_api_tool_sets.py

@@ -0,0 +1,55 @@
+# 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
+
+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",
+)