OpenAI Client

This tutorial demonstrates using the OpenAI chat completions API via the unique_toolkit package.

Common Imports

In this documentation we skip some imports as the documentation provides working python code through the Entangled, where are imports are declared. A link to the an example using the code blocks presented in this documentation will be found at the bottom of this page.

Nevertheless, we list the common imports that are particular to the unique toolkit when working with the openAI client.

#openai_toolkit_imports

from unique_toolkit.app.unique_settings import UniqueSettings
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

OpenAI Client

First we need to get an obtain the client from openai using the utitlity method get_openai_client.

#get_openai_client

client = get_openai_client()

Determining the Model to be use

#toolkit_language_model

model = LanguageModelName.AZURE_GPT_4o_2024_1120

Building the messages

We encourag the usage of the OpenAIMessageBuilder and the fluent builder pattern as it avoids a long list of imports and helps with typing.

#openai_chat_completion_messages

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages

Using the client

Now we are ready to create our first completion using the OpenAI client via the completion API

#openai_chat_completion_simple_completion

# Simple Completion
response = client.chat.completions.create(
    messages=messages,
    model=model,
)
for c in response:
    print(c)

or via the responses API

#openai_response_simple

response = client.responses.create(
    model=model,
    input="Write a one-sentence bedtime story about a unicorn."
)

Structured Output

Structured output from the large language model can be obtained via pydantic models. Be sure that the model chosen at the top supports this capability.

#openai_chat_completion_structured_output

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


completion = client.beta.chat.completions.parse(
    model=model,
    messages=messages,
    response_format=CalendarEvent,
)
completion.choices[0].message.content

or via the response API

#openai_responses_structured_output

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


response = client.responses.parse(
    model=model,
    input=messages, # type: ignore
    text_format=CalendarEvent,
)

Function calling

Function calling enables agents and workflows to use tools. The below example shows how to define a function and how to pass it to the LLM.

#openai_tool_description

from pydantic import Field
from unique_toolkit import LanguageModelToolDescription

class WeatherParameters(BaseModel):
    model_config = {"extra": "forbid"}
    location: str = Field(description="City and country e.g. Bogotá, Colombia")

weather_tool_description = LanguageModelToolDescription(
    name="get_weather",
    description="Get current temperature for a given location.",
    parameters=WeatherParameters,
    strict=True,
)

weather_tool_description_toolkit= weather_tool_description.to_openai()

#openai_chat_completion_function_calling

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="What is the weather like in Paris today?")
).messages

completion = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=[weather_tool_description_toolkit],
)

completion.choices[0].message.tool_calls

or with the response API

#openai_responses_function_calling

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="What is the weather like in Paris today?")
).messages

weather_tool_description_toolkit = weather_tool_description.to_openai(mode="responses")

response = client.responses.create(
    model=model,
    tools=[weather_tool_description_toolkit], # type: ignore
    input=messages, # type: ignore

)

Roles

Newer models support the different kind of message roles system, user, assistant and developer. The former are well-known and a messages object usually follows the pattern

• system
• user
• assistant
• user
• assistant ...

The newer developer messages enable us to give additional hints to the model that can be hidden in the frontend.

#openai_chat_completion_developer_message

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages

completion = client.chat.completions.create(
    model=model,
    messages=messages,
)
print(completion.choices[0].message.content)

Full Examples Completions API (Click to expand)

Simple CompletionStructured OutputFunction Calling

# %%
from unique_toolkit import (
    LanguageModelName,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages
# Simple Completion
response = client.chat.completions.create(
    messages=messages,
    model=model,
)
for c in response:
    print(c)

# %%
from pydantic import BaseModel

from unique_toolkit import (
    LanguageModelName,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


completion = client.beta.chat.completions.parse(
    model=model,
    messages=messages,
    response_format=CalendarEvent,
)
completion.choices[0].message.content

# %%
from pydantic import BaseModel, Field

from unique_toolkit import (
    LanguageModelName,
    LanguageModelToolDescription,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()


class WeatherParameters(BaseModel):
    model_config = {"extra": "forbid"}
    location: str = Field(description="City and country e.g. Bogotá, Colombia")


weather_tool_description = LanguageModelToolDescription(
    name="get_weather",
    description="Get current temperature for a given location.",
    parameters=WeatherParameters,
    strict=True,
)

weather_tool_description_toolkit = weather_tool_description.to_openai()
messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="What is the weather like in Paris today?")
).messages

completion = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=[weather_tool_description_toolkit],
)

completion.choices[0].message.tool_calls

Full Examples Responses API (Click to expand)

Simple CompletionStructured OutputFunction Calling

# %%
from unique_toolkit import (
    LanguageModelName,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages

response = client.responses.create(
    model=model, input="Write a one-sentence bedtime story about a unicorn."
)

# %%
from pydantic import BaseModel

from unique_toolkit import (
    LanguageModelName,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()

messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="How is the weather in New York")
).messages


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


response = client.responses.parse(
    model=model,
    input=messages,  # type: ignore
    text_format=CalendarEvent,
)

# %%
from pydantic import BaseModel, Field

from unique_toolkit import (
    LanguageModelName,
    LanguageModelToolDescription,
)
from unique_toolkit.framework_utilities.openai.client import get_openai_client
from unique_toolkit.framework_utilities.openai.message_builder import (
    OpenAIMessageBuilder,
)

model = LanguageModelName.AZURE_GPT_4o_2024_1120
client = get_openai_client()


class WeatherParameters(BaseModel):
    model_config = {"extra": "forbid"}
    location: str = Field(description="City and country e.g. Bogotá, Colombia")


weather_tool_description = LanguageModelToolDescription(
    name="get_weather",
    description="Get current temperature for a given location.",
    parameters=WeatherParameters,
    strict=True,
)

weather_tool_description_toolkit = weather_tool_description.to_openai()
messages = (
    OpenAIMessageBuilder()
    .system_message_append(content="You are a helpful assistant")
    .user_message_append(content="What is the weather like in Paris today?")
).messages

weather_tool_description_toolkit = weather_tool_description.to_openai(mode="responses")

response = client.responses.create(
    model=model,
    tools=[weather_tool_description_toolkit],  # type: ignore
    input=messages,  # type: ignore
)