calute.types.tool_calls

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"}')
... )

class calute.types.tool_calls.Function(*, name: str, description: str = '', parameters: dict[str, Any])

Bases: CaluteBase

Function definition for tools.

name

The name of the function.

Type

str

description

A description of what the function does.

Type

str

parameters

The parameters the functions accepts, described as a JSON Schema object.

Type

dict[str, Any]

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"],
...     },
... )

description: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

parameters: dict[str, Any]

class calute.types.tool_calls.FunctionCall(*, name: str, arguments: str)

Bases: CaluteBase

Function call.

name

The name of the function to call.

Type

str

arguments

The arguments to pass to the function.

Type

str

Examples

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

arguments: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

classmethod validate_arguments(v: str | dict[str, Any]) → str

Convert arguments to a JSON string if they are a dictionary.

Parameters

v – The arguments to validate.

Returns

The arguments as a JSON string.

class calute.types.tool_calls.Tool(*, type: ToolTypes = ToolTypes.function, function: Function)

Bases: CaluteBase

Tool definition.

type

The type of the tool.

Type

calute.types.tool_calls.ToolTypes

function

The function definition.

Type

calute.types.tool_calls.Function

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"],
...         },
...     ),
... )

classmethod from_openai(openai_tool: dict[str, Any]) → Tool

Create a Tool instance from an OpenAI-formatted dictionary.

Parameters

openai_tool – Dictionary in OpenAI tool format.

Returns

A new Tool instance.

function: Function

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_openai() → dict[str, Any]

Convert the tool to OpenAI-compatible format.

Returns

Dictionary representation compatible with OpenAI’s API.

type: ToolTypes

class calute.types.tool_calls.ToolCall(*, id: str = 'null', type: ToolTypes = ToolTypes.function, function: FunctionCall)

Bases: CaluteBase

Tool call.

id

The ID of the tool call. Required for V3+ tokenization

Type

str

type

The type of the tool call.

Type

calute.types.tool_calls.ToolTypes

function

The function call.

Type

calute.types.tool_calls.FunctionCall

Examples

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

classmethod from_openai(tool_call: dict[str, Any]) → ToolCall

Create a ToolCall instance from an OpenAI-formatted dictionary.

Parameters

tool_call – Dictionary in OpenAI tool call format.

Returns

A new ToolCall instance.

function: FunctionCall

id: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_openai() → dict[str, Any]

Convert the tool call to OpenAI-compatible format.

Returns

Dictionary representation compatible with OpenAI’s API.

type: ToolTypes

class calute.types.tool_calls.ToolChoice(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Enum of tool choice types.

auto

Automatically choose the tool.

none

Do not use any tools.

any

Use any tool.

Examples

>>> tool_choice = ToolChoice.auto

any = 'any'

auto = 'auto'

none = 'none'

calute.types.tool_calls.ToolType

TypeVar bound to Tool for generic tool handling.

alias of TypeVar(‘ToolType’, bound=Tool)

class calute.types.tool_calls.ToolTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Enum of tool types.

function

A function tool.

Examples

>>> tool_type = ToolTypes.function

function = 'function'