GitHub

Chat Completions API

Types and functions for the Chat Completions API.

Chat Object

UniLM.Chat — Type
chat = Chat()

Creates a new Chat object with default settings:

  • model is set to gpt-5.2
  • messages is set to an empty Vector{Message}
  • history is set to true
source

Messages

UniLM.Message — Type
Message(; role, content=nothing, name=nothing, finish_reason=nothing, refusal_message=nothing, tool_calls=nothing, tool_call_id=nothing)

Represents a single message in a Chat Completions conversation.

Fields

  • role::String: One of RoleSystem, RoleUser, RoleAssistant, or RoleTool.
  • content::Union{String,Nothing}: The text content of the message.
  • name::Union{String,Nothing}: Optional name for the participant.
  • finish_reason::Union{String,Nothing}: Why the model stopped generating (e.g. "stop", "tool_calls").
  • refusal_message::Union{String,Nothing}: Refusal text when content is filtered.
  • tool_calls::Union{Nothing,Vector{GPTToolCall}}: Tool calls requested by the assistant.
  • tool_call_id::Union{String,Nothing}: Required when role is "tool" — the ID of the tool call being responded to.

Validation

  • At least one of content, tool_calls, or refusal_message must be non-nothing.
  • tool_call_id is required when role == "tool".

Convenience Constructors

Message(Val(:system), "You are a helpful assistant")
Message(Val(:user), "Hello!")
source

Convenience Constructors

using UniLM

sys = Message(Val(:system), "You are a helpful assistant")
usr = Message(Val(:user), "Hello!")
println("System role: ", sys.role)
println("User role: ", usr.role)
println("User content: ", usr.content)
System role: system
User role: user
User content: Hello!

Conversation Management

UniLM.issendvalid — Function
is_send_valid(chat::Chat)::Bool

Check if the conversation is valid for sending to the API.

This check employs a rough heuristic that works for practical purposes. 
        
It checks if the conversation has at least two messages, the first message is from the system, the last message is from the user, and there are no consecutive messages from the same role. However, this is not a foolproof check and may not work in all cases (e.g. imagine that you passed another system message in the middle of the conversation).
source
UniLM.update! — Function
update!(chat::Chat, msg::Message)

Update the chat with a new message.
source

Building a Conversation

chat = Chat(model="gpt-5.2")
push!(chat, Message(Val(:system), "You are a helpful assistant"))
push!(chat, Message(Val(:user), "What is Julia?"))
println("Messages: ", length(chat))
println("Valid for sending: ", issendvalid(chat))
Messages: 2
Valid for sending: true

Tools

UniLM.GPTTool — Type
GPTTool(; type="function", func)

Wraps a GPTFunctionSignature for use in the tools parameter of a Chat.

Example

tool = GPTTool(func=GPTFunctionSignature(
    name="get_weather",
    description="Get the current weather",
    parameters=Dict("type" => "object", "properties" => Dict())
))
chat = Chat(tools=[tool])
source
UniLM.GPTFunctionSignature — Type
GPTFunctionSignature(; name, description=nothing, parameters=nothing)

Describes a function that can be called by the model in the Chat Completions API.

Fields

  • name::String: The name of the function.
  • description::Union{String,Nothing}: A description of what the function does.
  • parameters::Union{AbstractDict,Nothing}: JSON Schema object describing the function parameters.

Example

sig = GPTFunctionSignature(
    name="get_weather",
    description="Get the current weather in a given location",
    parameters=Dict(
        "type" => "object",
        "properties" => Dict(
            "location" => Dict("type" => "string", "description" => "The city")
        ),
        "required" => ["location"]
    )
)
source
UniLM.GPTToolCall — Type
GPTToolCall(; id, type="function", func)

Represents a tool call returned by the model. Contains the call id (used to match results back), the tool type, and the [GPTFunction] with name and parsed arguments.

source
UniLM.GPTFunctionCallResult — Type
GPTFunctionCallResult{T}

Holds the result of executing a function that was requested by the model via a tool call.

Fields

  • name::Union{String,Symbol}: The function name.
  • origincall::GPTFunction: The original [GPTFunction] call from the model.
  • result::T: The result of executing the function.
source

Output Format

UniLM.ResponseFormat — Type
ResponseFormat(; type="json_object", json_schema=nothing)
ResponseFormat(json_schema)

Specifies the output format for Chat Completions.

Fields

  • type::String: "json_object" or "json_schema".
  • json_schema::Union{JsonSchemaAPI,AbstractDict,Nothing}: Schema definition when type is "json_schema".

Examples

# Free-form JSON
fmt = ResponseFormat()

# Structured JSON via schema
fmt = ResponseFormat(JsonSchemaAPI(
    name="result",
    description="A structured result",
    schema=Dict("type" => "object", "properties" => Dict())
))
Note

Use the convenience constructors json_object() and json_schema() for cleaner code.

source
using JSON

# JSON object format
fmt = ResponseFormat()
println("Type: ", fmt.type)
println("JSON: ", JSON.json(fmt))
Type: json_object
JSON: {"type":"json_object"}

Request Function

UniLM.chatrequest! — Function
chatrequest!(chat::Chat, retries=0, callback=nothing)

Send a request to the OpenAI API to generate a response to the messages in conv.

The callback function is called for each chunk of the response. The close Ref is also passed to the callback function, which can be used to close the stream (for example when not satisfied with the intermediate results and want to stop the stream).

The signature of the callback function is:
    `callback(chunk::Union{String, Message}, close::Ref{Bool})`
source

Flexible keyword arguments usage

chatrequest!(; kwargs...) Send a request to the OpenAI API to generate a response to the messages in conv.

Keyword Arguments

  • service::Type{<:ServiceEndpoint} = AZUREServiceEndpoint: The service endpoint to use (e.g., AZUREServiceEndpoint, OPENAIServiceEndpoint).
  • model::String = "gpt-5.2": The model to use for the chat completion.
  • systemprompt::Union{Message,String}: The system prompt message.
  • userprompt::Union{Message,String}: The user prompt message.
  • messages::Conversation = Message[]: The conversation history or the system/prompt messages.
  • history::Bool = true: Whether to include the conversation history in the request.
  • tools::Union{Vector{GPTTool},Nothing} = nothing: A list of tools the model may call.
  • tool_choice::Union{String,GPTToolChoice,Nothing} = nothing: Controls which (if any) function is called by the model. e.g. "auto", "none", GPTToolChoice.
  • parallel_tool_calls::Union{Bool,Nothing} = false: Whether to enable parallel function calling.
  • temperature::Union{Float64,Nothing} = nothing: Sampling temperature (0.0-2.0). Higher values make output more random. Mutually exclusive with top_p.
  • top_p::Union{Float64,Nothing} = nothing: Nucleus sampling parameter (0.0-1.0). Mutually exclusive with temperature.
  • n::Union{Int64,Nothing} = nothing: How many chat completion choices to generate for each input message (1-10).
  • stream::Union{Bool,Nothing} = nothing: If set, partial message deltas will be sent, like in ChatGPT.
  • stop::Union{Vector{String},String,Nothing} = nothing: Up to 4 sequences where the API will stop generating further tokens.
  • max_tokens::Union{Int64,Nothing} = nothing: The maximum number of tokens to generate in the chat completion.
  • presence_penalty::Union{Float64,Nothing} = nothing: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.
  • response_format::Union{ResponseFormat,Nothing} = nothing: An object specifying the format that the model must output. e.g., ResponseFormat(type="json_object").
  • frequency_penalty::Union{Float64,Nothing} = nothing: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far.
  • logit_bias::Union{AbstractDict{String,Float64},Nothing} = nothing: Modify the likelihood of specified tokens appearing in the completion.
  • user::Union{String,Nothing} = nothing: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
  • seed::Union{Int64,Nothing} = nothing: This feature is in Beta. If specified, the system will make a best effort to sample deterministically.
source

Role Constants

Tool Loop

UniLM.CallableTool — Type
CallableTool{T}(tool, callable)

Wraps a tool schema T (GPTTool or FunctionTool) with a callable. JSON serialization delegates to the inner tool, preserving backward compatibility.

Fields

  • tool::T: The tool schema.
  • callable::Function: (name::String, args::Dict{String,Any}) -> String

Example

tool = GPTTool(func=GPTFunctionSignature(name="add", description="Add two numbers",
    parameters=Dict("type"=>"object","properties"=>Dict("a"=>Dict("type"=>"number"),"b"=>Dict("type"=>"number")))))
ct = CallableTool(tool, (name, args) -> string(args["a"] + args["b"]))
source
UniLM.ToolCallOutcome — Type
ToolCallOutcome

Per-call record from a tool dispatch.

Fields

  • tool_name::String: Name of the tool that was called.
  • arguments::Dict{String,Any}: Arguments passed to the tool.
  • result::Union{GPTFunctionCallResult,Nothing}: The result wrapper, or nothing on failure.
  • success::Bool: Whether the dispatch succeeded.
  • error::Union{String,Nothing}: Error message on failure.
source
UniLM.ToolLoopResult — Type
ToolLoopResult

Result of a tool dispatch loop.

Fields

  • response::LLMRequestResponse: The final API response.
  • tool_calls::Vector{ToolCallOutcome}: History of all tool dispatches.
  • turns_used::Int: Number of API round-trips.
  • completed::Bool: Whether the loop terminated normally (text response).
  • llm_error::Union{String,Nothing}: Error message if not completed.
source
UniLM.tool_loop! — Function
tool_loop!(chat::Chat, dispatcher::Function; max_turns=10, retries=0, callback=nothing, on_tool_call=nothing) -> ToolLoopResult

Run a tool-calling loop on a Chat. Repeatedly calls chatrequest!, dispatches tool calls via dispatcher(name, args), pushes tool-role messages back, and repeats until a text response, API error, or max_turns.

Arguments

  • dispatcher: (name::String, args::Dict{String,Any}) -> String
  • max_turns: Maximum API round-trips (default 10).
  • retries: Retry count passed to chatrequest!.
  • callback: Streaming callback passed to chatrequest!.
  • on_tool_call: Tool call notification callback passed to chatrequest!.

Example

chat = Chat(model="gpt-5-mini", tools=[tool])
push!(chat, Message(Val(:system), "You are a calculator"))
push!(chat, Message(Val(:user), "What is 3+5?"))
result = tool_loop!(chat, (name, args) -> string(args["a"] + args["b"]))
source
tool_loop!(chat::Chat; tools::Vector{<:CallableTool}, kwargs...) -> ToolLoopResult

No-dispatcher variant: builds a dispatcher from CallableTool entries.

source
UniLM.tool_loop — Function
tool_loop(r::Respond, dispatcher::Function; max_turns=10, retries=0) -> ToolLoopResult

Run a tool-calling loop on a Respond request. Dispatches function calls via dispatcher(name, args), builds function_call_output input items, and chains via previous_response_id.

source
tool_loop(r::Respond; max_turns=10, retries=0) -> ToolLoopResult

No-dispatcher variant: extracts callables from CallableTool entries in r.tools.

source
tool_loop(input, dispatcher::Function; tools, kwargs...) -> ToolLoopResult

Convenience form: creates a Respond and runs the tool loop.

source
UniLM.to_tool — Function
to_tool(x)

Overloadable conversion protocol. Identity for GPTTool, FunctionTool, CallableTool. Converts AbstractDict to GPTTool. Package extensions can add methods for other types.

source

Convert an MCPServerTool to a FunctionTool for use with the Responses API.

source

Model Constants

println("GPT5_2: ", UniLM.GPT5_2)
GPT5_2: gpt-5.2