calute.types.oai_protocols

calute.types.oai_protocols#

OpenAI API protocol definitions for Calute.

This module provides Pydantic models that mirror the OpenAI API protocol structures. It includes: - Request models for chat completions and text completions - Response models for both streaming and non-streaming responses - Message types for chat conversations - Tool and function calling structures - Usage and metrics tracking

These models enable Calute to provide OpenAI-compatible API endpoints and facilitate integration with OpenAI-compatible clients and tools.

Example

>>> from calute.types.oai_protocols import ChatCompletionRequest, ChatMessage
>>> request = ChatCompletionRequest(
...     model="gpt-4",
...     messages=[ChatMessage(role="user", content="Hello!")]
... )

class calute.types.oai_protocols.ChatCompletionRequest(*, model: str, messages: list[calute.types.oai_protocols.ChatMessage], max_tokens: int = 128, presence_penalty: float = 0.0, frequency_penalty: float = 0.0, repetition_penalty: float = 1.0, temperature: float = 0.7, top_p: float = 0.95, top_k: int = 0, min_p: float = 0.0, suppress_tokens: list[int] = <factory>, functions: list[calute.types.oai_protocols.FunctionDefinition] | None = None, function_call: str | dict[str, typing.Any] | None = None, tools: list[calute.types.oai_protocols.ToolDefinition] | None = None, tool_choice: str | dict[str, typing.Any] | None = None, n: int | None = 1, stream: bool | None = False, stop: str | list[str] | None = None, logit_bias: dict[str, float] | None = None, user: str | None = None, chat_template_kwargs: dict[str, int | float | str | bool] | None = None, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a request to the chat completion endpoint.

Mirrors the OpenAI ChatCompletion request structure with additional parameters for extended functionality.

model#

Model identifier to use for completion.

Type: str

messages#

List of messages in the conversation.

Type: list[calute.types.oai_protocols.ChatMessage]

max_tokens#

Maximum tokens to generate.

Type: int

presence_penalty#

Penalty for token presence (0.0-2.0).

Type: float

frequency_penalty#

Penalty for token frequency (0.0-2.0).

Type: float

repetition_penalty#

Repetition penalty multiplier.

Type: float

temperature#

Sampling temperature (0.0-2.0).

Type: float

top_p#

Nucleus sampling probability threshold.

Type: float

top_k#

Top-k sampling parameter.

Type: int

min_p#

Minimum probability threshold for sampling.

Type: float

suppress_tokens#

Token IDs to suppress during generation.

Type: list[int]

functions#

Legacy function definitions (deprecated).

Type: list[calute.types.oai_protocols.FunctionDefinition] | None

function_call#

Legacy function call control (deprecated).

Type: str | dict[str, Any] | None

tools#

Tool definitions for function calling.

Type: list[calute.types.oai_protocols.ToolDefinition] | None

tool_choice#

Tool selection strategy.

Type: str | dict[str, Any] | None

n#

Number of completions to generate.

Type: int | None

stream#

Whether to stream the response.

Type: bool | None

stop#

Stop sequences to end generation.

Type: str | list[str] | None

logit_bias#

Token logit adjustments.

Type: dict[str, float] | None

user#

Unique user identifier for tracking.

Type: str | None

chat_template_kwargs#

Additional template rendering arguments.

Type: dict[str, int | float | str | bool] | None

chat_template_kwargs: dict[str, int | float | str | bool] | None#

frequency_penalty: float#

function_call: str | dict[str, Any] | None#

functions: list[calute.types.oai_protocols.FunctionDefinition] | None#

logit_bias: dict[str, float] | None#

max_tokens: int#

messages: list[calute.types.oai_protocols.ChatMessage]#

min_p: float#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n: int | None#

presence_penalty: float#

repetition_penalty: float#

stop: str | list[str] | None#

stream: bool | None#

suppress_tokens: list[int]#

temperature: float#

tool_choice: str | dict[str, Any] | None#

tools: list[calute.types.oai_protocols.ToolDefinition] | None#

top_k: int#

top_p: float#

user: str | None#

class calute.types.oai_protocols.ChatCompletionResponse(*, id: str = <factory>, object: str = 'chat.completion', created: int = <factory>, model: str, choices: list[calute.types.oai_protocols.ChatCompletionResponseChoice], usage: ~calute.types.oai_protocols.UsageInfo, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a complete non-streaming response from the chat completion endpoint.

Contains one or more choices (completions), usage statistics, and metadata about the request. Compatible with the OpenAI chat completion response format.

id#

Unique identifier for this completion, auto-generated with a "chat-" prefix followed by a UUID hex string.

Type: str

object#

Object type identifier, always "chat.completion".

Type: str

created#

Unix timestamp (seconds) when the response was created.

Type: int

model#

The model identifier that generated the response.

Type: str

choices#

List of ChatCompletionResponseChoice objects, one per requested completion (controlled by the n parameter).

Type: list[calute.types.oai_protocols.ChatCompletionResponseChoice]

usage#

Token usage statistics for the request and response.

Type: calute.types.oai_protocols.UsageInfo

choices: list[calute.types.oai_protocols.ChatCompletionResponseChoice]#

created: int#

id: str#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

object: str#

usage: UsageInfo#

class calute.types.oai_protocols.ChatCompletionResponseChoice(*, index: int, message: ChatMessage, finish_reason: Optional[Literal['stop', 'length', 'function_call', 'tool_calls', 'abort']] = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a single choice within a non-streaming chat completion response.

Each choice contains a complete message and metadata about why generation stopped.

index#

Zero-based index of this choice in the response’s choices list.

Type: int

message#

The complete ChatMessage generated for this choice.

Type: calute.types.oai_protocols.ChatMessage

finish_reason#

The reason generation stopped. One of "stop" (natural end), "length" (token limit reached), "function_call" (legacy function invocation), "tool_calls" (tool invocation requested), or "abort" (generation was aborted). None if not yet finished.

Type: Optional[Literal[‘stop’, ‘length’, ‘function_call’, ‘tool_calls’, ‘abort’]]

finish_reason: Optional[Literal['stop', 'length', 'function_call', 'tool_calls', 'abort']]#

index: int#

message: ChatMessage#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class calute.types.oai_protocols.ChatCompletionStreamResponse(*, id: str = <factory>, object: str = 'chat.completion.chunk', created: int = <factory>, model: str, choices: list[calute.types.oai_protocols.ChatCompletionStreamResponseChoice], usage: ~calute.types.oai_protocols.UsageInfo, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a single chunk in a streaming response from the chat completion endpoint.

Sent as a Server-Sent Events (SSE) data payload during streaming. Each chunk contains incremental updates to one or more choices being generated.

id#

Unique identifier for the streaming session, auto-generated with a "chat-" prefix followed by a UUID hex string.

Type: str

object#

Object type identifier, always "chat.completion.chunk".

Type: str

created#

Unix timestamp (seconds) when the chunk was created.

Type: int

model#

The model identifier generating the streamed response.

Type: str

choices#

List of ChatCompletionStreamResponseChoice objects with incremental delta updates.

Type: list[calute.types.oai_protocols.ChatCompletionStreamResponseChoice]

usage#

Token usage statistics. May be populated only in the final chunk.

Type: calute.types.oai_protocols.UsageInfo

choices: list[calute.types.oai_protocols.ChatCompletionStreamResponseChoice]#

created: int#

id: str#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

object: str#

usage: UsageInfo#

class calute.types.oai_protocols.ChatCompletionStreamResponseChoice(*, index: int, delta: DeltaMessage, finish_reason: Optional[Literal['stop', 'length', 'function_call']] = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a single choice within a streaming chat completion response chunk.

Contains a delta (incremental update) rather than a complete message, allowing clients to progressively build the response.

index#

Zero-based index of this choice in the chunk’s choices list.

Type: int

delta#

The DeltaMessage containing incremental content or role information for this chunk.

Type: calute.types.oai_protocols.DeltaMessage

finish_reason#

The reason generation stopped, or None if generation is still in progress. One of "stop", "length", or "function_call".

Type: Optional[Literal[‘stop’, ‘length’, ‘function_call’]]

delta: DeltaMessage#

finish_reason: Optional[Literal['stop', 'length', 'function_call']]#

index: int#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class calute.types.oai_protocols.ChatMessage(*, role: str, content: str | list[Mapping[str, str]], name: str | None = None, function_call: dict[str, Any] | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a single message in a chat conversation (OpenAI protocol).

Used within ChatCompletionRequest to represent messages in the conversation history. Supports both plain text and structured multimodal content.

role#

The role of the message sender. One of "system", "user", "assistant", or "function".

Type: str

content#

The message content, either a plain text string or a list of content part mappings for multimodal messages.

Type: str | list[Mapping[str, str]]

name#

Optional name identifier for the message sender, used to distinguish between multiple participants with the same role.

Type: str | None

function_call#

Optional dictionary containing function call information when the assistant requests a function invocation (legacy format).

Type: dict[str, Any] | None

Example

>>> msg = ChatMessage(role="user", content="What is the weather?")

content: str | list[Mapping[str, str]]#

function_call: dict[str, Any] | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None#

role: str#

class calute.types.oai_protocols.CompletionLogprobs(*, tokens: list[str], token_logprobs: list[float], top_logprobs: list[dict[str, float]] | None = None, text_offset: list[int] | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Log probability information for generated tokens.

Contains per-token log probabilities and optionally the top alternative tokens with their probabilities, useful for analyzing model confidence and debugging generation behavior.

tokens#

List of generated token strings.

Type: list[str]

token_logprobs#

Log probability of each generated token.

Type: list[float]

top_logprobs#

Optional list of dictionaries mapping alternative tokens to their log probabilities for each position.

Type: list[dict[str, float]] | None

text_offset#

Optional list of character offsets for each token in the original text.

Type: list[int] | None

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

text_offset: list[int] | None#

token_logprobs: list[float]#

tokens: list[str]#

top_logprobs: list[dict[str, float]] | None#

class calute.types.oai_protocols.CompletionRequest(*, model: str, prompt: str | list[str], max_tokens: int = 128, presence_penalty: float = 0.0, frequency_penalty: float = 0.0, repetition_penalty: float = 1.0, temperature: float = 0.7, top_p: float = 0.95, top_k: int = 0, min_p: float = 0.0, suppress_tokens: list[int] = <factory>, n: int | None = 1, stream: bool | None = False, stop: str | list[str] | None = None, logit_bias: dict[str, float] | None = None, user: str | None = None, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a request to the completions endpoint.

Mirrors the OpenAI Completion request structure for text completion (non-chat) endpoints.

model#

Model identifier to use for completion.

Type: str

prompt#

Text prompt(s) to complete.

Type: str | list[str]

max_tokens#

Maximum tokens to generate.

Type: int

presence_penalty#

Penalty for token presence (0.0-2.0).

Type: float

frequency_penalty#

Penalty for token frequency (0.0-2.0).

Type: float

repetition_penalty#

Repetition penalty multiplier.

Type: float

temperature#

Sampling temperature (0.0-2.0).

Type: float

top_p#

Nucleus sampling probability threshold.

Type: float

top_k#

Top-k sampling parameter.

Type: int

min_p#

Minimum probability threshold for sampling.

Type: float

suppress_tokens#

Token IDs to suppress during generation.

Type: list[int]

n#

Number of completions to generate.

Type: int | None

stream#

Whether to stream the response.

Type: bool | None

stop#

Stop sequences to end generation.

Type: str | list[str] | None

logit_bias#

Token logit adjustments.

Type: dict[str, float] | None

user#

Unique user identifier for tracking.

Type: str | None

frequency_penalty: float#

logit_bias: dict[str, float] | None#

max_tokens: int#

min_p: float#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n: int | None#

presence_penalty: float#

prompt: str | list[str]#

repetition_penalty: float#

stop: str | list[str] | None#

stream: bool | None#

suppress_tokens: list[int]#

temperature: float#

top_k: int#

top_p: float#

user: str | None#

class calute.types.oai_protocols.CompletionResponse(*, id: str = <factory>, object: str = 'text_completion', created: int = <factory>, model: str, choices: list[calute.types.oai_protocols.CompletionResponseChoice], usage: ~calute.types.oai_protocols.UsageInfo, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a complete non-streaming response from the text completions endpoint.

id#

Unique identifier for this completion, auto-generated with a "cmpl-" prefix followed by a UUID hex string.

Type: str

object#

Object type identifier, always "text_completion".

Type: str

created#

Unix timestamp (seconds) when the response was created.

Type: int

model#

The model identifier that generated the completion.

Type: str

choices#

List of CompletionResponseChoice objects, one per requested completion.

Type: list[calute.types.oai_protocols.CompletionResponseChoice]

usage#

Token usage statistics for the request and response.

Type: calute.types.oai_protocols.UsageInfo

choices: list[calute.types.oai_protocols.CompletionResponseChoice]#

created: int#

id: str#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

object: str#

usage: UsageInfo#

class calute.types.oai_protocols.CompletionResponseChoice(*, text: str, index: int, logprobs: calute.types.oai_protocols.CompletionLogprobs | None = None, finish_reason: Optional[Literal['stop', 'length', 'function_call']] = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a single choice within a text completion response.

text#

The generated text completion string.

Type: str

index#

Zero-based index of this choice in the response’s choices list.

Type: int

logprobs#

Optional CompletionLogprobs with per-token log probability information, included when requested via the logprobs parameter.

Type: calute.types.oai_protocols.CompletionLogprobs | None

finish_reason#

The reason generation stopped. One of "stop" (hit a stop sequence), "length" (reached max tokens), or "function_call". None if not yet finished.

Type: Optional[Literal[‘stop’, ‘length’, ‘function_call’]]

finish_reason: Optional[Literal['stop', 'length', 'function_call']]#

index: int#

logprobs: calute.types.oai_protocols.CompletionLogprobs | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

text: str#

class calute.types.oai_protocols.CompletionStreamResponse(*, id: str = <factory>, object: str = 'text_completion.chunk', created: int = <factory>, model: str, choices: list[calute.types.oai_protocols.CompletionStreamResponseChoice], usage: calute.types.oai_protocols.UsageInfo | None = None, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Represents a single chunk in a streaming response from the text completions endpoint.

Sent as a Server-Sent Events (SSE) data payload during streaming text completion requests.

id#

Unique identifier for the streaming session, auto-generated with a "cmpl-" prefix followed by a UUID hex string.

Type: str

object#

Object type identifier, always "text_completion.chunk".

Type: str

created#

Unix timestamp (seconds) when the chunk was created.

Type: int

model#

The model identifier generating the streamed completion.

Type: str

choices#

List of CompletionStreamResponseChoice objects with incremental text content.

Type: list[calute.types.oai_protocols.CompletionStreamResponseChoice]

usage#

Optional token usage statistics, typically populated only in the final chunk.

Type: calute.types.oai_protocols.UsageInfo | None

choices: list[calute.types.oai_protocols.CompletionStreamResponseChoice]#

created: int#

id: str#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

object: str#

usage: calute.types.oai_protocols.UsageInfo | None#

class calute.types.oai_protocols.CompletionStreamResponseChoice(*, index: int, text: str, logprobs: calute.types.oai_protocols.CompletionLogprobs | None = None, finish_reason: Optional[Literal['stop', 'length', 'function_call']] = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a single choice within a streaming text completion response chunk.

index#

Zero-based index of this choice in the chunk’s choices list.

Type: int

text#

Incremental text content for this chunk.

Type: str

logprobs#

Optional CompletionLogprobs with per-token log probability information for the tokens in this chunk.

Type: calute.types.oai_protocols.CompletionLogprobs | None

finish_reason#

The reason generation stopped, or None if generation is still in progress. One of "stop", "length", or "function_call".

Type: Optional[Literal[‘stop’, ‘length’, ‘function_call’]]

finish_reason: Optional[Literal['stop', 'length', 'function_call']]#

index: int#

logprobs: calute.types.oai_protocols.CompletionLogprobs | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

text: str#

class calute.types.oai_protocols.CountTokenRequest(*, model: str, conversation: str | list[calute.types.oai_protocols.ChatMessage], **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a request to the token counting endpoint.

Used to count the number of tokens in a conversation or text string for a specific model, without generating a completion.

model#

The model identifier to use for tokenization.

Type: str

conversation#

The input to tokenize, either a plain text string or a list of ChatMessage objects representing a conversation.

Type: str | list[calute.types.oai_protocols.ChatMessage]

conversation: str | list[calute.types.oai_protocols.ChatMessage]#

model: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class calute.types.oai_protocols.DeltaFunctionCall(*, name: str | None = None, arguments: str | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents incremental updates to a function call during streaming.

Carries partial function call data within streaming tool call chunks. The name is typically sent in the first chunk only, while arguments are progressively appended across multiple chunks.

name#

The function name, included only in the first chunk of the tool call. None for subsequent chunks.

Type: str | None

arguments#

Incremental JSON string fragment of the function arguments to append. None when no argument data is included in this chunk.

Type: str | None

arguments: str | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None#

class calute.types.oai_protocols.DeltaMessage(*, role: str | None = None, content: str | list[Mapping[str, str]] | None = None, function_call: dict[str, Any] | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents an incremental change (delta) in a chat message during streaming.

Used within ChatCompletionStreamResponseChoice to convey partial updates as they are generated. The first chunk typically includes the role, and subsequent chunks contain incremental content.

role#

The message role, included only in the first chunk of a new message (e.g., "assistant"). None for subsequent chunks.

Type: str | None

content#

Incremental text content to append to the message being built, or a list of structured content parts. None when only metadata is being sent.

Type: str | list[Mapping[str, str]] | None

function_call#

Optional dictionary with incremental function call updates (legacy format). Used for streaming function name and arguments progressively.

Type: dict[str, Any] | None

content: str | list[Mapping[str, str]] | None#

function_call: dict[str, Any] | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

role: str | None#

class calute.types.oai_protocols.DeltaToolCall(*, id: str | None = None, type: Optional[Literal['function']] = None, index: int, function: calute.types.oai_protocols.DeltaFunctionCall | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents incremental updates to a tool call during streaming.

Used in streaming chat completion responses to progressively build up tool call information across multiple chunks. The id and type are sent in the first chunk, while function data arrives incrementally.

id#

Unique tool call identifier, included only in the first chunk. None for subsequent chunks.

Type: str | None

type#

The tool type literal, always "function" when present. None for subsequent chunks after the first.

Type: Optional[Literal[‘function’]]

index#

Zero-based index of this tool call in the response’s tool calls list. Always present to identify which tool call is being updated.

Type: int

function#

Incremental DeltaFunctionCall with partial function name and/or arguments data. None when no function data is included in this chunk.

Type: calute.types.oai_protocols.DeltaFunctionCall | None

function: calute.types.oai_protocols.DeltaFunctionCall | None#

id: str | None#

index: int#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: Optional[Literal['function']]#

class calute.types.oai_protocols.ExtractedToolCallInformation(*, tools_called: bool, tool_calls: list[calute.types.oai_protocols.ToolCall], content: str | None = None, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Container for extracted tool call information from model output.

Used to parse and store tool calls extracted from various model output formats.

tools_called#

Whether any tools were called.

Type: bool

tool_calls#

List of extracted tool calls.

Type: list[calute.types.oai_protocols.ToolCall]

content#

Any remaining content after tool extraction.

Type: str | None

content: str | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tool_calls: list[calute.types.oai_protocols.ToolCall]#

tools_called: bool#

class calute.types.oai_protocols.Function(*, name: str, description: str | None = None, parameters: dict[str, typing.Any] = <factory>, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Function definition used within ToolCall for response-side tool calls.

This is the response-side counterpart to the request-side FunctionDefinition. It appears within ToolCall objects in model responses to describe the function being invoked.

name#

The function name matching a defined tool.

Type: str

description#

Optional description of the function’s purpose.

Type: str | None

parameters#

JSON Schema object for the function’s parameters.

Type: dict[str, Any]

description: str | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str#

parameters: dict[str, Any]#

class calute.types.oai_protocols.FunctionCall(*, name: str, arguments: str, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a function call extracted from a model response.

Contains the function name and a JSON-encoded arguments string as produced by the model during function/tool calling.

name#

The name of the function to call, matching a function defined in the request’s tools or functions list.

Type: str

arguments#

JSON-encoded string of the function arguments as generated by the model. Must be parsed with json.loads() before use.

Type: str

arguments: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str#

class calute.types.oai_protocols.FunctionCallFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Supported function call formats.

Different models and frameworks use different formats for function calling.

OPENAI#: OpenAI’s standard format

JSON_SCHEMA#: Direct JSON schema format

HERMES#: Hermes model function calling format

GORILLA#: Gorilla model function calling format

QWEN#: Qwen’s special token format (✿FUNCTION✿)

NOUS#: Nous XML-style wrapper format

GORILLA = 'gorilla'#

HERMES = 'hermes'#

JSON_SCHEMA = 'json_schema'#

NOUS = 'nous'#

OPENAI = 'openai'#

QWEN = 'qwen'#

class calute.types.oai_protocols.FunctionDefinition(*, name: str, description: str | None = None, parameters: dict[str, typing.Any] = <factory>, **extra_data: ~typing.Any)[source]#

Bases: OpenAIBaseModel

Defines a function that can be called by the model (legacy format).

Used within the deprecated functions field of ChatCompletionRequest. For new implementations, prefer ToolDefinition with the tools field.

name#

The unique function name used by the model for invocation.

Type: str

description#

Optional human-readable description to help the model understand when and how to call this function.

Type: str | None

parameters#

JSON Schema object describing the function’s parameters, including property types, descriptions, and required fields.

Type: dict[str, Any]

description: str | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str#

parameters: dict[str, Any]#

class calute.types.oai_protocols.OpenAIBaseModel(**extra_data: Any)[source]#

Bases: BaseModel

Base Pydantic model for all OpenAI-compatible protocol structures.

Extends Pydantic’s BaseModel with extra="allow" configuration to accept additional fields beyond those explicitly defined, and provides automatic caching of valid field names (including aliases) for efficient validation in downstream code.

All OpenAI protocol models in this module inherit from this base class to ensure consistent behavior and forward compatibility with new API fields.

field_names#

Class-variable cache of valid field names including aliases. Populated lazily on first model validation and reused for subsequent instances.

Type: ClassVar[set[str] | None]

field_names: ClassVar[set[str] | None] = None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class calute.types.oai_protocols.Tool(*, type: str = 'function', function: Function, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Tool definition wrapping a function for model-driven invocation.

Wraps a Function definition with a type discriminator, following the OpenAI tools API format where type is always "function".

type#

The tool type identifier, currently always "function".

Type: str

function#

The Function definition describing the callable tool.

Type: calute.types.oai_protocols.Function

function: Function#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str#

class calute.types.oai_protocols.ToolCall(*, id: str, type: str = 'function', function: FunctionCall, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Represents a tool call made by the model in a response.

Contains the full identification and function call details for a single tool invocation requested by the model.

id#

Unique identifier for this tool call, used to correlate with the corresponding tool result message.

Type: str

type#

The tool type, always "function".

Type: str

function#

The FunctionCall containing the function name and JSON-encoded arguments string.

Type: calute.types.oai_protocols.FunctionCall

function: FunctionCall#

id: str#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str#

class calute.types.oai_protocols.ToolDefinition(*, type: str = 'function', function: FunctionDefinition, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Defines a tool that can be called by the model.

Wraps a FunctionDefinition with a type discriminator, following the OpenAI tools API format for use in the tools field of ChatCompletionRequest.

type#

The tool type identifier, currently always "function".

Type: str

function#

The FunctionDefinition describing the callable tool.

Type: calute.types.oai_protocols.FunctionDefinition

function: FunctionDefinition#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str#

class calute.types.oai_protocols.UsageInfo(*, prompt_tokens: int = 0, completion_tokens: int | None = 0, total_tokens: int = 0, tokens_per_second: float = 0, processing_time: float = 0.0, **extra_data: Any)[source]#

Bases: OpenAIBaseModel

Token usage statistics and performance metrics for a request.

Tracks computational resources consumed during a chat or text completion request, including token counts and timing information.

prompt_tokens#

Number of tokens in the input prompt.

Type: int

completion_tokens#

Number of tokens generated in the response. May be None for streaming responses where the count is not yet finalized.

Type: int | None

total_tokens#

Total token count (sum of prompt and completion tokens).

Type: int

tokens_per_second#

Token generation throughput in tokens per second.

Type: float

processing_time#

Total wall-clock processing time in seconds.

Type: float

completion_tokens: int | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

processing_time: float#

prompt_tokens: int#

tokens_per_second: float#

total_tokens: int#

calute.types.oai_protocols

Contents

calute.types.oai_protocols#