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

google/adk/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.py

@@ -0,0 +1,231 @@
+# 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
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+
+from fastapi.openapi.models import Operation
+from pydantic import BaseModel
+
+from ....auth.auth_credential import AuthCredential
+from ....auth.auth_schemes import AuthScheme
+from ..common.common import ApiParameter
+from ..common.common import to_snake_case
+from .operation_parser import OperationParser
+
+
+class OperationEndpoint(BaseModel):
+  base_url: str
+  path: str
+  method: str
+
+
+class ParsedOperation(BaseModel):
+  name: str
+  description: str
+  endpoint: OperationEndpoint
+  operation: Operation
+  parameters: List[ApiParameter]
+  return_value: ApiParameter
+  auth_scheme: Optional[AuthScheme] = None
+  auth_credential: Optional[AuthCredential] = None
+  additional_context: Optional[Any] = None
+
+
+class OpenApiSpecParser:
+  """Generates Python code, JSON schema, and callables for an OpenAPI operation.
+
+  This class takes an OpenApiOperation object and provides methods to generate:
+  1. A string representation of a Python function that handles the operation.
+  2. A JSON schema representing the input parameters of the operation.
+  3. A callable Python object (a function) that can execute the operation.
+  """
+
+  def parse(self, openapi_spec_dict: Dict[str, Any]) -> List[ParsedOperation]:
+    """Extracts an OpenAPI spec dict into a list of ParsedOperation objects.
+
+    ParsedOperation objects are further used for generating RestApiTool.
+
+    Args:
+        openapi_spec_dict: A dictionary representing the OpenAPI specification.
+
+    Returns:
+        A list of ParsedOperation objects.
+    """
+
+    openapi_spec_dict = self._resolve_references(openapi_spec_dict)
+    operations = self._collect_operations(openapi_spec_dict)
+    return operations
+
+  def _collect_operations(
+      self, openapi_spec: Dict[str, Any]
+  ) -> List[ParsedOperation]:
+    """Collects operations from an OpenAPI spec."""
+    operations = []
+
+    # Taking first server url, or default to empty string if not present
+    base_url = ""
+    if openapi_spec.get("servers"):
+      base_url = openapi_spec["servers"][0].get("url", "")
+
+    # Get global security scheme (if any)
+    global_scheme_name = None
+    if openapi_spec.get("security"):
+      # Use first scheme by default.
+      scheme_names = list(openapi_spec["security"][0].keys())
+      global_scheme_name = scheme_names[0] if scheme_names else None
+
+    auth_schemes = openapi_spec.get("components", {}).get("securitySchemes", {})
+
+    for path, path_item in openapi_spec.get("paths", {}).items():
+      if path_item is None:
+        continue
+
+      for method in (
+          "get",
+          "post",
+          "put",
+          "delete",
+          "patch",
+          "head",
+          "options",
+          "trace",
+      ):
+        operation_dict = path_item.get(method)
+        if operation_dict is None:
+          continue
+
+        # If operation ID is missing, assign an operation id based on path
+        # and method
+        if "operationId" not in operation_dict:
+          temp_id = to_snake_case(f"{path}_{method}")
+          operation_dict["operationId"] = temp_id
+
+        url = OperationEndpoint(base_url=base_url, path=path, method=method)
+        operation = Operation.model_validate(operation_dict)
+        operation_parser = OperationParser(operation)
+
+        # Check for operation-specific auth scheme
+        auth_scheme_name = operation_parser.get_auth_scheme_name()
+        auth_scheme_name = (
+            auth_scheme_name if auth_scheme_name else global_scheme_name
+        )
+        auth_scheme = (
+            auth_schemes.get(auth_scheme_name) if auth_scheme_name else None
+        )
+
+        parsed_op = ParsedOperation(
+            name=operation_parser.get_function_name(),
+            description=operation.description or operation.summary or "",
+            endpoint=url,
+            operation=operation,
+            parameters=operation_parser.get_parameters(),
+            return_value=operation_parser.get_return_value(),
+            auth_scheme=auth_scheme,
+            auth_credential=None,  # Placeholder
+            additional_context={},
+        )
+        operations.append(parsed_op)
+
+    return operations
+
+  def _resolve_references(self, openapi_spec: Dict[str, Any]) -> Dict[str, Any]:
+    """Recursively resolves all $ref references in an OpenAPI specification.
+
+    Handles circular references correctly.
+
+    Args:
+        openapi_spec: A dictionary representing the OpenAPI specification.
+
+    Returns:
+        A dictionary representing the OpenAPI specification with all references
+        resolved.
+    """
+
+    openapi_spec = copy.deepcopy(openapi_spec)  # Work on a copy
+    resolved_cache = {}  # Cache resolved references
+
+    def resolve_ref(ref_string, current_doc):
+      """Resolves a single $ref string."""
+      parts = ref_string.split("/")
+      if parts[0] != "#":
+        raise ValueError(f"External references not supported: {ref_string}")
+
+      current = current_doc
+      for part in parts[1:]:
+        if part in current:
+          current = current[part]
+        else:
+          return None  # Reference not found
+      return current
+
+    def recursive_resolve(obj, current_doc, seen_refs=None):
+      """Recursively resolves references, handling circularity.
+
+      Args:
+          obj: The object to traverse.
+          current_doc:  Document to search for refs.
+          seen_refs: A set to track already-visited references (for circularity
+            detection).
+
+      Returns:
+          The resolved object.
+      """
+      if seen_refs is None:
+        seen_refs = set()  # Initialize the set if it's the first call
+
+      if isinstance(obj, dict):
+        if "$ref" in obj and isinstance(obj["$ref"], str):
+          ref_string = obj["$ref"]
+
+          # Check for circularity
+          if ref_string in seen_refs and ref_string not in resolved_cache:
+            # Circular reference detected! Return a *copy* of the object,
+            # but *without* the $ref.  This breaks the cycle while
+            # still maintaining the overall structure.
+            return {k: v for k, v in obj.items() if k != "$ref"}
+
+          seen_refs.add(ref_string)  # Add the reference to the set
+
+          # Check if we have a cached resolved value
+          if ref_string in resolved_cache:
+            return copy.deepcopy(resolved_cache[ref_string])
+
+          resolved_value = resolve_ref(ref_string, current_doc)
+          if resolved_value is not None:
+            # Recursively resolve the *resolved* value,
+            # passing along the 'seen_refs' set
+            resolved_value = recursive_resolve(
+                resolved_value, current_doc, seen_refs
+            )
+            resolved_cache[ref_string] = resolved_value
+            return copy.deepcopy(resolved_value)  # return the cached result
+          else:
+            return obj  # return original if no resolved value.
+
+        else:
+          new_dict = {}
+          for key, value in obj.items():
+            new_dict[key] = recursive_resolve(value, current_doc, seen_refs)
+          return new_dict
+
+      elif isinstance(obj, list):
+        return [recursive_resolve(item, current_doc, seen_refs) for item in obj]
+      else:
+        return obj
+
+    return recursive_resolve(openapi_spec, openapi_spec)

google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py

@@ -0,0 +1,144 @@
+# 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 json
+import logging
+from typing import Any
+from typing import Dict
+from typing import Final
+from typing import List
+from typing import Literal
+from typing import Optional
+
+import yaml
+
+from ....auth.auth_credential import AuthCredential
+from ....auth.auth_schemes import AuthScheme
+from .openapi_spec_parser import OpenApiSpecParser
+from .rest_api_tool import RestApiTool
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAPIToolset:
+  """Class for parsing OpenAPI spec into a list of RestApiTool.
+
+  Usage:
+  ```
+    # Initialize OpenAPI toolset from a spec string.
+    openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
+      spec_str_type="json")
+    # Or, initialize OpenAPI toolset from a spec dictionary.
+    openapi_toolset = OpenAPIToolset(spec_dict=openapi_spec_dict)
+
+    # Add all tools to an agent.
+    agent = Agent(
+      tools=[*openapi_toolset.get_tools()]
+    )
+    # Or, add a single tool to an agent.
+    agent = Agent(
+      tools=[openapi_toolset.get_tool('tool_name')]
+    )
+  ```
+  """
+
+  def __init__(
+      self,
+      *,
+      spec_dict: Optional[Dict[str, Any]] = None,
+      spec_str: Optional[str] = None,
+      spec_str_type: Literal["json", "yaml"] = "json",
+      auth_scheme: Optional[AuthScheme] = None,
+      auth_credential: Optional[AuthCredential] = None,
+  ):
+    """Initializes the OpenAPIToolset.
+
+    Usage:
+    ```
+      # Initialize OpenAPI toolset from a spec string.
+      openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
+        spec_str_type="json")
+      # Or, initialize OpenAPI toolset from a spec dictionary.
+      openapi_toolset = OpenAPIToolset(spec_dict=openapi_spec_dict)
+
+      # Add all tools to an agent.
+      agent = Agent(
+        tools=[*openapi_toolset.get_tools()]
+      )
+      # Or, add a single tool to an agent.
+      agent = Agent(
+        tools=[openapi_toolset.get_tool('tool_name')]
+      )
+    ```
+
+    Args:
+      spec_dict: The OpenAPI spec dictionary. If provided, it will be used
+        instead of loading the spec from a string.
+      spec_str: The OpenAPI spec string in JSON or YAML format. It will be used
+        when spec_dict is not provided.
+      spec_str_type: The type of the OpenAPI spec string. Can be "json" or
+        "yaml".
+      auth_scheme: The auth scheme to use for all tools. Use AuthScheme or use
+        helpers in `google.adk.tools.openapi_tool.auth.auth_helpers`
+      auth_credential: The auth credential to use for all tools. Use
+        AuthCredential or use helpers in
+        `google.adk.tools.openapi_tool.auth.auth_helpers`
+    """
+    if not spec_dict:
+      spec_dict = self._load_spec(spec_str, spec_str_type)
+    self.tools: Final[List[RestApiTool]] = list(self._parse(spec_dict))
+    if auth_scheme or auth_credential:
+      self._configure_auth_all(auth_scheme, auth_credential)
+
+  def _configure_auth_all(
+      self, auth_scheme: AuthScheme, auth_credential: AuthCredential
+  ):
+    """Configure auth scheme and credential for all tools."""
+
+    for tool in self.tools:
+      if auth_scheme:
+        tool.configure_auth_scheme(auth_scheme)
+      if auth_credential:
+        tool.configure_auth_credential(auth_credential)
+
+  def get_tools(self) -> List[RestApiTool]:
+    """Get all tools in the toolset."""
+    return self.tools
+
+  def get_tool(self, tool_name: str) -> Optional[RestApiTool]:
+    """Get a tool by name."""
+    matching_tool = filter(lambda t: t.name == tool_name, self.tools)
+    return next(matching_tool, None)
+
+  def _load_spec(
+      self, spec_str: str, spec_type: Literal["json", "yaml"]
+  ) -> Dict[str, Any]:
+    """Loads the OpenAPI spec string into adictionary."""
+    if spec_type == "json":
+      return json.loads(spec_str)
+    elif spec_type == "yaml":
+      return yaml.safe_load(spec_str)
+    else:
+      raise ValueError(f"Unsupported spec type: {spec_type}")
+
+  def _parse(self, openapi_spec_dict: Dict[str, Any]) -> List[RestApiTool]:
+    """Parse OpenAPI spec into a list of RestApiTool."""
+    operations = OpenApiSpecParser().parse(openapi_spec_dict)
+
+    tools = []
+    for o in operations:
+      tool = RestApiTool.from_parsed_operation(o)
+      logger.info("Parsed tool: %s", tool.name)
+      tools.append(tool)
+    return tools

google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py

@@ -0,0 +1,260 @@
+# 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 textwrap import dedent
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.openapi.models import Operation
+from fastapi.openapi.models import Parameter
+from fastapi.openapi.models import Schema
+
+from ..common.common import ApiParameter
+from ..common.common import PydocHelper
+from ..common.common import to_snake_case
+
+
+class OperationParser:
+  """Generates parameters for Python functions from an OpenAPI operation.
+
+  This class processes an OpenApiOperation object and provides helper methods
+  to extract information needed to generate Python function declarations,
+  docstrings, signatures, and JSON schemas.  It handles parameter processing,
+  name deduplication, and type hint generation.
+  """
+
+  def __init__(
+      self, operation: Union[Operation, Dict[str, Any], str], should_parse=True
+  ):
+    """Initializes the OperationParser with an OpenApiOperation.
+
+    Args:
+        operation: The OpenApiOperation object or a dictionary to process.
+        should_parse: Whether to parse the operation during initialization.
+    """
+    if isinstance(operation, dict):
+      self.operation = Operation.model_validate(operation)
+    elif isinstance(operation, str):
+      self.operation = Operation.model_validate_json(operation)
+    else:
+      self.operation = operation
+
+    self.params: List[ApiParameter] = []
+    self.return_value: Optional[ApiParameter] = None
+    if should_parse:
+      self._process_operation_parameters()
+      self._process_request_body()
+      self._process_return_value()
+      self._dedupe_param_names()
+
+  @classmethod
+  def load(
+      cls,
+      operation: Union[Operation, Dict[str, Any]],
+      params: List[ApiParameter],
+      return_value: Optional[ApiParameter] = None,
+  ) -> 'OperationParser':
+    parser = cls(operation, should_parse=False)
+    parser.params = params
+    parser.return_value = return_value
+    return parser
+
+  def _process_operation_parameters(self):
+    """Processes parameters from the OpenAPI operation."""
+    parameters = self.operation.parameters or []
+    for param in parameters:
+      if isinstance(param, Parameter):
+        original_name = param.name
+        description = param.description or ''
+        location = param.in_ or ''
+        schema = param.schema_ or {}  # Use schema_ instead of .schema
+
+        self.params.append(
+            ApiParameter(
+                original_name=original_name,
+                param_location=location,
+                param_schema=schema,
+                description=description,
+            )
+        )
+
+  def _process_request_body(self):
+    """Processes the request body from the OpenAPI operation."""
+    request_body = self.operation.requestBody
+    if not request_body:
+      return
+
+    content = request_body.content or {}
+    if not content:
+      return
+
+    # If request body is an object, expand the properties as parameters
+    for _, media_type_object in content.items():
+      schema = media_type_object.schema_ or {}
+      description = request_body.description or ''
+
+      if schema and schema.type == 'object':
+        for prop_name, prop_details in schema.properties.items():
+          self.params.append(
+              ApiParameter(
+                  original_name=prop_name,
+                  param_location='body',
+                  param_schema=prop_details,
+                  description=prop_details.description,
+              )
+          )
+
+      elif schema and schema.type == 'array':
+        self.params.append(
+            ApiParameter(
+                original_name='array',
+                param_location='body',
+                param_schema=schema,
+                description=description,
+            )
+        )
+      else:
+        self.params.append(
+            # Empty name for unnamed body param
+            ApiParameter(
+                original_name='',
+                param_location='body',
+                param_schema=schema,
+                description=description,
+            )
+        )
+      break  # Process first mime type only
+
+  def _dedupe_param_names(self):
+    """Deduplicates parameter names to avoid conflicts."""
+    params_cnt = {}
+    for param in self.params:
+      name = param.py_name
+      if name not in params_cnt:
+        params_cnt[name] = 0
+      else:
+        params_cnt[name] += 1
+        param.py_name = f'{name}_{params_cnt[name] -1}'
+
+  def _process_return_value(self) -> Parameter:
+    """Returns a Parameter object representing the return type."""
+    responses = self.operation.responses or {}
+    # Default to Any if no 2xx response or if schema is missing
+    return_schema = Schema(type='Any')
+
+    # Take the 20x response with the smallest response code.
+    valid_codes = list(
+        filter(lambda k: k.startswith('2'), list(responses.keys()))
+    )
+    min_20x_status_code = min(valid_codes) if valid_codes else None
+
+    if min_20x_status_code and responses[min_20x_status_code].content:
+      content = responses[min_20x_status_code].content
+      for mime_type in content:
+        if content[mime_type].schema_:
+          return_schema = content[mime_type].schema_
+          break
+
+    self.return_value = ApiParameter(
+        original_name='',
+        param_location='',
+        param_schema=return_schema,
+    )
+
+  def get_function_name(self) -> str:
+    """Returns the generated function name."""
+    operation_id = self.operation.operationId
+    if not operation_id:
+      raise ValueError('Operation ID is missing')
+    return to_snake_case(operation_id)[:60]
+
+  def get_return_type_hint(self) -> str:
+    """Returns the return type hint string (like 'str', 'int', etc.)."""
+    return self.return_value.type_hint
+
+  def get_return_type_value(self) -> Any:
+    """Returns the return type value (like str, int, List[str], etc.)."""
+    return self.return_value.type_value
+
+  def get_parameters(self) -> List[ApiParameter]:
+    """Returns the list of Parameter objects."""
+    return self.params
+
+  def get_return_value(self) -> ApiParameter:
+    """Returns the list of Parameter objects."""
+    return self.return_value
+
+  def get_auth_scheme_name(self) -> str:
+    """Returns the name of the auth scheme for this operation from the spec."""
+    if self.operation.security:
+      scheme_name = list(self.operation.security[0].keys())[0]
+      return scheme_name
+    return ''
+
+  def get_pydoc_string(self) -> str:
+    """Returns the generated PyDoc string."""
+    pydoc_params = [param.to_pydoc_string() for param in self.params]
+    pydoc_description = (
+        self.operation.summary or self.operation.description or ''
+    )
+    pydoc_return = PydocHelper.generate_return_doc(
+        self.operation.responses or {}
+    )
+    pydoc_arg_list = chr(10).join(
+        f'        {param_doc}' for param_doc in pydoc_params
+    )
+    return dedent(f"""
+        \"\"\"{pydoc_description}
+
+        Args:
+        {pydoc_arg_list}
+
+        {pydoc_return}
+        \"\"\"
+            """).strip()
+
+  def get_json_schema(self) -> Dict[str, Any]:
+    """Returns the JSON schema for the function arguments."""
+    properties = {
+        p.py_name: jsonable_encoder(p.param_schema, exclude_none=True)
+        for p in self.params
+    }
+    return {
+        'properties': properties,
+        'required': [p.py_name for p in self.params],
+        'title': f"{self.operation.operationId or 'unnamed'}_Arguments",
+        'type': 'object',
+    }
+
+  def get_signature_parameters(self) -> List[inspect.Parameter]:
+    """Returns a list of inspect.Parameter objects for the function."""
+    return [
+        inspect.Parameter(
+            param.py_name,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=param.type_value,
+        )
+        for param in self.params
+    ]
+
+  def get_annotations(self) -> Dict[str, Any]:
+    """Returns a dictionary of parameter annotations for the function."""
+    annotations = {p.py_name: p.type_value for p in self.params}
+    annotations['return'] = self.get_return_type_value()
+    return annotations