Source code for calute.types.tool_calls

# Copyright 2025 The EasyDeL/Calute Author @erfanzar (Erfan Zare Chavoshi).
#
# 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
#
#     https://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.


"""Tool and function call type definitions for Calute.

This module defines the core data structures for representing tools
and function calls in the Calute framework. It provides:
- Function definitions with JSON Schema parameters
- Tool wrappers for functions
- Tool choice options for controlling tool selection
- Function call representations for LLM outputs
- Tool call structures with unique identifiers

The types are designed to be compatible with OpenAI's function calling
API format while providing additional validation and type safety through
Pydantic models.

Example:
    >>> from calute.types.tool_calls import Tool, Function, ToolCall, FunctionCall
    >>> tool = Tool(
    ...     function=Function(
    ...         name="get_weather",
    ...         description="Get weather for a location",
    ...         parameters={"type": "object", "properties": {"location": {"type": "string"}}}
    ...     )
    ... )
    >>> tool_call = ToolCall(
    ...     id="call_123",
    ...     function=FunctionCall(name="get_weather", arguments='{"location": "NYC"}')
    ... )
"""

import json
from enum import StrEnum
from typing import Any, TypeVar

from pydantic import field_validator

from ..core.utils import CaluteBase


class Function(CaluteBase):
    r"""Function definition for tools.

    Attributes:
        name: The name of the function.
        description: A description of what the function does.
        parameters: The parameters the functions accepts, described as a JSON Schema object.

    Examples:
        >>> function = Function(
        ...     name="get_current_weather",
        ...     description="Get the current weather in a given location",
        ...     parameters={
        ...         "type": "object",
        ...         "properties": {
        ...             "location": {
        ...                 "type": "string",
        ...                 "description": "The city and state, e.g. San Francisco, CA",
        ...             },
        ...             "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        ...         },
        ...         "required": ["location"],
        ...     },
        ... )
    """

    name: str
    description: str = ""
    parameters: dict[str, Any]


class ToolTypes(StrEnum):
    r"""Enum of tool types.

    Attributes:
       function: A function tool.

    Examples:
        >>> tool_type = ToolTypes.function
    """

    function = "function"


class ToolChoice(StrEnum):
    r"""Enum of tool choice types.

    Attributes:
        auto: Automatically choose the tool.
        none: Do not use any tools.
        any: Use any tool.

    Examples:
        >>> tool_choice = ToolChoice.auto
    """

    auto = "auto"
    none = "none"
    any = "any"


class Tool(CaluteBase):
    r"""Tool definition.

    Attributes:
        type: The type of the tool.
        function: The function definition.

    Examples:
        >>> tool = Tool(
        ...     function=Function(
        ...         name="get_current_weather",
        ...         description="Get the current weather in a given location",
        ...         parameters={
        ...             "type": "object",
        ...             "properties": {
        ...                 "location": {
        ...                     "type": "string",
        ...                     "description": "The city and state, e.g. San Francisco, CA",
        ...                 },
        ...                 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        ...             },
        ...             "required": ["location"],
        ...         },
        ...     ),
        ... )
    """

    type: ToolTypes = ToolTypes.function
    function: Function

    def to_openai(self) -> dict[str, Any]:
        """Convert the tool to OpenAI-compatible format.

        Returns:
            Dictionary representation compatible with OpenAI's API.
        """
        return self.model_dump()

    @classmethod
    def from_openai(cls, openai_tool: dict[str, Any]) -> "Tool":
        """Create a Tool instance from an OpenAI-formatted dictionary.

        Args:
            openai_tool: Dictionary in OpenAI tool format.

        Returns:
            A new Tool instance.
        """
        return cls.model_validate(openai_tool)


class FunctionCall(CaluteBase):
    r"""Function call.

    Attributes:
        name: The name of the function to call.
        arguments: The arguments to pass to the function.

    Examples:
        >>> function_call = FunctionCall(
        ...     name="get_current_weather",
        ...     arguments={"location": "San Francisco, CA", "unit": "celsius"},
        ... )
    """

    name: str
    arguments: str

    @field_validator("arguments", mode="before")
    def validate_arguments(cls, v: str | dict[str, Any]) -> str:
        """Convert arguments to a JSON string if they are a dictionary.

        Args:
            v: The arguments to validate.

        Returns:
            The arguments as a JSON string.
        """
        if isinstance(v, dict):
            return json.dumps(v)
        return v


class ToolCall(CaluteBase):
    r"""Tool call.

    Attributes:
        id: The ID of the tool call. Required for V3+ tokenization
        type: The type of the tool call.
        function: The function call.

    Examples:
        >>> tool_call = ToolCall(
        ...     id="call_abc123",
        ...     function=FunctionCall(
        ...         name="get_current_weather",
        ...         arguments={"location": "San Francisco, CA", "unit": "celsius"},
        ...     ),
        ... )
    """

    id: str = "null"
    type: ToolTypes = ToolTypes.function
    function: FunctionCall

    def to_openai(self) -> dict[str, Any]:
        """Convert the tool call to OpenAI-compatible format.

        Returns:
            Dictionary representation compatible with OpenAI's API.
        """
        return self.model_dump()

    @classmethod
    def from_openai(cls, tool_call: dict[str, Any]) -> "ToolCall":
        """Create a ToolCall instance from an OpenAI-formatted dictionary.

        Args:
            tool_call: Dictionary in OpenAI tool call format.

        Returns:
            A new ToolCall instance.
        """
        return cls.model_validate(tool_call)


ToolType = TypeVar("ToolType", bound=Tool)
"""TypeVar bound to Tool for generic tool handling."""