Struct ChatCompletion

pub struct ChatCompletion {
    pub request_body: ChatCompletionRequestBody,
    /* private fields */
}

High-level client for OpenAI Chat Completion API.

This struct provides a convenient interface for making chat completion requests to the OpenAI API. It handles API key management, request building, and response parsing automatically.

Features

• Fluent API: Builder pattern for easy configuration
• Automatic Authentication: Reads API key from environment variables
• Error Handling: Comprehensive error messages for common issues
• Type Safety: Strongly typed parameters and responses

Environment Variables

The client requires the OPENAI_API_KEY environment variable to be set. This can be done through a .env file or system environment variables.

Example

use openai_tools::chat::ChatCompletion;
use openai_tools::common::Message;

let mut chat = ChatCompletion::new();

let response = chat
    .model_id("gpt-4o-mini".to_string())
    .messages(vec![Message::from_string("user".to_string(), "Hello!".to_string())])
    .temperature(0.7)
    .chat()
    .await?;

println!("{}", response.choices[0].message.content);

Fields

request_body: ChatCompletionRequestBody

Implementations

impl ChatCompletion

pub fn new() -> Self

Creates a new ChatCompletion client instance.

This constructor automatically loads environment variables from a .env file (if present) and retrieves the OpenAI API key from the OPENAI_API_KEY environment variable.

Panics

Panics if the OPENAI_API_KEY environment variable is not set.

Returns

A new ChatCompletion instance ready for configuration and use.

Example

use openai_tools::chat::ChatCompletion;

// Ensure OPENAI_API_KEY is set in environment or .env file
let chat = ChatCompletion::new();

pub fn model_id(&mut self, model_id: String) -> &mut Self

Sets the model ID for the chat completion request.

Arguments

• model_id - The ID of the OpenAI model to use (e.g., “gpt-4o-mini”, “gpt-4”, “gpt-3.5-turbo”)

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.model_id("gpt-4o-mini".to_string());

pub fn messages(&mut self, messages: Vec<Message>) -> &mut Self

Sets the conversation messages for the chat completion request.

Arguments

• messages - A vector of Message objects representing the conversation history

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
let messages = vec![
    Message::from_string("system".to_string(), "You are a helpful assistant.".to_string()),
    Message::from_string("user".to_string(), "Hello!".to_string()),
];
chat.messages(messages);

pub fn store(&mut self, store: bool) -> &mut Self

Sets whether to store the output of this chat completion request.

Arguments

• store - Whether to store the output for the user

Returns

A mutable reference to self for method chaining.

pub fn frequency_penalty(&mut self, frequency_penalty: f32) -> &mut Self

Sets the frequency penalty for the chat completion request.

Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.

Arguments

• frequency_penalty - Number between -2.0 and 2.0

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.frequency_penalty(0.5); // Reduce repetition

pub fn logit_bias(&mut self, logit_bias: FxHashMap<String, i32>) -> &mut Self

Sets logit bias to modify the likelihood of specified tokens appearing.

Arguments

• logit_bias - Maps tokens (as strings) to bias values from -100 to 100

Returns

A mutable reference to self for method chaining.

pub fn logprobs(&mut self, logprobs: bool) -> &mut Self

Sets whether to return log probabilities of the output tokens.

Arguments

• logprobs - Whether to return log probabilities

Returns

A mutable reference to self for method chaining.

pub fn top_logprobs(&mut self, top_logprobs: u8) -> &mut Self

Sets the number of most likely tokens to return at each token position.

Arguments

• top_logprobs - Number between 0 and 20

Returns

A mutable reference to self for method chaining.

pub fn max_completion_tokens(&mut self, max_completion_tokens: u64) -> &mut Self

Sets the maximum number of tokens that can be generated for a completion.

Arguments

• max_completion_tokens - Maximum number of tokens to generate

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.max_completion_tokens(150); // Limit response to 150 tokens

pub fn n(&mut self, n: u32) -> &mut Self

Sets how many chat completion choices to generate for each input message.

Arguments

• n - Number of choices to generate (default is 1)

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.n(3); // Generate 3 different responses

pub fn modalities(&mut self, modalities: Vec<String>) -> &mut Self

Sets the output types that the model should generate for this request.

Arguments

• modalities - Vector of output types (e.g., [“text”] for most models)

Returns

A mutable reference to self for method chaining.

pub fn presence_penalty(&mut self, presence_penalty: f32) -> &mut Self

Sets the presence penalty for the chat completion request.

Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics.

Arguments

• presence_penalty - Number between -2.0 and 2.0

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.presence_penalty(0.6); // Encourage talking about new topics

pub fn temperature(&mut self, temperature: f32) -> &mut Self

Sets the sampling temperature for the chat completion request.

Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

Arguments

• temperature - Number between 0 and 2

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
chat.temperature(0.7); // Balanced creativity and consistency

pub fn response_format( &mut self, response_format: ChatCompletionResponseFormat, ) -> &mut Self

Sets the response format for structured outputs.

This is used to ensure the model returns data in a specific JSON schema format, enabling structured data extraction from the model’s responses.

Arguments

• response_format - The response format specification including JSON schema

Returns

A mutable reference to self for method chaining.

Example

let mut chat = ChatCompletion::new();
let mut schema = Schema::chat_json_schema("person".to_string());
schema.add_property("name".to_string(), "string".to_string(), None);

let format = ChatCompletionResponseFormat::new("json_schema".to_string(), schema);
chat.response_format(format);

pub async fn chat(&mut self) -> Result<ChatCompletionResponse>

Executes the chat completion request.

This method sends the configured request to the OpenAI Chat Completion API and returns the response. It performs validation on required fields before making the request.

Returns

• Ok(ChatCompletionResponse) - The successful response from the API
• Err(anyhow::Error) - An error if the request fails or validation fails

Errors

This method will return an error if:

• The API key is not set or empty
• The model ID is not set or empty
• No messages have been provided
• The HTTP request fails
• The response cannot be parsed as JSON
• The API returns a non-success status code

Example

let mut chat = ChatCompletion::new();

let response = chat
    .model_id("gpt-4o-mini".to_string())
    .messages(vec![Message::from_string("user".to_string(), "Hello!".to_string())])
    .chat()
    .await?;

println!("Response: {}", response.choices[0].message.content);
println!("Tokens used: {}", response.usage.total_tokens.unwrap_or(0));