calute.types.converters

calute.types.converters#

OpenAI format conversion utilities for Calute.

This module provides utilities for converting between OpenAI API formats and Calute’s internal message and tool representations. It includes: - Message conversion from OpenAI format to Calute ChatMessage types - Tool conversion from OpenAI format to Calute Tool types - Field name validation for OpenAI compatibility checks

The converters ensure seamless interoperability with OpenAI-compatible APIs and models while maintaining Calute’s type safety.

Example

>>> from calute.types.converters import convert_openai_messages, convert_openai_tools
>>> openai_messages = [{"role": "user", "content": "Hello"}]
>>> calute_messages = convert_openai_messages(openai_messages)
>>> openai_tools = [{"type": "function", "function": {"name": "test", "parameters": {}}}]
>>> calute_tools = convert_openai_tools(openai_tools)
calute.types.converters.check_openai_fields_names(valid_fields_names: set[str], names: set[str]) → None[source]#

Validate that parameter names are recognized field names.

Checks each name against two sets: the caller-provided valid_fields_names and the internal _OPENAI_COMPLETION_FIELDS set of standard OpenAI chat completion parameters. Names that appear in neither set are flagged as invalid.

The error message distinguishes between names that are valid OpenAI parameters (but not in the caller’s valid set) and names that are entirely unrecognized, making it easier to diagnose configuration issues.

Parameters

  • valid_fields_names – A set of field names that the caller considers valid for its specific context (e.g., fields on a custom request model).

  • names – The set of field names to validate against both the caller’s valid set and the OpenAI completion fields.

Raises

ValueError – If any name is not found in valid_fields_names. The error message separates OpenAI-valid-but-unsupported parameters from completely unrecognized parameters.

Example

>>> valid = {"model", "messages", "temperature"}
>>> check_openai_fields_names(valid, {"model", "temperature"})  # OK
>>> check_openai_fields_names(valid, {"invalid_param"})  # raises ValueError
calute.types.converters.convert_openai_messages(messages: list[dict[str, str | list[dict[str, str | dict[str, Any]]]]]) → list[calute.types.messages.SystemMessage | calute.types.messages.UserMessage | calute.types.messages.AssistantMessage | calute.types.messages.ToolMessage][source]#

Convert a list of OpenAI-format message dictionaries to Calute ChatMessage objects.

Iterates through each message dictionary and dispatches to the appropriate Calute message class (UserMessage, AssistantMessage, ToolMessage, or SystemMessage) based on the ‘role’ field.

Parameters

messages – A list of message dictionaries in OpenAI chat completion format. Each dictionary must contain a ‘role’ key with one of the values: ‘user’, ‘assistant’, ‘tool’, or ‘system’. Additional keys depend on the role (e.g., ‘content’, ‘tool_calls’, ‘tool_call_id’).

Returns

A list of typed Calute ChatMessage objects corresponding to the input messages, preserving order.

Raises

ValueError – If a message has an unrecognized role value.

Example

>>> openai_msgs = [
...     {"role": "system", "content": "You are a helpful assistant."},
...     {"role": "user", "content": "Hello!"},
...     {"role": "assistant", "content": "Hi there!"},
... ]
>>> calute_msgs = convert_openai_messages(openai_msgs)
>>> len(calute_msgs)
3
calute.types.converters.convert_openai_tools(tools: list[dict[str, Any]]) → list[calute.types.tool_calls.Tool][source]#

Convert a list of OpenAI-format tool dictionaries to Calute Tool objects.

Each tool dictionary is expected to follow the OpenAI tool definition format with a ‘type’ field (typically “function”) and a ‘function’ field containing the function name, description, and JSON Schema parameters.

Parameters

tools – A list of tool definition dictionaries in OpenAI format. Each dictionary should contain ‘type’ and ‘function’ keys matching the OpenAI tool specification.

Returns

A list of Calute Tool instances, one per input dictionary.

Example

>>> openai_tools = [{
...     "type": "function",
...     "function": {
...         "name": "get_weather",
...         "description": "Get weather info",
...         "parameters": {"type": "object", "properties": {}}
...     }
... }]
>>> calute_tools = convert_openai_tools(openai_tools)
>>> calute_tools[0].function.name
'get_weather'
calute.types.converters.is_openai_field_name(name: str) → bool[source]#

Check whether a name is a recognized OpenAI chat completion field.

Looks up the given name in the internal _OPENAI_COMPLETION_FIELDS set, which contains all standard parameter names accepted by the OpenAI chat completion API (e.g., ‘model’, ‘messages’, ‘temperature’, ‘tools’).

Parameters

name – The field name string to check against the known OpenAI completion parameter names.

Returns

True if the name is a recognized OpenAI completion field name, False otherwise.

Example

>>> is_openai_field_name("temperature")
True
>>> is_openai_field_name("not_a_real_field")
False
Contents