Struct ChatCompletionChunk 

pub struct ChatCompletionChunk { /* private fields */ }

A streaming chunk from a chat completion response.

Each chunk represents a delta update from the model as it generates the response.

Implementations

impl ChatCompletionChunk

pub fn new(response: CreateChatCompletionStreamResponse) -> Self

Create a new chunk from a stream response.

pub fn content(&self) -> Option<&str>

Get the content delta from this chunk, if any.

Returns the text content that was generated in this chunk.

Examples found in repository

examples/chat_streaming.rs (line 59)

async fn basic_streaming(client: &Client) -> Result<()> {
    println!("Question: Tell me a short joke");

    let builder = client.chat().user("Tell me a short joke");

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Response: ");
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
        }
    }
    println!();

    Ok(())
}

async fn streaming_with_parameters(client: &Client) -> Result<()> {
    println!("Question: Write a creative tagline for a bakery");

    let builder = client
        .chat()
        .user("Write a creative tagline for a bakery")
        .temperature(0.9)
        .max_tokens(50);

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Response: ");
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
        }
    }
    println!();

    Ok(())
}

async fn collect_content(client: &Client) -> Result<()> {
    println!("Question: What is the capital of France?");

    let builder = client.chat().user("What is the capital of France?");

    let mut stream = client.send_chat_stream(builder).await?;

    // Manually collect all content
    let mut content = String::new();
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(text) = chunk.content() {
            content.push_str(text);
        }
    }
    println!("Full response: {}", content);

    Ok(())
}

async fn streaming_with_system(client: &Client) -> Result<()> {
    println!("System: You are a helpful assistant that speaks like a pirate");
    println!("Question: Tell me about the weather");

    let builder = client
        .chat()
        .system("You are a helpful assistant that speaks like a pirate")
        .user("Tell me about the weather")
        .max_tokens(100);

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Response: ");
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
        }
    }
    println!();

    Ok(())
}

async fn multiple_turns(client: &Client) -> Result<()> {
    println!("Building a conversation with multiple turns...\n");

    // First turn
    println!("User: What is 2+2?");
    let builder = client.chat().user("What is 2+2?");

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Assistant: ");
    let mut first_response = String::new();
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
            first_response.push_str(content);
        }
    }
    println!();

    // Second turn - continuing the conversation
    println!("\nUser: Now multiply that by 3");
    let builder = client
        .chat()
        .user("What is 2+2?")
        .assistant(&first_response)
        .user("Now multiply that by 3");

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Assistant: ");
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
        }
    }
    println!();

    Ok(())
}

examples/langfuse_streaming.rs (line 105)

async fn basic_streaming(client: &Client<LangfuseState<Span>>) -> Result<()> {
    println!("Question: Tell me a short joke");

    let builder = client.chat().user("Tell me a short joke");

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Response: ");
    let mut chunk_count = 0;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
            chunk_count += 1;
        }
    }
    println!(
        "\n(Received {} chunks, all traced to Langfuse)",
        chunk_count
    );

    Ok(())
}

async fn streaming_with_parameters(client: &Client<LangfuseState<Span>>) -> Result<()> {
    println!("Question: Write a creative tagline for a bakery");

    let builder = client
        .chat()
        .user("Write a creative tagline for a bakery")
        .temperature(0.9)
        .max_tokens(50);

    let mut stream = client.send_chat_stream(builder).await?;

    print!("Response: ");
    let mut chunk_count = 0;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(content) = chunk.content() {
            print!("{}", content);
            chunk_count += 1;
        }
    }
    println!(
        "\n(Received {} chunks, all traced to Langfuse)",
        chunk_count
    );

    Ok(())
}

async fn collect_content(client: &Client<LangfuseState<Span>>) -> Result<()> {
    println!("Question: What is the capital of France?");

    let builder = client.chat().user("What is the capital of France?");

    let mut stream = client.send_chat_stream(builder).await?;

    // Manually collect content (interceptor hooks are still called for each chunk)
    let mut content = String::new();
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        if let Some(text) = chunk.content() {
            content.push_str(text);
        }
    }
    println!("Full response: {}", content);
    println!("(All chunks were traced to Langfuse during collection)");

    Ok(())
}

examples/quickstart.rs (line 146)

async fn main() -> Result<()> {
    // Initialize logging to see what's happening under the hood
    tracing_subscriber::fmt().with_env_filter("info").init();

    println!(" OpenAI Ergonomic Quickstart");
    println!("==============================\n");

    // ==========================================
    // 1. ENVIRONMENT SETUP & CLIENT CREATION
    // ==========================================

    println!(" Step 1: Setting up the client");

    // The simplest way to get started - reads OPENAI_API_KEY from environment
    let client = match Client::from_env() {
        Ok(client_builder) => {
            println!(" Client created successfully!");
            client_builder.build()
        }
        Err(e) => {
            eprintln!(" Failed to create client: {e}");
            eprintln!(" Make sure you've set OPENAI_API_KEY environment variable");
            eprintln!("   Example: export OPENAI_API_KEY=\"sk-your-key-here\"");
            return Err(e);
        }
    };

    // ==========================================
    // 2. BASIC CHAT COMPLETION
    // ==========================================

    println!("\n Step 2: Basic chat completion");

    // The simplest way to get a response from ChatGPT
    let builder = client.chat_simple("What is Rust programming language in one sentence?");
    let response = client.send_chat(builder).await;

    match response {
        Ok(chat_response) => {
            println!(" Got response!");
            if let Some(content) = chat_response.content() {
                println!(" AI: {content}");
            }

            // Show usage information for cost tracking
            if let Some(usage) = &chat_response.inner().usage {
                println!(
                    " Usage: {} prompt + {} completion = {} total tokens",
                    usage.prompt_tokens, usage.completion_tokens, usage.total_tokens
                );
            }
        }
        Err(e) => {
            println!(" Chat completion failed: {e}");
            // Continue with other examples even if this one fails
        }
    }

    // ==========================================
    // 3. CHAT WITH SYSTEM MESSAGE
    // ==========================================

    println!("\n Step 3: Chat with system context");

    // System messages help set the AI's behavior and context
    let builder = client.chat_with_system(
        "You are a helpful coding mentor who explains things simply",
        "Explain what a HashMap is in Rust",
    );
    let response = client.send_chat(builder).await;

    match response {
        Ok(chat_response) => {
            println!(" Got contextual response!");
            if let Some(content) = chat_response.content() {
                println!("‍ Mentor: {content}");
            }
        }
        Err(e) => {
            println!(" Contextual chat failed: {e}");
        }
    }

    // ==========================================
    // 4. STREAMING RESPONSES
    // ==========================================

    println!("\n Step 4: Streaming response (real-time)");

    // Streaming lets you see the response as it's being generated
    // This is great for chatbots and interactive applications
    print!(" AI is typing: ");
    io::stdout().flush().unwrap();

    let builder = client
        .responses()
        .user("Write a short haiku about programming")
        .temperature(0.7);

    // Use send_responses_stream for real streaming
    let stream_result = client.send_responses_stream(builder).await;

    match stream_result {
        Ok(mut stream) => {
            // Process each chunk as it arrives
            while let Some(chunk_result) = stream.next().await {
                match chunk_result {
                    Ok(chunk) => {
                        if let Some(content) = chunk.content() {
                            print!("{content}");
                            io::stdout().flush().unwrap();
                        }
                    }
                    Err(e) => {
                        println!("\n Error processing chunk: {e}");
                        break;
                    }
                }
            }
            println!(); // New line after streaming
        }
        Err(e) => {
            println!("\n Failed to get streaming response: {e}");
        }
    }

    // ==========================================
    // 5. FUNCTION/TOOL CALLING
    // ==========================================

    println!("\n Step 5: Using tools/functions");

    // Tools let the AI call external functions to get real data
    // Here we define a weather function as an example
    let weather_tool = tool_function(
        "get_current_weather",
        "Get the current weather for a given location",
        json!({
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city name, e.g. 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["location"]
        }),
    );

    let builder = client
        .responses()
        .user("What's the weather like in Tokyo?")
        .tool(weather_tool);
    let response = client.send_responses(builder).await;

    match response {
        Ok(chat_response) => {
            println!(" Got response with potential tool calls!");

            // Check if the AI wants to call our weather function
            let tool_calls = chat_response.tool_calls();
            if !tool_calls.is_empty() {
                println!(" AI requested tool calls:");
                for tool_call in tool_calls {
                    let function_name = tool_call.function_name();
                    println!("   Function: {function_name}");
                    let function_args = tool_call.function_arguments();
                    println!("   Arguments: {function_args}");

                    // In a real app, you'd execute the function here
                    // and send the result back to the AI
                    println!("    In a real app, you'd call your weather API here");
                }
            } else if let Some(content) = chat_response.content() {
                println!(" AI: {content}");
            }
        }
        Err(e) => {
            println!(" Tool calling example failed: {e}");
        }
    }

    // ==========================================
    // 6. ERROR HANDLING PATTERNS
    // ==========================================

    println!("\n Step 6: Error handling patterns");

    // Show how to handle different types of errors gracefully
    let builder = client.chat_simple(""); // Empty message might cause an error
    let bad_response = client.send_chat(builder).await;

    match bad_response {
        Ok(response) => {
            println!(" Unexpectedly succeeded with empty message");
            if let Some(content) = response.content() {
                println!(" AI: {content}");
            }
        }
        Err(Error::Api {
            status, message, ..
        }) => {
            println!(" API Error (HTTP {status}):");
            println!("   Message: {message}");
            println!(" This is normal - we sent an invalid request");
        }
        Err(Error::RateLimit { .. }) => {
            println!(" Rate limited - you're sending requests too fast");
            println!(" In a real app, you'd implement exponential backoff");
        }
        Err(Error::Http(_)) => {
            println!(" HTTP/Network error");
            println!(" Check your internet connection and API key");
        }
        Err(e) => {
            println!(" Other error: {e}");
        }
    }

    // ==========================================
    // 7. COMPLETE REAL-WORLD EXAMPLE
    // ==========================================

    println!("\n Step 7: Complete real-world example");
    println!("Building a simple AI assistant that can:");
    println!("- Answer questions with context");
    println!("- Track conversation costs");
    println!("- Handle errors gracefully");

    let mut total_tokens = 0;

    // Simulate a conversation with context and cost tracking
    let questions = [
        "What is the capital of France?",
        "What's special about that city?",
        "How many people live there?",
    ];

    for (i, question) in questions.iter().enumerate() {
        println!("\n User: {question}");

        let builder = client
            .responses()
            .system(
                "You are a knowledgeable geography expert. Keep answers concise but informative.",
            )
            .user(*question)
            .temperature(0.1); // Lower temperature for more factual responses
        let response = client.send_responses(builder).await;

        match response {
            Ok(chat_response) => {
                if let Some(content) = chat_response.content() {
                    println!(" Assistant: {content}");
                }

                // Track token usage for cost monitoring
                if let Some(usage) = chat_response.usage() {
                    total_tokens += usage.total_tokens;
                    println!(
                        " This exchange: {} tokens (Running total: {})",
                        usage.total_tokens, total_tokens
                    );
                }
            }
            Err(e) => {
                println!(" Question {} failed: {}", i + 1, e);
                // In a real app, you might retry or log this error
            }
        }
    }

    // ==========================================
    // 8. WRAP UP & NEXT STEPS
    // ==========================================

    println!("\n Quickstart Complete!");
    println!("======================");
    println!("You've successfully:");
    println!(" Created an OpenAI client");
    println!(" Made basic chat completions");
    println!(" Used streaming responses");
    println!(" Implemented tool/function calling");
    println!(" Handled errors gracefully");
    println!(" Built a complete conversational AI");
    println!("\n Total tokens used in examples: {total_tokens}");
    println!(
        " Estimated cost: ~${:.4} (assuming GPT-4 pricing)",
        f64::from(total_tokens) * 0.03 / 1000.0
    );

    println!("\n Next Steps:");
    println!("- Check out other examples in the examples/ directory");
    println!("- Read the documentation: https://docs.rs/openai-ergonomic");
    println!("- Explore advanced features like vision, audio, and assistants");
    println!("- Build your own AI-powered applications!");

    Ok(())
}

pub fn role(&self) -> Option<&str>

Get the role from this chunk, if any.

This is typically only present in the first chunk.

pub fn tool_calls(&self) -> Option<&Vec<ChatCompletionMessageToolCallChunk>>

Get tool calls from this chunk, if any.

pub fn finish_reason(&self) -> Option<&str>

Get the finish reason, if any.

This indicates why the generation stopped and is only present in the last chunk.

pub fn is_final(&self) -> bool

Check if this is the last chunk in the stream.

pub fn raw_response(&self) -> &CreateChatCompletionStreamResponse

Get the underlying raw response.

pub fn delta(&self) -> Option<&ChatCompletionStreamResponseDelta>

Get the delta object directly.

Trait Implementations

impl Clone for ChatCompletionChunk

fn clone(&self) -> ChatCompletionChunk

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChatCompletionChunk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.