oci 2.151.0__py3-none-any.whl → 2.152.1__py3-none-any.whl

oci/addons/adk/tool/toolkit.py

@@ -0,0 +1,189 @@
+# coding: utf-8
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.  All rights reserved.
+# This software is dual-licensed to you under the Universal Permissive License (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose either license.
+
+import inspect
+import json
+from types import MethodType
+from typing import Any, Callable, Dict, List
+
+from pydantic import BaseModel, Field
+
+from oci.addons.adk.logger import default_logger as logger
+from oci.addons.adk.tool import FunctionTool
+
+
+class Toolkit(BaseModel):
+    """A base class where subclass can declare a collection
+    of tools related to a specific task."""
+
+    name: str
+
+    functions: Dict[str, FunctionTool] = Field(default_factory=dict)
+    openai_tools_file: str = ""
+
+    def __init__(self, name: str = "toolkit", openai_tools_file: str = ""):
+        """Initialize a new Toolkit.
+
+        Args:
+            name:
+                A descriptive name for the toolkit
+            openai_tools_file:
+                Optional JSON containing the function definition
+                per OpenAI Responses API function tool format
+        """
+        super().__init__(name=name, functions={}, openai_tools_file=openai_tools_file)
+
+        # Load OpenAI tool definitions if specified
+        openai_tools_json = {}
+        if openai_tools_file != "":
+            try:
+                with open(openai_tools_file, "r", encoding="utf-8") as f:
+                    openai_tools_json = json.load(f)
+
+                # check it's a JSON object that contains a "tools" key
+                if "tools" not in openai_tools_json:
+                    raise ValueError("OpenAI tools file must contain a 'tools' key")
+
+                # check the "tools" key is a list
+                if not isinstance(openai_tools_json["tools"], list):
+                    raise ValueError(
+                        "OpenAI tools file must contain a 'tools' key that is a list"
+                    )
+
+                # check each item in the list is a JSON object that contains key "type"
+                for tool in openai_tools_json["tools"]:
+                    if "type" not in tool:
+                        raise ValueError(
+                            "OpenAI tools file must contain a 'type' key for each tool"
+                        )
+
+                    # check the "type" key is "function"
+                    if tool["type"] != "function":
+                        raise ValueError(
+                            "OpenAI tools file must contain a 'type' key "
+                            "for each tool that is 'function'"
+                        )
+
+                # get the number of tools
+                num_tools = len(openai_tools_json["tools"])
+                logger.debug(
+                    f"[green]Success:[/green] Loaded {num_tools} "
+                    f"OpenAI tools from {openai_tools_file}"
+                )
+            except Exception as e:
+                logger.debug(
+                    f"[yellow]Warning:[/yellow] Failed to load OpenAI tools "
+                    f"from {openai_tools_file}: {e}"
+                )
+
+        # Auto-register methods marked with @tool decorator
+        for attr_name in dir(self):
+            # skip private methods
+            if attr_name.startswith("__"):
+                continue
+
+            if attr_name.startswith("model_"):
+                continue
+
+            attr = getattr(self, attr_name)
+
+            # skip non-callable attributes
+            if not callable(attr):
+                continue
+
+            # skip non-tool attributes
+            if not getattr(attr, "_is_tool", False):
+                continue
+
+            # skip not method attributes
+            if not isinstance(attr, MethodType):
+                continue
+
+            # Ensure method first argument is self
+            original_func = attr.__func__
+            sig = inspect.signature(original_func)
+            params = list(sig.parameters.values())
+            if len(params) == 0 or params[0].name != "self":
+                raise ValueError(
+                    f"@Tool decorated method {attr_name} of {self.__class__.__name__} "
+                    "must have a first argument of self"
+                )
+
+            matching_openai_tool = None
+            if openai_tools_json:
+                # Find the matching OpenAI tool def with the same name as the method
+                openai_tool_list = openai_tools_json["tools"]
+                matching_openai_tool = next(
+                    (
+                        tool
+                        for tool in openai_tool_list
+                        if tool.get("name") == attr_name and tool.get("type") == "function"
+                    ),
+                    None,
+                )
+
+            if matching_openai_tool:
+                # Create FunctionTool from OpenAI definition
+                self._add_function_tool_from_openai(attr, matching_openai_tool)
+            else:
+                # Create FunctionTool from method decoration
+                self._add_function_tool(attr)
+
+    def get_registered_tools(self) -> List[FunctionTool]:
+        """Return a list of all registered tools in the toolkit."""
+        return list(self.functions.values())
+
+    def print_arguments_received(self) -> None:
+        """Print the arguments received by the tool."""
+        # Get the frame of the calling function
+        caller_frame = inspect.currentframe()
+        if caller_frame is None:
+            logger.info("Could not get caller frame")
+            return
+
+        caller_frame = caller_frame.f_back
+        if caller_frame is None:
+            logger.info("Could not get caller's parent frame")
+            return
+
+        # Get all arguments of the calling function
+        args_info = inspect.getargvalues(caller_frame)
+        # Create a dictionary of arguments (excluding 'self')
+        args = {arg: args_info.locals[arg] for arg in args_info.args if arg != "self"}
+        logger.info(
+            f"Executing mock function implementation with received arguments: {args}"
+        )
+
+    def _add_function_tool(self, callable: Callable[..., Any]) -> None:
+        """Internal method to add a function as a tool to the toolkit.
+
+        Args:
+            callable: The callable to add as a tool
+        """
+        try:
+            f = FunctionTool.from_callable(callable)
+            self.functions[f.name] = f
+        except Exception as e:
+            raise e
+
+    def _add_function_tool_from_openai(
+        self, callable: Callable[..., Any], openai_tool: Dict[str, Any]
+    ) -> None:
+        """Internal method to add a function as a tool using OpenAI tool definition.
+
+        Args:
+            callable: The callable to add as a tool
+            openai_tool: The OpenAI tool definition
+        """
+        try:
+            f = FunctionTool.from_callable_openai_tool(callable, openai_tool)
+            self.functions[f.name] = f
+        except Exception as e:
+            raise e
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} name={self.name} functions={list(self.functions.keys())}>"  # noqa: E501
+
+    def __str__(self):
+        return self.__repr__()

oci/addons/adk/tool/utils.py

@@ -0,0 +1,120 @@
+# coding: utf-8
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.  All rights reserved.
+# This software is dual-licensed to you under the Universal Permissive License (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose either license.
+
+from typing import Dict, Any, List, TypeVar
+
+from oci.addons.adk.tool.function_tool import FunctionTool
+from oci.addons.adk.tool.prebuilt.agentic_rag_tool import AgenticRagTool
+from oci.addons.adk.logger import default_logger as logger
+from oci.addons.adk.util import build_custom_function_params
+
+
+def diff_local_and_remote_tool(
+    local_tool: FunctionTool | AgenticRagTool,
+    remote_tool: Dict[str, Any],
+) -> bool:
+    """
+    Return true if the local tool and the remote tool are different.
+
+    Args:
+        local_tool: The local tool
+        remote_tool: The remote tool
+
+    Returns:
+        True if the local tool and the remote tool are different, False otherwise
+    """
+    local_tool_json_spec: Dict[str, Any] = {}
+    remote_tool_json_spec: Dict[str, Any] = {}
+
+    if isinstance(local_tool, FunctionTool):
+        local_tool_json_spec = {
+            "tool_name": local_tool.name,
+            "tool_description": local_tool.description,
+            "name": local_tool.name,
+            "description": local_tool.description,
+            "parameters": build_custom_function_params(local_tool.parameters),
+        }
+
+        remote_tool_json_spec = {
+            "tool_name": remote_tool.get("display_name", ""),
+            "tool_description": remote_tool.get("description", ""),
+            **remote_tool["tool_config"]["function"],
+        }
+
+    elif isinstance(local_tool, AgenticRagTool):
+        local_tool_json_spec = {
+            "name": local_tool.name,
+            "description": local_tool.description,
+            "knowledge_base_ids": sorted(local_tool.knowledge_base_ids),
+        }
+        remote_tool_json_spec = {
+            "name": remote_tool.get("display_name", ""),
+            "description": remote_tool.get("description", ""),
+            "knowledge_base_ids": sorted(
+                [
+                    kb_config.get("knowledge_base_id")
+                    for kb_config in remote_tool.get("tool_config", {}).get(
+                        "knowledge_base_configs", []
+                    )
+                ]
+            )
+        }
+
+    logger.debug(f"Local tool JSON spec: {local_tool_json_spec}")
+    logger.debug(f"Remote tool JSON spec: {remote_tool_json_spec}")
+
+    return local_tool_json_spec != remote_tool_json_spec
+
+
+def compare_local_and_remote_tools(
+    local_tools: List[FunctionTool] | List[AgenticRagTool],
+    remote_tools: List[Dict[str, Any]],
+) -> bool:
+    """
+    Return true if the local tools and the remote tools are the same.
+
+    Args:
+        local_tools: The local tools
+        remote_tools: The remote tools
+
+    Returns:
+        True if the all local tools and the remote tools are the same, False otherwise
+    """
+    same_list: List[bool] = []
+    # different number of tools
+    if len(local_tools) != len(remote_tools):
+        return False
+    for local_tool in local_tools:
+        # any remote tool is the same with local tool
+        same_list.append(
+            any(
+                not diff_local_and_remote_tool(local_tool, remote_tool)
+                for remote_tool in remote_tools
+            )
+        )
+    # all local tools are the same with remote tools
+    return all(same_list)
+
+
+T = TypeVar('T')
+
+
+def dedupe_tools_list(
+    tools_list: List[T],
+) -> List[T]:
+    """
+    Return a list of unique tools.
+
+    Args:
+        tools_list: The tools list of any type
+
+    Returns:
+        A list of unique tools of the same type as input
+    """
+    result_tools_list: List[T] = []
+    for tool in tools_list:
+        if any(tool == exist_tool for exist_tool in result_tools_list):
+            continue
+        result_tools_list.append(tool)
+    return result_tools_list

oci/addons/adk/util.py

@@ -0,0 +1,325 @@
+# coding: utf-8
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.  All rights reserved.
+# This software is dual-licensed to you under the Universal Permissive License (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl or Apache License 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose either license.
+
+import inspect
+import json
+from types import NoneType
+from typing import Any, Callable, Dict, Optional, Tuple, Union, get_args, get_origin
+
+from docstring_parser import parse
+from oci import regions
+
+
+class DocstringParser:
+    """Utility class for parsing and extracting information from docstrings."""
+
+    @staticmethod
+    def get_callable_description(callable_func: Callable) -> str:
+        """
+        Extract a description from a callable's docstring.
+
+        Args:
+            callable_func: The function or method to extract description from
+
+        Returns:
+            A string containing the combined short and long descriptions
+        """
+        doc = inspect.getdoc(callable_func)
+        if not doc:
+            return ""
+
+        parsed = parse(doc)
+
+        # Combine short and long descriptions
+        result = ""
+        if parsed.short_description:
+            result = parsed.short_description
+        if parsed.long_description:
+            # Preserve the double newline between short and long descriptions
+            if result:
+                result += "\n\n"
+            result += parsed.long_description
+
+        return result
+
+
+class JsonSchemaGenerator:
+    """Utility class for generating JSON schemas from Python type annotations."""
+
+    # Constants for type mapping
+    JSON_TYPE_MAPPING = {
+        "int": "number",
+        "float": "number",
+        "complex": "number",
+        "Decimal": "number",
+        "str": "string",
+        "string": "string",
+        "bool": "boolean",
+        "boolean": "boolean",
+        "NoneType": "null",
+        "None": "null",
+        "list": "array",
+        "tuple": "array",
+        "set": "array",
+        "frozenset": "array",
+        "dict": "object",
+        "mapping": "object",
+    }
+
+    # Collection types that should be treated as arrays
+    ARRAY_TYPES = (list, tuple, set, frozenset)
+
+    @classmethod
+    def get_json_type_for_py_type(cls, arg_type: str) -> str:
+        """
+        Get the JSON schema type for a given Python type.
+
+        Args:
+            arg_type: The Python type name to convert
+
+        Returns:
+            The corresponding JSON schema type
+        """
+        return cls.JSON_TYPE_MAPPING.get(arg_type, "object")
+
+    @classmethod
+    def get_json_schema_for_arg(cls, t: Any) -> Optional[Dict[str, Any]]:
+        """
+        Generate a JSON schema for a given type annotation.
+
+        Args:
+            t: The type annotation to convert to JSON schema
+
+        Returns:
+            A dictionary representing the JSON schema for the type
+        """
+        type_args = get_args(t)
+        type_origin = get_origin(t)
+
+        if type_origin is not None:
+            if type_origin in cls.ARRAY_TYPES:
+                return cls._handle_array_type(type_args)
+            elif type_origin is dict:
+                return cls._handle_dict_type(type_args)
+            elif type_origin is Union:
+                return cls._handle_union_type(type_args)
+
+        return {"type": cls.get_json_type_for_py_type(t.__name__)}
+
+    @classmethod
+    def _handle_array_type(cls, type_args: Tuple) -> Dict[str, Any]:
+        """Helper method to handle array-like types"""
+        json_schema_for_items = (
+            cls.get_json_schema_for_arg(type_args[0])
+            if type_args
+            else {"type": "string"}
+        )
+        return {"type": "array", "items": json_schema_for_items}
+
+    @classmethod
+    def _handle_dict_type(cls, type_args: Tuple) -> Dict[str, Any]:
+        """Helper method to handle dictionary types"""
+        key_schema = (
+            cls.get_json_schema_for_arg(type_args[0])
+            if type_args
+            else {"type": "string"}
+        )
+        value_schema = (
+            cls.get_json_schema_for_arg(type_args[1])
+            if len(type_args) > 1
+            else {"type": "string"}
+        )
+        return {
+            "type": "object",
+            "propertyNames": key_schema,
+            "additionalProperties": value_schema,
+        }
+
+    @classmethod
+    def _handle_union_type(cls, type_args: Tuple) -> Optional[Dict[str, Any]]:
+        """Helper method to handle Union types"""
+        types = []
+        for arg in type_args:
+            if arg is not NoneType:
+                try:
+                    schema = cls.get_json_schema_for_arg(arg)
+                    if schema:
+                        types.append(schema)
+                except Exception:
+                    continue
+        return {"anyOf": types} if types else None
+
+    @staticmethod
+    def is_optional_type(v: Any) -> Tuple[bool, Any]:
+        """
+        Check if a type is Optional (Union with NoneType) and extract the actual type.
+
+        Args:
+            v: The type to check
+
+        Returns:
+            A tuple of (is_optional, actual_type)
+        """
+        type_origin = get_origin(v)
+        type_args = get_args(v)
+        is_optional = (
+            type_origin is Union and
+            len(type_args) == 2 and
+            any(arg is NoneType for arg in type_args)
+        )
+
+        if is_optional:
+            actual_type = next(arg for arg in type_args if arg is not NoneType)
+            return True, actual_type
+
+        return False, v
+
+    @classmethod
+    def get_json_schema(
+        cls,
+        type_hints: Dict[str, Any],
+        param_descriptions: Optional[Dict[str, str]] = None,
+        strict: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Generate a JSON schema from type hints and parameter descriptions.
+
+        Args:
+            type_hints: Dictionary of parameter names to their type annotations
+            param_descriptions: Optional dictionary of parameter descriptions
+            strict: Whether to disallow additional properties
+
+        Returns:
+            A JSON schema object
+        """
+        json_schema: Dict[str, Any] = {
+            "type": "object",
+            "properties": {},
+        }
+        if strict:
+            json_schema["additionalProperties"] = False
+
+        for k, v in type_hints.items():
+            if k == "return":
+                continue
+
+            try:
+                is_optional, actual_type = cls.is_optional_type(v)
+
+                # Handle cases with no type hint
+                if actual_type:
+                    arg_json_schema = cls.get_json_schema_for_arg(actual_type)
+                else:
+                    arg_json_schema = {}
+
+                if arg_json_schema is not None:
+                    if is_optional:
+                        # Handle null type for optional fields
+                        if isinstance(arg_json_schema.get("type"), list):
+                            arg_json_schema["type"].append("null")
+                        else:
+                            arg_json_schema["type"] = [arg_json_schema["type"], "null"]
+
+                    # Add description
+                    if (
+                        param_descriptions and
+                        k in param_descriptions and
+                        param_descriptions[k]
+                    ):
+                        arg_json_schema["description"] = param_descriptions[k]
+
+                    json_schema["properties"][k] = arg_json_schema
+            except Exception:
+                continue
+
+        return json_schema
+
+
+# Maintain backward compatibility with the original function names
+def get_callable_description(callable_func: Callable) -> str:
+    return DocstringParser.get_callable_description(callable_func)
+
+
+def get_json_type_for_py_type(arg_type: str) -> str:
+    return JsonSchemaGenerator.get_json_type_for_py_type(arg_type)
+
+
+def get_json_schema_for_arg(t: Any) -> Optional[Dict[str, Any]]:
+    return JsonSchemaGenerator.get_json_schema_for_arg(t)
+
+
+def get_json_schema(
+    type_hints: Dict[str, Any],
+    param_descriptions: Optional[Dict[str, str]] = None,
+    strict: bool = False,
+) -> Dict[str, Any]:
+    return JsonSchemaGenerator.get_json_schema(type_hints, param_descriptions, strict)
+
+
+def build_custom_function_params(func_params: Dict[str, Any]) -> Dict[str, str]:
+    """
+    Build a dictionary of function parameters for customizing a function.
+    This function ensures that all values are json serialized
+    which is required for current OCI Agent function calls API.
+
+    Args:
+        func_params: Dictionary of function parameters to customize
+
+    Returns:
+        A dictionary of parameters with string values
+    """
+    new_func_params = {}
+    for k, v in func_params.items():
+        if isinstance(v, str):
+            new_func_params[k] = v
+        elif isinstance(v, dict):
+            new_func_params[k] = json.dumps(v)
+        elif isinstance(v, list):
+            new_func_params[k] = json.dumps(v)
+        else:
+            new_func_params[k] = str(v)
+    return new_func_params
+
+
+def read_custom_function_params(func_params: Dict[str, str]) -> Dict[str, Any]:
+    """
+    Read a dictionary of function parameters from a dictionary of string values.
+
+    Args:
+        func_params: Dictionary of function parameters with string values
+
+    Returns:
+        A dictionary of parameters with their original types
+    """
+    new_func_params = {}
+    for k, v in func_params.items():
+        if isinstance(v, dict):
+            new_func_params[k] = json.loads(v)
+        else:
+            new_func_params[k] = v
+    return new_func_params
+
+
+def get_region_endpoint(
+    region: str, endpoint: str, service: str = "generativeai"
+) -> str:
+    """
+    Get the endpoint for a given region and service.
+
+    Args:
+        region: The region to use, e.g. "FRA" or "us-chicago-1"
+        endpoint: The endpoint to use, e.g. "agent" or "agent-runtime"
+        service: The service to use, default "generativeai"
+
+    Returns:
+        The endpoint for the given region and service
+    """
+    service_endpoint_template = (
+        f"https://{endpoint}.{service}" + ".{region}.oci.{secondLevelDomain}"
+    )
+    return regions.endpoint_for(
+        service=service,
+        region=region,
+        service_endpoint_template=service_endpoint_template,
+    )