类型定义¶
本节记录了 ToolRegistry 库中使用的类型定义，用于与各种 LLM API 格式的兼容。
通用类型¶
库中通用的类型定义。
toolregistry.types ¶
Type definitions for toolregistry.
ContentBlock
module-attribute
¶
Union type for all supported content block kinds.
Base64ImageSource ¶
Bases: TypedDict
Base64-encoded image data with media type.
ChatCompetionMessageToolCallResult ¶
ChatCompletionMessage ¶
ChatCompletionMessageCustomToolCall ¶
Bases: BaseModel
Custom tool call from OpenAI's updated SDK.
Example usage:
{ "id": "call_12345xyz", "type": "custom", "custom": { "name": "custom_tool", "input": "some input data" } }
ChatCompletionMessageFunctionToolCall ¶
Bases: BaseModel
Function tool call from OpenAI's SDK.
Example usage:
{ "id": "call_12345xyz", "type": "function", "function": { "name": "get_weather", "arguments": "{"location":"Paris, France"}" } }
Custom ¶
Function ¶
Bases: BaseModel
arguments
instance-attribute
¶
The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
ImageBlock ¶
Bases: TypedDict
An image content block with base64-encoded source.
ResponseFunctionToolCall ¶
Bases: BaseModel
Example usage
{ "id": "fc_12345xyz", "call_id": "call_12345xyz", "type": "function_call", "name": "get_weather", "arguments": "{"location":"Paris, France"}" }
arguments
instance-attribute
¶
A JSON string of the arguments to pass to the function.
call_id
instance-attribute
¶
The unique ID of the function tool call generated by the model.
id
class-attribute
instance-attribute
¶
The unique ID of the function tool call.
status
class-attribute
instance-attribute
¶
The status of the item.
One of in_progress, completed, or incomplete. Populated when items are
returned via API.
type
class-attribute
instance-attribute
¶
The type of the function tool call. Always function_call.
ResponseFunctionToolCallResult ¶
Bases: BaseModel
Example usage
{ "type": "function_call_output", "call_id": tool_call.call_id, "output": str(result) }
type
class-attribute
instance-attribute
¶
The type of the function tool call result. Always function_call_output.
TextBlock ¶
Bases: TypedDict
A plain text content block.
ToolCall ¶
Bases: BaseModel
arguments
instance-attribute
¶
The arguments to call the function with, as generated by the model in JSON format.
type
class-attribute
instance-attribute
¶
The type of the tool call. Either 'function' or 'custom'.
from_tool_call
classmethod
¶
Convert various tool call formats to ToolCall using Pydantic validation.
Supports the following formats: - ChatCompletionMessageFunctionToolCall (function calls) - ChatCompletionMessageCustomToolCall (custom calls) - ResponseFunctionToolCall (response API format) - Anthropic tool_use / server_tool_use blocks - Gemini functionCall parts - Dictionary representations of the above
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_call
|
Any
|
Tool call object in various formats (Pydantic models or dicts) |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ToolCall |
ToolCall
|
Normalized tool call object with proper type classification |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the tool call format is not supported |
ToolCallResult ¶
Bases: BaseModel
convert_any_field_to_str ¶
Convert result to string during serialization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
Current value of |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
String representation of the field. |
build_assistant_message ¶
build_assistant_message(tool_calls: list[ToolCall], *, api_format: API_FORMATS = 'openai-chat') -> list[dict[str, Any]]
Build the assistant message from tool calls in various API formats.
Reconstructs the assistant-side message containing tool call requests in the target API format. This function only handles the tool-call portion of the assistant message; content, thinking, reasoning, and other vendor-specific fields must be preserved by the caller from the original LLM response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_calls
|
list[ToolCall]
|
A list of ToolCall objects (may contain mixed types). |
required |
api_format
|
API_FORMATS
|
Target API format. Defaults to |
'openai-chat'
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
The assistant message as a list of dicts in the specified API format. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the API format is unsupported. |
build_expanded_user_message ¶
Build a user message from expanded multimodal content parts.
Converts canonical content blocks (TextBlock / ImageBlock)
into the user message format required by the target API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content_parts
|
list[dict[str, Any]]
|
List of content block dicts produced by
:func: |
required |
api_format
|
str
|
Target API format (e.g. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A user message dict ready to append to the conversation. |
build_tool_response ¶
build_tool_response(tool_responses: dict[str, str | list], *, api_format: API_FORMATS = 'openai-chat', tool_calls: list[ToolCall] | None = None) -> list[dict[str, Any]]
Build tool result messages from tool execution responses.
Reconstructs the tool-result messages needed by the LLM to process
function call outcomes. For Gemini format, tool_calls must be
provided to resolve function names (Gemini uses function names
instead of call IDs).
Values in tool_responses may be plain strings or
list[ContentBlock] for multimodal results. All formats
receive text-only tool results; multimodal content should be
expanded into a separate user message upstream via
:func:~toolregistry.types.content_blocks.expand_content_blocks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_responses
|
dict[str, str | list]
|
Mapping of tool call IDs to results ( |
required |
api_format
|
API_FORMATS
|
Target API format. Defaults to |
'openai-chat'
|
tool_calls
|
list[ToolCall] | None
|
Optional ToolCall list for Gemini name resolution. Falls back to call_id when unavailable. |
None
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
Tool result messages in the specified API format. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the API format is unsupported. |
content_blocks_to_text ¶
Render content blocks as a plain-text string.
Text blocks are concatenated directly. Image blocks are replaced with a human-readable placeholder indicating the media type and approximate data size.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blocks
|
list[ContentBlock]
|
List of content blocks to render. |
required |
Returns:
| Type | Description |
|---|---|
str
|
A plain-text representation of the content. |
convert_tool_calls ¶
Convert a list of tool calls into a list of ToolCall objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_calls
|
List[Any]
|
A list of tool call objects to convert. |
required |
Returns:
| Type | Description |
|---|---|
list[ToolCall]
|
List[ToolCall]: A list of converted ToolCall objects. |
expand_content_blocks ¶
expand_content_blocks(tool_responses: dict[str, str | list]) -> tuple[dict[str, str | list], list[dict[str, Any]]]
Separate multimodal content from tool responses for uniform handling.
For each tool response that contains content blocks (multimodal),
replaces the value with a placeholder string referencing a
<tool-content> tag, and collects the actual content blocks
into user message content parts that should follow the tool result
messages.
This approach is provider-agnostic: all API formats receive text-only tool results, and multimodal content is delivered via a subsequent user message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_responses
|
dict[str, str | list]
|
Mapping of tool call IDs to results.
Values may be |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str | list]
|
A tuple of: |
list[dict[str, Any]]
|
|
tuple[dict[str, str | list], list[dict[str, Any]]]
|
|
is_content_block_list ¶
Check whether value is a list of content blocks.
A valid content block list is a non-empty list where every
element is a dict with a "type" key whose value is one of
the recognized content block types ("text" or "image").
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
The value to check. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|
recover_assistant_message ¶
recover_assistant_message(tool_calls: list[ToolCall], *, api_format: API_FORMATS = 'openai-chat') -> list[dict[str, Any]]
Deprecated: use :func:build_assistant_message instead.
recover_tool_message ¶
recover_tool_message(tool_responses: dict[str, str | list], *, api_format: API_FORMATS = 'openai-chat', tool_calls: list[ToolCall] | None = None) -> list[dict[str, Any]]
Deprecated: use :func:build_tool_response instead.
toolregistry.types.common ¶
ToolCall ¶
Bases: BaseModel
arguments
instance-attribute
¶
The arguments to call the function with, as generated by the model in JSON format.
type
class-attribute
instance-attribute
¶
The type of the tool call. Either 'function' or 'custom'.
from_tool_call
classmethod
¶
Convert various tool call formats to ToolCall using Pydantic validation.
Supports the following formats: - ChatCompletionMessageFunctionToolCall (function calls) - ChatCompletionMessageCustomToolCall (custom calls) - ResponseFunctionToolCall (response API format) - Anthropic tool_use / server_tool_use blocks - Gemini functionCall parts - Dictionary representations of the above
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_call
|
Any
|
Tool call object in various formats (Pydantic models or dicts) |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ToolCall |
ToolCall
|
Normalized tool call object with proper type classification |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the tool call format is not supported |
ToolCallResult ¶
Bases: BaseModel
convert_any_field_to_str ¶
Convert result to string during serialization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
Current value of |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
String representation of the field. |
build_assistant_message ¶
build_assistant_message(tool_calls: list[ToolCall], *, api_format: API_FORMATS = 'openai-chat') -> list[dict[str, Any]]
Build the assistant message from tool calls in various API formats.
Reconstructs the assistant-side message containing tool call requests in the target API format. This function only handles the tool-call portion of the assistant message; content, thinking, reasoning, and other vendor-specific fields must be preserved by the caller from the original LLM response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_calls
|
list[ToolCall]
|
A list of ToolCall objects (may contain mixed types). |
required |
api_format
|
API_FORMATS
|
Target API format. Defaults to |
'openai-chat'
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
The assistant message as a list of dicts in the specified API format. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the API format is unsupported. |
build_tool_response ¶
build_tool_response(tool_responses: dict[str, str | list], *, api_format: API_FORMATS = 'openai-chat', tool_calls: list[ToolCall] | None = None) -> list[dict[str, Any]]
Build tool result messages from tool execution responses.
Reconstructs the tool-result messages needed by the LLM to process
function call outcomes. For Gemini format, tool_calls must be
provided to resolve function names (Gemini uses function names
instead of call IDs).
Values in tool_responses may be plain strings or
list[ContentBlock] for multimodal results. All formats
receive text-only tool results; multimodal content should be
expanded into a separate user message upstream via
:func:~toolregistry.types.content_blocks.expand_content_blocks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_responses
|
dict[str, str | list]
|
Mapping of tool call IDs to results ( |
required |
api_format
|
API_FORMATS
|
Target API format. Defaults to |
'openai-chat'
|
tool_calls
|
list[ToolCall] | None
|
Optional ToolCall list for Gemini name resolution. Falls back to call_id when unavailable. |
None
|
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
Tool result messages in the specified API format. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the API format is unsupported. |
convert_tool_calls ¶
Convert a list of tool calls into a list of ToolCall objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_calls
|
List[Any]
|
A list of tool call objects to convert. |
required |
Returns:
| Type | Description |
|---|---|
list[ToolCall]
|
List[ToolCall]: A list of converted ToolCall objects. |
recover_assistant_message ¶
recover_assistant_message(tool_calls: list[ToolCall], *, api_format: API_FORMATS = 'openai-chat') -> list[dict[str, Any]]
Deprecated: use :func:build_assistant_message instead.
recover_tool_message ¶
recover_tool_message(tool_responses: dict[str, str | list], *, api_format: API_FORMATS = 'openai-chat', tool_calls: list[ToolCall] | None = None) -> list[dict[str, Any]]
Deprecated: use :func:build_tool_response instead.
OpenAI 类型¶
用于 OpenAI API 兼容的类型定义。
toolregistry.types.openai ¶
OpenAI API types for toolregistry.
ChatCompetionMessageToolCallResult ¶
ChatCompletionMessage ¶
ChatCompletionMessageCustomToolCall ¶
Bases: BaseModel
Custom tool call from OpenAI's updated SDK.
Example usage:
{ "id": "call_12345xyz", "type": "custom", "custom": { "name": "custom_tool", "input": "some input data" } }
ChatCompletionMessageFunctionToolCall ¶
Bases: BaseModel
Function tool call from OpenAI's SDK.
Example usage:
{ "id": "call_12345xyz", "type": "function", "function": { "name": "get_weather", "arguments": "{"location":"Paris, France"}" } }
Custom ¶
Function ¶
Bases: BaseModel
arguments
instance-attribute
¶
The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
ResponseFunctionToolCall ¶
Bases: BaseModel
Example usage
{ "id": "fc_12345xyz", "call_id": "call_12345xyz", "type": "function_call", "name": "get_weather", "arguments": "{"location":"Paris, France"}" }
arguments
instance-attribute
¶
A JSON string of the arguments to pass to the function.
call_id
instance-attribute
¶
The unique ID of the function tool call generated by the model.
id
class-attribute
instance-attribute
¶
The unique ID of the function tool call.
status
class-attribute
instance-attribute
¶
The status of the item.
One of in_progress, completed, or incomplete. Populated when items are
returned via API.
type
class-attribute
instance-attribute
¶
The type of the function tool call. Always function_call.
toolregistry.types.openai.chat_completion ¶
ChatCompetionMessageToolCallResult ¶
ChatCompletionMessage ¶
ChatCompletionMessageCustomToolCall ¶
Bases: BaseModel
Custom tool call from OpenAI's updated SDK.
Example usage:
{ "id": "call_12345xyz", "type": "custom", "custom": { "name": "custom_tool", "input": "some input data" } }
ChatCompletionMessageFunctionToolCall ¶
Bases: BaseModel
Function tool call from OpenAI's SDK.
Example usage:
{ "id": "call_12345xyz", "type": "function", "function": { "name": "get_weather", "arguments": "{"location":"Paris, France"}" } }
Custom ¶
Function ¶
Bases: BaseModel
arguments
instance-attribute
¶
The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
toolregistry.types.openai.response ¶
ResponseFunctionToolCall ¶
Bases: BaseModel
Example usage
{ "id": "fc_12345xyz", "call_id": "call_12345xyz", "type": "function_call", "name": "get_weather", "arguments": "{"location":"Paris, France"}" }
arguments
instance-attribute
¶
A JSON string of the arguments to pass to the function.
call_id
instance-attribute
¶
The unique ID of the function tool call generated by the model.
id
class-attribute
instance-attribute
¶
The unique ID of the function tool call.
status
class-attribute
instance-attribute
¶
The status of the item.
One of in_progress, completed, or incomplete. Populated when items are
returned via API.
type
class-attribute
instance-attribute
¶
The type of the function tool call. Always function_call.
Anthropic 类型¶
用于 Anthropic API 兼容的类型定义。
toolregistry.types.anthropic ¶
Anthropic API types for toolregistry.
Format conversion for Anthropic tool schemas, tool calls, and tool results
is handled via llm-rosetta (pip install toolregistry[rosetta]).
No Pydantic models are defined here as llm-rosetta operates on plain dicts.
Gemini 类型¶
用于 Google Gemini API 兼容的类型定义。
toolregistry.types.gemini ¶
Gemini API types for toolregistry.
Format conversion for Gemini tool schemas, tool calls, and tool results
is handled via llm-rosetta (pip install toolregistry[rosetta]).
No Pydantic models are defined here as llm-rosetta operates on plain dicts.