yera.models.interfaces.llms.open_ai

Interface to OpenAI llms.

This module provides the OpenAILLM class for interacting with OpenAI's language models including GPT-4, GPT-4o, and newer variants. It supports both standard streaming chat completions and structured output generation. For models that support native structured outputs (GPT-4o from 2024-08-06+), uses the native response_format parameter. For older models, falls back to tool use with strict mode enforcement.

Symbols

class OpenAILLM — Interface to OpenAI llms.

OpenAILLM

Inherits: BaseLLMInterface
Subclasses: AzureOpenAILLM

Interface to OpenAI llms.

Provides a wrapper around the OpenAI API client, supporting GPT-4, GPT-4o, and newer models. Automatically detects whether the selected model supports native structured outputs (response_format) based on model identifier and release date. For models with native support, uses the response_format parameter. For older models, falls back to tool use with strict mode.

The client is lazily initialised on start() and must be explicitly shut down via stop().

Attributes

model_id
type: str

The identifier of the OpenAI model to use.

connection
type: OpenAIConnection

Connection configuration including API key.

struct_gen
type: bool

Whether the selected model supports native structured output generation.

client
type: OpenAI

Lazy-initialised OpenAI API client instance.

Methods

start — Initialise the OpenAI API client.
stop — Shut down and clear the OpenAI API client.
chat — Stream a chat completion response from OpenAI.
make_struct — Stream a structured output response conforming to a provided schema.

OpenAILLM.start

start() → None

Initialise the OpenAI API client.

Creates and stores an OpenAI client instance using the configured connection settings (API key, organisation, etc.). This method must be called before making any API requests via the client property.

OpenAILLM.stop

stop() → None

Shut down and clear the OpenAI API client.

Releases the OpenAI client instance by setting it to None. After calling this method, start() must be called again before further API requests can be made.

OpenAILLM.chat

chat(
    messages: list[Message],
    **openai_kw,
) → Iterator[str]

Stream a chat completion response from OpenAI.

Sends a conversation to the OpenAI API and streams the response as text tokens. Messages are converted to OpenAI's message format before being sent to the API.

Parameters

messages
type: list[Message]

List of Message objects representing the conversation history.

**openai_kw
type: str | float | int | bool

Additional keyword arguments passed to the OpenAI API (e.g., temperature, top_p, presence_penalty).

OpenAILLM.make_struct

make_struct(
    messages: list[Message],
    **openai_kw,
) → Iterator[str]

Stream a structured output response conforming to a provided schema.

Generates a response that strictly conforms to the structure defined by the provided Pydantic model class. For models supporting native structured outputs (GPT-4o from 2024-08-06+), uses the response_format parameter with strict mode. For older models, falls back to tool use with strict=true enforcement.

Parameters

messages
type: list[Message]

List of Message objects representing the conversation history.

cls
type: type[TStruct]

A Pydantic model class defining the desired output structure. The model will be transformed into a strict JSON schema for the API.

**openai_kw
type: str | float | int | bool

Additional keyword arguments passed to the OpenAI API (e.g., temperature, top_p).