Tool Ops API¶

The tool_ops module provides a lightweight convenience API for converting tool definitions between the IR (Intermediate Representation) and provider-native formats — without instantiating full converter pipelines.

All imports are lazy, so no provider-specific dependencies are loaded until the first call for that provider.

IR ToolDefinition format¶

Every function in this module consumes or produces the IR ToolDefinition TypedDict:

Field	Type	Required	Description
`type`	`"function"` \| `"mcp"`	✓	Tool kind. Currently only `"function"` is universally supported.
`name`	`str`	✓	Function name (snake_case recommended).
`description`	`str`	✓	Plain-language description of what the tool does.
`parameters`	`dict`	✓	JSON Schema object describing the function arguments.
`required_parameters`	`list[str]`	optional	Required parameter names (merged into the JSON Schema on conversion).
`metadata`	`dict`	optional	Pass-through extra fields; provider converters may use or ignore these.

ir_tool: ToolDefinition = {
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["city"],
    },
}

Provider wire formats¶

Each provider serialises tools differently. The table below shows the top-level shape after conversion:

Provider	Output shape
`openai_chat`	`{"type": "function", "function": {"name": …, "description": …, "parameters": {…}}}`
`openai_responses`	`{"type": "function", "name": …, "description": …, "parameters": {…}}`
`anthropic`	`{"name": …, "description": …, "input_schema": {…}}`
`google`	`{"function_declarations": [{"name": …, "description": …, "parameters": {…}}]}`

Quick example¶

from llm_rosetta import tool_ops

ir_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}

# ---- IR → provider ----
openai_tool    = tool_ops.to_openai_chat(ir_tool)
responses_tool = tool_ops.to_openai_responses(ir_tool)
anthropic_tool = tool_ops.to_anthropic(ir_tool)
google_tool    = tool_ops.to_google_genai(ir_tool)

# Unified dispatch variant
same_tool = tool_ops.to_provider(ir_tool, provider="anthropic")

# ---- Provider → IR ----
recovered = tool_ops.from_openai_chat(openai_tool)
recovered = tool_ops.from_anthropic(anthropic_tool)
recovered = tool_ops.from_provider(anthropic_tool, provider="anthropic")

Example: Anthropic output¶

tool_ops.to_anthropic(ir_tool)
# →
{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}

Example: Google GenAI output¶

tool_ops.to_google_genai(ir_tool)
# →
{
    "function_declarations": [
        {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ]
}

Google wraps declarations in a list

to_google_genai always wraps the converted tool inside {"function_declarations": [...]}. Likewise, from_google_genai can return a list of IR tools when the input contains multiple declarations.

Supported providers¶

Canonical name	Accepted aliases
`openai_chat`	`openai-chat`
`openai_responses`	`openai-responses`, `open_responses`, `open-responses`
`anthropic`	—
`google`	`google-genai`

Batch conversion¶

tool_ops converts one tool at a time. For a list of tools, use a comprehension:

ir_tools = [tool_a, tool_b, tool_c]

# IR → Anthropic
anthropic_tools = [tool_ops.to_anthropic(t) for t in ir_tools]

# Anthropic → IR
ir_recovered = [tool_ops.from_anthropic(t) for t in anthropic_tools]
# filter None in case a tool type is unsupported
ir_recovered = [t for t in ir_recovered if t is not None]

For Google, flatten the function_declarations list first:

google_tools = [tool_ops.to_google_genai(t) for t in ir_tools]
# google_tools is a list of {"function_declarations": [...]} dicts

# Round-trip: each from_google_genai call may return a list
import itertools
ir_recovered = list(itertools.chain.from_iterable(
    result if isinstance(result, list) else [result]
    for t in google_tools
    if (result := tool_ops.from_google_genai(t)) is not None
))

Error handling¶

to_provider and from_provider raise ValueError for unrecognised provider names:

try:
    tool_ops.to_provider(ir_tool, provider="unknown")
except ValueError as exc:
    print(exc)
# Unknown provider: 'unknown'. Supported: openai_chat, openai_responses, ...

Per-provider shortcuts (to_anthropic, etc.) do not perform name resolution and never raise ValueError for provider names.

Unified dispatch¶

llm_rosetta.tool_ops.to_provider ¶

to_provider(ir_tool: ToolDefinition, provider: ToolProvider, **kwargs: Any) -> Any

Convert an IR tool definition to provider-native format.

Parameters:

Name	Type	Description	Default
`ir_tool`	`ToolDefinition`	IR ToolDefinition dict.	required
`provider`	`ToolProvider`	Target provider name or alias.	required
`**kwargs`	`Any`	Forwarded to the underlying ToolOps method.	`{}`

Returns:

Type	Description
`Any`	Provider-native tool definition dict.

Raises:

Type	Description
`ValueError`	If provider is not recognized.

Source code in src/llm_rosetta/tool_ops.py

def to_provider(ir_tool: ToolDefinition, provider: ToolProvider, **kwargs: Any) -> Any:
    """Convert an IR tool definition to provider-native format.

    Args:
        ir_tool: IR ToolDefinition dict.
        provider: Target provider name or alias.
        **kwargs: Forwarded to the underlying ToolOps method.

    Returns:
        Provider-native tool definition dict.

    Raises:
        ValueError: If *provider* is not recognized.
    """
    return _get_tool_ops(provider).ir_tool_definition_to_p(ir_tool, **kwargs)

llm_rosetta.tool_ops.from_provider ¶

from_provider(provider_tool: Any, provider: ToolProvider, **kwargs: Any) -> ToolDefinition | list[ToolDefinition] | None

Convert a provider-native tool definition to IR format.

Parameters:

Name	Type	Description	Default
`provider_tool`	`Any`	Provider-native tool definition.	required
`provider`	`ToolProvider`	Source provider name or alias.	required
`**kwargs`	`Any`	Forwarded to the underlying ToolOps method.	`{}`

Returns:

Type	Description
`ToolDefinition \| list[ToolDefinition] \| None`	IR ToolDefinition, a list of them (Google may return multiple),
`ToolDefinition \| list[ToolDefinition] \| None`	or None if the tool type is not supported.

Raises:

Type	Description
`ValueError`	If provider is not recognized.

Source code in src/llm_rosetta/tool_ops.py

def from_provider(
    provider_tool: Any, provider: ToolProvider, **kwargs: Any
) -> ToolDefinition | list[ToolDefinition] | None:
    """Convert a provider-native tool definition to IR format.

    Args:
        provider_tool: Provider-native tool definition.
        provider: Source provider name or alias.
        **kwargs: Forwarded to the underlying ToolOps method.

    Returns:
        IR ToolDefinition, a list of them (Google may return multiple),
        or None if the tool type is not supported.

    Raises:
        ValueError: If *provider* is not recognized.
    """
    return _get_tool_ops(provider).p_tool_definition_to_ir(provider_tool, **kwargs)

Per-provider shortcuts¶

IR → provider¶

llm_rosetta.tool_ops.to_openai_chat ¶

to_openai_chat(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]

Convert IR tool definition to OpenAI Chat format.

Source code in src/llm_rosetta/tool_ops.py

def to_openai_chat(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]:
    """Convert IR tool definition to OpenAI Chat format."""
    from .converters.openai_chat import OpenAIChatToolOps

    return OpenAIChatToolOps.ir_tool_definition_to_p(ir_tool, **kwargs)

llm_rosetta.tool_ops.to_openai_responses ¶

to_openai_responses(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]

Convert IR tool definition to OpenAI Responses format.

Source code in src/llm_rosetta/tool_ops.py

def to_openai_responses(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]:
    """Convert IR tool definition to OpenAI Responses format."""
    from .converters.openai_responses import OpenAIResponsesToolOps

    return OpenAIResponsesToolOps.ir_tool_definition_to_p(ir_tool, **kwargs)

llm_rosetta.tool_ops.to_anthropic ¶

to_anthropic(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]

Convert IR tool definition to Anthropic format.

Source code in src/llm_rosetta/tool_ops.py

def to_anthropic(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]:
    """Convert IR tool definition to Anthropic format."""
    from .converters.anthropic import AnthropicToolOps

    return AnthropicToolOps.ir_tool_definition_to_p(ir_tool, **kwargs)

llm_rosetta.tool_ops.to_google_genai ¶

to_google_genai(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]

Convert IR tool definition to Google GenAI format.

Source code in src/llm_rosetta/tool_ops.py

def to_google_genai(ir_tool: ToolDefinition, **kwargs: Any) -> dict[str, Any]:
    """Convert IR tool definition to Google GenAI format."""
    from .converters.google_genai import GoogleGenAIToolOps

    return GoogleGenAIToolOps.ir_tool_definition_to_p(ir_tool, **kwargs)

Provider → IR¶

llm_rosetta.tool_ops.from_openai_chat ¶

from_openai_chat(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None

Convert OpenAI Chat tool definition to IR format.

Source code in src/llm_rosetta/tool_ops.py

def from_openai_chat(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None:
    """Convert OpenAI Chat tool definition to IR format."""
    from .converters.openai_chat import OpenAIChatToolOps

    return OpenAIChatToolOps.p_tool_definition_to_ir(provider_tool, **kwargs)

llm_rosetta.tool_ops.from_openai_responses ¶

from_openai_responses(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None

Convert OpenAI Responses tool definition to IR format.

Source code in src/llm_rosetta/tool_ops.py

def from_openai_responses(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None:
    """Convert OpenAI Responses tool definition to IR format."""
    from .converters.openai_responses import OpenAIResponsesToolOps

    return OpenAIResponsesToolOps.p_tool_definition_to_ir(provider_tool, **kwargs)

llm_rosetta.tool_ops.from_anthropic ¶

from_anthropic(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None

Convert Anthropic tool definition to IR format.

Source code in src/llm_rosetta/tool_ops.py

def from_anthropic(provider_tool: Any, **kwargs: Any) -> ToolDefinition | None:
    """Convert Anthropic tool definition to IR format."""
    from .converters.anthropic import AnthropicToolOps

    return AnthropicToolOps.p_tool_definition_to_ir(provider_tool, **kwargs)

llm_rosetta.tool_ops.from_google_genai ¶

from_google_genai(provider_tool: Any, **kwargs: Any) -> ToolDefinition | list[ToolDefinition] | None

Convert Google GenAI tool definition to IR format.

Source code in src/llm_rosetta/tool_ops.py

def from_google_genai(
    provider_tool: Any, **kwargs: Any
) -> ToolDefinition | list[ToolDefinition] | None:
    """Convert Google GenAI tool definition to IR format."""
    from .converters.google_genai import GoogleGenAIToolOps

    return GoogleGenAIToolOps.p_tool_definition_to_ir(provider_tool, **kwargs)