Struct ChatCompletionBuilder 

pub struct ChatCompletionBuilder { /* private fields */ }

Builder for chat completion requests.

Implementations

impl ChatCompletionBuilder

pub fn new(model: impl Into<String>) -> Self

Create a new chat completion builder with the specified model.

Examples found in repository

examples/langfuse.rs (line 104)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for logging
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive("openai_ergonomic=debug".parse()?),
        )
        .init();

    // 1. Build Langfuse exporter from environment variables
    let exporter = ExporterBuilder::from_env()?.build()?;

    // 2. Create tracer provider with batch processor
    let provider = SdkTracerProvider::builder()
        .with_span_processor(BatchSpanProcessor::builder(exporter, Tokio).build())
        .build();

    // Set as global provider
    global::set_tracer_provider(provider.clone());

    // 3. Get tracer and create interceptor
    let tracer = provider.tracer("openai-ergonomic");
    let langfuse_interceptor =
        std::sync::Arc::new(LangfuseInterceptor::new(tracer, LangfuseConfig::new()));

    // 4. Create the OpenAI client and add the Langfuse interceptor
    // Keep a reference to the interceptor so we can update context later
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor.clone()))
        .build();

    println!(" OpenAI client initialized with Langfuse observability");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Example 1: Simple chat completion
    println!("Example 1: Simple chat completion");
    println!("---------------------------------");
    let chat_builder = client
        .chat_simple("What is the capital of France? Answer in one word.")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 2: Chat completion with builder pattern
    println!("Example 2: Chat with builder pattern");
    println!("-------------------------------------");
    let chat_builder = client
        .chat()
        .system("You are a helpful assistant that speaks like a pirate.")
        .user("Tell me about the ocean in 2 sentences.")
        .temperature(0.7)
        .max_tokens(100)
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 3: Multiple messages in a conversation
    println!("Example 3: Conversation");
    println!("-----------------------");
    let chat_builder = client
        .chat()
        .system("You are a math tutor.")
        .user("What is 2 + 2?")
        .assistant("2 + 2 equals 4.")
        .user("And what about 3 + 3?")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 4: Error handling (intentionally trigger an error)
    println!("Example 4: Error handling");
    println!("-------------------------");
    // Create a builder with a non-existent model
    let chat_builder = ChatCompletionBuilder::new("non-existent-model")
        .user("This should fail")
        .build()?;
    let result = client.execute_chat(chat_builder).await;

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(e) => println!("Expected error captured: {e}\n"),
    }

    // Example 5: Embeddings
    println!("Example 5: Embeddings");
    println!("--------------------");
    let embeddings_builder = client.embeddings().text(
        "text-embedding-ada-002",
        "The quick brown fox jumps over the lazy dog",
    );
    let embeddings = client.embeddings().create(embeddings_builder).await?;
    println!("Generated {} embedding(s)\n", embeddings.data.len());

    // Example 6: Using custom metadata via interceptor context
    println!("Example 6: Custom metadata via interceptor context");
    println!("---------------------------------------------------");

    // Set session and user IDs on the interceptor's context
    langfuse_interceptor.set_session_id("demo-session-123");
    langfuse_interceptor.set_user_id("demo-user-456");
    langfuse_interceptor.add_tags(vec!["example".to_string(), "demo".to_string()]);

    let chat_builder = client
        .chat_simple("Say 'Hello from custom session!'")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response with custom metadata: {:?}\n", response.content());

    // Clear context for subsequent calls
    langfuse_interceptor.clear_context();

    println!(" All examples completed!");
    println!(" Check your Langfuse dashboard to see the traces");
    println!("   - Look for traces with operation name 'chat'");
    println!("   - Each trace includes request/response details, token usage, and timing");
    println!("   - Example 6 will have custom session_id, user_id, and tags");

    // Shutdown the tracer provider to flush all spans
    println!("\n⏳ Flushing spans to Langfuse...");
    provider.shutdown()?;

    Ok(())
}

pub fn system(self, content: impl Into<String>) -> Self

Add a system message to the conversation.

Examples found in repository

examples/chat_streaming.rs (line 117)

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(())
}

examples/vision_chat.rs (line 89)

async fn demonstrate_basic_image_analysis(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 1: Basic Image Analysis");
    println!("----------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "What do you see in this image? Please describe it in detail.";

    println!("Image URL: {image_url}");
    println!("Question: {question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Use the convenient user_with_image_url method
    let chat_builder = client
        .chat()
        .system("You are a helpful AI assistant that can analyze images. Provide detailed, accurate descriptions of what you see.")
        .user_with_image_url(question, image_url)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Show usage information
        if let Some(usage) = response.usage() {
            println!("\n Token usage:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate analysis of multiple images in a single message.
async fn demonstrate_multiple_images(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multiple Image Analysis");
    println!("---------------------------------------");

    let question = "Compare these two images. What are the differences and similarities?";

    println!("Question: {question}");
    println!("Image 1: {}", SAMPLE_IMAGE_URLS[0]);
    println!("Image 2: {}", SAMPLE_IMAGE_URLS[1]);
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts manually for multiple images
    let parts = vec![
        text_part(question),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[0], Detail::Auto),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[1], Detail::Auto),
    ];

    let chat_builder = client
        .chat()
        .system("You are an expert at comparing and analyzing images. Provide thoughtful comparisons focusing on visual elements, composition, and content.")
        .user_with_parts(parts)
        .temperature(0.4);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate different detail levels for image analysis.
async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate base64 image encoding and analysis.
async fn demonstrate_base64_image(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Base64 Image Analysis");
    println!("-----------------------------------");

    let question = "What is this image? It's very small, what can you tell about it?";

    println!("Question: {question}");
    println!("Image: Small test image encoded as base64");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts with base64 image
    let parts = vec![
        text_part(question),
        image_base64_part_with_detail(SAMPLE_BASE64_IMAGE, "image/png", Detail::High),
    ];

    let chat_builder = client
        .chat()
        .system("You are analyzing images provided in base64 format. Even if an image is very small or simple, try to provide what information you can.")
        .user_with_parts(parts)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate conversation context with images.
async fn demonstrate_conversation_with_images(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 5: Conversation Context with Images");
    println!("----------------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];

    // First message: Analyze the image
    println!("Step 1: Initial image analysis");
    print!("Assistant: ");
    io::stdout().flush()?;

    let mut chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .temperature(0.3);

    let response1 = client.send_chat(chat_builder).await?;
    let first_response = response1.content().unwrap_or("No response").to_string();
    println!("{first_response}");

    // Second message: Follow-up question (without re-uploading the image)
    println!("\nStep 2: Follow-up question");
    print!("Assistant: ");
    io::stdout().flush()?;

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .temperature(0.3);

    let response2 = client.send_chat(chat_builder).await?;

    if let Some(content) = response2.content() {
        println!("{content}");
    }

    // Third message: Ask for creative interpretation
    println!("\nStep 3: Creative interpretation");
    print!("Assistant: ");
    io::stdout().flush()?;

    let second_response = response2.content().unwrap_or("No response").to_string();

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .assistant(second_response)
        .user("Based on our discussion, write a short poem inspired by this image.")
        .temperature(0.7);

    let response3 = client.send_chat(chat_builder).await?;

    if let Some(content) = response3.content() {
        println!("{content}");
    }

    println!();
    Ok(())
}

examples/moderations.rs (line 254)

async fn response_filtering(client: &Client) -> Result<()> {
    // Filter AI responses before showing to users

    println!("Generating and moderating AI responses:");

    // Generate response
    let prompt = "Tell me about technology";
    let builder = client.chat().user(prompt).max_completion_tokens(100);
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Generated response: '{}'", content);

        // Moderate the response
        let moderation_result = simulate_moderation(content);

        if moderation_result.flagged {
            println!(
                "  Response flagged! Categories: {:?}",
                moderation_result.categories
            );
            println!("Action: Response blocked or regenerated");

            // Regenerate with more strict instructions
            let safe_builder = client
                .chat()
                .system("Provide helpful, safe, and appropriate responses only.")
                .user(prompt)
                .max_completion_tokens(100);
            let safe_response = client.send_chat(safe_builder).await?;

            if let Some(safe_content) = safe_response.content() {
                println!("Regenerated safe response: '{}'", safe_content);
            }
        } else {
            println!(" Response passed moderation");
        }
    }

    Ok(())
}

examples/chat_comprehensive.rs (line 204)

async fn demonstrate_basic_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 1: Basic Chat Completion");
    println!("----------------------------------");

    let user_message = "Hello! Can you explain what you can help me with?";
    conversation.add_user_message(user_message.to_string());

    println!("User: {user_message}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build the chat request with conversation history
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat();

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {} // Ignore unknown roles
        }
    }

    // Send the request
    let response = client.send_chat(chat_builder.temperature(0.7)).await?;

    if let Some(content) = response.content() {
        println!("{content}");
        conversation.add_assistant_message(content.to_string(), None);

        // Track token usage if available
        if let Some(usage) = response.usage() {
            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate multi-turn conversation.
async fn demonstrate_multi_turn_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multi-turn Conversation");
    println!("------------------------------------");

    let questions = vec![
        "What's the capital of France?",
        "What's the population of that city?",
        "Can you tell me an interesting fact about it?",
    ];

    for question in questions {
        conversation.add_user_message(question.to_string());

        println!("User: {question}");
        print!("Assistant: ");
        io::stdout().flush()?;

        // Build chat request with full conversation history
        let messages = conversation.get_conversation_for_api();
        let mut chat_builder = client.chat();

        for (role, content) in messages {
            match role.as_str() {
                "system" => chat_builder = chat_builder.system(content),
                "user" => chat_builder = chat_builder.user(content),
                "assistant" => chat_builder = chat_builder.assistant(content),
                _ => {}
            }
        }

        let response = client.send_chat(chat_builder.temperature(0.3)).await?;

        if let Some(content) = response.content() {
            println!("{content}");
            conversation.add_assistant_message(content.to_string(), None);

            // Track token usage
            if let Some(usage) = response.usage() {
                conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
            }
        }

        println!();
        // Small delay between questions for readability
        tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

/// Demonstrate streaming chat response.
async fn demonstrate_streaming_chat(
    _client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Streaming Chat Response");
    println!("------------------------------------");

    // Add user message for streaming example
    let streaming_question = "Can you write a short poem about programming?";
    conversation.add_user_message(streaming_question.to_string());

    println!("User: {streaming_question}");
    println!("Assistant (streaming): ");

    // Note: Streaming is not yet fully implemented in the client
    // This is a placeholder showing the intended API
    println!(" Streaming functionality is being implemented...");
    println!("Future implementation will show real-time token-by-token responses");

    // Simulate what streaming would look like
    let simulated_response = "Programming flows like poetry in motion,\nEach function a verse, each loop a devotion.\nVariables dance through memory's halls,\nWhile algorithms answer logic's calls.";

    // Simulate typing effect
    for char in simulated_response.chars() {
        print!("{char}");
        io::stdout().flush()?;
        tokio::time::sleep(tokio::time::Duration::from_millis(30)).await;
    }
    println!("\n");

    // Add the response to conversation history
    conversation.add_assistant_message(simulated_response.to_string(), None);

    Ok(())
}

/// Demonstrate token usage tracking.
async fn demonstrate_token_tracking(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Token Usage Tracking");
    println!("---------------------------------");

    let efficiency_question = "In one sentence, what is machine learning?";
    conversation.add_user_message(efficiency_question.to_string());

    println!("User: {efficiency_question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build chat request
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat().max_completion_tokens(50); // Limit tokens for demo

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {}
        }
    }

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Display detailed token usage
        if let Some(usage) = response.usage() {
            println!("\n Token Usage Breakdown:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);

            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);

            conversation.add_assistant_message(content.to_string(), Some(usage.completion_tokens));
        } else {
            conversation.add_assistant_message(content.to_string(), None);
        }
    }

    println!();
    Ok(())
}

examples/azure_comprehensive.rs (line 63)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    println!("=== Azure OpenAI Comprehensive API Test ===\n");

    let client = Client::from_env()?.build();

    // Test 1: Simple chat completion
    println!("1. Testing simple chat completion...");
    let builder = client.chat_simple("What is 2+2? Answer in one word.");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Chat completion: {content}");
            }
        }
        Err(e) => println!("   ✗ Chat completion failed: {e}"),
    }

    // Test 2: Chat with system message
    println!("\n2. Testing chat with system message...");
    let builder = client.chat_with_system(
        "You are a helpful assistant that responds in one sentence.",
        "What is Rust?",
    );
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ System message chat: {content}");
            }
        }
        Err(e) => println!("   ✗ System message chat failed: {e}"),
    }

    // Test 3: Chat with temperature
    println!("\n3. Testing chat with custom parameters...");
    let builder = client
        .chat()
        .user("Say 'test' in a creative way")
        .temperature(0.7)
        .max_tokens(50);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Custom parameters: {content}");
            }
        }
        Err(e) => println!("   ✗ Custom parameters failed: {e}"),
    }

    // Test 4: Multiple messages conversation
    println!("\n4. Testing multi-message conversation...");
    let builder = client
        .chat()
        .system("You are a helpful assistant")
        .user("My name is Alice")
        .assistant("Hello Alice! Nice to meet you.")
        .user("What's my name?");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Multi-message: {content}");
            }
        }
        Err(e) => println!("   ✗ Multi-message failed: {e}"),
    }

    // Test 5: Chat with max_tokens limit
    println!("\n5. Testing with max_tokens limit...");
    let builder = client.chat().user("Explain quantum physics").max_tokens(20);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Limited tokens: {content}");
                println!("   (Note: response is truncated due to max_tokens=20)");
            }
        }
        Err(e) => println!("   ✗ Max tokens test failed: {e}"),
    }

    // Test 6: Using responses API
    println!("\n6. Testing responses API...");
    let builder = client.responses().user("What is the capital of France?");
    match client.send_responses(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Responses API: {content}");
            }
        }
        Err(e) => println!("   ✗ Responses API failed: {e}"),
    }

    println!("\n=== Test Summary ===");
    println!("Azure OpenAI integration tested across multiple endpoints!");
    println!("\nNote: Some advanced features like embeddings, streaming, and");
    println!("tool calling may require specific Azure OpenAI deployments.");

    Ok(())
}

examples/tool_calling_multiturn.rs (line 251)

async fn main() -> Result<()> {
    println!("=== Multi-turn Tool Calling Example ===\n");

    // Initialize client
    let client = Client::from_env()?.build();

    // Create storage for the memory tool
    let storage = Arc::new(Mutex::new(HashMap::new()));

    // Define available tools
    let tools = vec![get_calculator_tool(), get_memory_tool()];

    println!("Available tools:");
    println!("  - calculator: Perform arithmetic operations");
    println!("  - memory: Store and retrieve values");
    println!();

    // Example 1: Single tool call
    println!("Example 1: Single Tool Call");
    println!("User: What is 15 + 27?");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("What is 15 + 27?");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 2: Multiple sequential tool calls
    println!("\n\nExample 2: Multiple Sequential Tool Calls");
    println!("User: Calculate 10 * 5 and store the result in memory as 'product'");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("Calculate 10 * 5 and store the result in memory as 'product'");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 3: Retrieve from memory
    println!("\n\nExample 3: Retrieve from Memory");
    println!("User: What did I store in 'product'?");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("What did I store in 'product'?");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 4: Complex multi-step task
    println!("\n\nExample 4: Complex Multi-step Task");
    println!("User: Calculate 100 / 4, multiply that by 3, and tell me the final result");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("Calculate 100 / 4, multiply that by 3, and tell me the final result");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 5: Conversation with history
    println!("\n\nExample 5: Conversation with History");
    {
        let mut chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.");

        // First question
        println!("User: What is 8 + 7?");
        chat_builder = chat_builder.user("What is 8 + 7?");
        let result = handle_tool_loop(&client, chat_builder.clone(), &tools, &storage).await?;
        println!("Assistant: {}", result);

        // Add assistant response to history
        chat_builder = chat_builder.assistant(&result);

        // Follow-up question that depends on previous context
        println!("\nUser: Now multiply that by 3");
        chat_builder = chat_builder.user("Now multiply that by 3");
        let result = handle_tool_loop(&client, chat_builder.clone(), &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    println!("\n\n=== All examples completed successfully ===");
    println!("\nKey Takeaway:");
    println!("  When implementing multi-turn tool calling, ALWAYS use");
    println!("  assistant_with_tool_calls() to maintain proper conversation");
    println!("  history. This is essential for the model to understand the");
    println!("  tool results and continue the conversation correctly.");

    Ok(())
}

Additional examples can be found in:

• examples/langfuse.rs

pub fn user(self, content: impl Into<String>) -> Self

Add a user message to the conversation.

Examples found in repository

examples/chat_streaming.rs (line 52)

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 97)

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/tool_calling.rs (line 131)

async fn simple_tool_call(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("What's the weather like in San Francisco?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        for tool_call in tool_calls {
            println!("Tool called: {}", tool_call.function_name());
            println!("Arguments: {}", tool_call.function_arguments());

            // Execute the function
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("Function result: {}", result);
        }
    }

    Ok(())
}

async fn multiple_tools(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("What's the weather in NYC and what time is it there?")
        .tools(vec![get_weather_tool(), get_time_tool()]);
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        match tool_call.function_name() {
            "get_weather" => {
                let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
                let result = execute_weather_function(params)?;
                println!("Weather result: {}", result);
            }
            "get_current_time" => {
                let params: serde_json::Value =
                    serde_json::from_str(tool_call.function_arguments())?;
                if let Some(timezone) = params["timezone"].as_str() {
                    let result = execute_time_function(timezone);
                    println!("Time result: {}", result);
                }
            }
            _ => println!("Unknown tool: {}", tool_call.function_name()),
        }
    }

    Ok(())
}

async fn tool_choice_control(client: &Client) -> Result<()> {
    // Force specific tool
    println!("Forcing weather tool:");
    let builder = client
        .chat()
        .user("Tell me about Paris")
        .tools(vec![get_weather_tool(), get_time_tool()])
        .tool_choice(ToolChoiceHelper::specific("get_weather"));
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        println!("Forced tool: {}", tool_call.function_name());
    }

    // Disable tools
    println!("\nDisabling tools:");
    let builder = client
        .chat()
        .user("What's the weather?")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::none());
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Response without tools: {}", content);
    }

    Ok(())
}

async fn conversation_with_tools(client: &Client) -> Result<()> {
    // This example demonstrates proper multi-turn tool calling with full message history

    println!("=== Conversation with Tools (Full Implementation) ===");

    // Initialize the conversation
    let mut builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);

    // First request - the model will call the tool
    let response = client.send_chat(builder.clone()).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!("Step 1: Model requests tool call");
        for tool_call in &tool_calls {
            println!("  Tool: {}", tool_call.function_name());
            println!("  Args: {}", tool_call.function_arguments());
        }

        // IMPORTANT: Add the assistant's response (with tool calls) to the history
        // This is the key step for maintaining proper conversation context!
        builder = builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute the tools and add results
        println!("\nStep 2: Execute tools and add results to conversation");
        for tool_call in tool_calls {
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("  Tool result: {}", result);

            // Add the tool result to the conversation history
            builder = builder.tool(tool_call.id(), result);
        }

        // Send the follow-up request with tool results
        println!("\nStep 3: Send follow-up request with tool results");
        let final_response = client
            .send_chat(builder.tools(vec![get_weather_tool()]))
            .await?;

        if let Some(content) = final_response.content() {
            println!("  Final assistant response: {}", content);
        }
    }

    println!("\nNote: This demonstrates the complete tool calling loop with proper");
    println!("message history management using assistant_with_tool_calls()");

    Ok(())
}

fn streaming_with_tools(_client: &Client) {
    println!("Streaming response with tools:");

    // Note: Streaming with tool calls is more complex and requires
    // proper handling of partial tool call chunks. For now, this is
    // a placeholder showing the concept.

    println!("This would demonstrate streaming tool calls if streaming API was available");
    println!("In streaming mode, tool calls would arrive as chunks that need to be assembled");
}

async fn parallel_tool_calls(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("Check the weather in Tokyo, London, and New York")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Modern models can call multiple tools in parallel
    let tool_calls = response.tool_calls();
    println!("Parallel tool calls: {}", tool_calls.len());

    // Collect arguments first to avoid lifetime issues
    let args_vec: Vec<String> = tool_calls
        .iter()
        .map(|tc| tc.function_arguments().to_string())
        .collect();

    // Execute all in parallel using tokio
    let mut handles = Vec::new();
    for args in args_vec {
        let handle = tokio::spawn(async move {
            let params: WeatherParams = serde_json::from_str(&args)?;
            execute_weather_function(params)
        });
        handles.push(handle);
    }

    // Wait for all results
    for (i, handle) in handles.into_iter().enumerate() {
        match handle.await {
            Ok(Ok(result)) => println!("Location {}: {}", i + 1, result),
            Ok(Err(e)) => println!("Location {} error: {}", i + 1, e),
            Err(e) => println!("Task {} panicked: {}", i + 1, e),
        }
    }

    Ok(())
}

examples/retry_patterns.rs (line 369)

async fn fallback_chain(client: &Client) -> Result<()> {
    // Define fallback chain
    let strategies = vec![
        ("GPT-4o", "gpt-4o", 1024),
        ("GPT-4o-mini", "gpt-4o-mini", 512),
        ("GPT-3.5", "gpt-3.5-turbo", 256),
    ];

    let prompt = "Explain quantum computing";

    for (name, _model, max_tokens) in strategies {
        println!("Trying {} (max_tokens: {})", name, max_tokens);

        let builder = client.chat().user(prompt).max_completion_tokens(max_tokens);
        match client.send_chat(builder).await {
            Ok(response) => {
                println!("Success with {}", name);
                if let Some(content) = response.content() {
                    println!("Response: {}...", &content[..content.len().min(100)]);
                }
                return Ok(());
            }
            Err(e) => {
                println!("Failed with {}: {}", name, e);
            }
        }
    }

    println!("All fallback strategies exhausted");
    Ok(())
}

examples/models.rs (line 186)

async fn model_selection_by_task(client: &Client) -> Result<()> {
    // Task-specific model recommendations
    let task_models = vec![
        ("Simple Q&A", "gpt-3.5-turbo", "Fast and cost-effective"),
        ("Complex reasoning", "gpt-4o", "Best reasoning capabilities"),
        ("Code generation", "gpt-4o", "Excellent code understanding"),
        ("Vision tasks", "gpt-4o", "Native vision support"),
        (
            "Quick responses",
            "gpt-4o-mini",
            "Low latency, good quality",
        ),
        (
            "Bulk processing",
            "gpt-3.5-turbo",
            "Best cost/performance ratio",
        ),
    ];

    for (task, model, reason) in task_models {
        println!("Task: {}", task);
        println!("  Recommended: {}", model);
        println!("  Reason: {}", reason);

        // Demo the model
        let builder = client
            .chat()
            .user(format!("Say 'Hello from {}'", model))
            .max_completion_tokens(10);
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("  Response: {}\n", content);
        }
    }

    Ok(())
}

async fn cost_optimization(client: &Client) -> Result<()> {
    let models = get_model_registry();
    let test_prompt = "Explain the theory of relativity in one sentence";
    let estimated_input_tokens = 15;
    let estimated_output_tokens = 50;

    println!("Cost comparison for same task:");
    println!("Prompt: '{}'\n", test_prompt);

    let mut costs = Vec::new();

    for (name, info) in &models {
        if !info.deprecated {
            let input_cost = (f64::from(estimated_input_tokens) / 1000.0) * info.cost_per_1k_input;
            let output_cost =
                (f64::from(estimated_output_tokens) / 1000.0) * info.cost_per_1k_output;
            let total_cost = input_cost + output_cost;

            costs.push((name.clone(), total_cost));
        }
    }

    costs.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap());

    println!("{:<20} {:>15}", "Model", "Estimated Cost");
    println!("{:-<35}", "");
    for (model, cost) in costs {
        println!("{:<20} ${:>14.6}", model, cost);
    }

    // Demonstrate cheapest vs best
    println!("\nRunning with cheapest model (gpt-3.5-turbo):");
    let builder = client.chat().user(test_prompt);
    let cheap_response = client.send_chat(builder).await?;

    if let Some(content) = cheap_response.content() {
        println!("Response: {}", content);
    }

    Ok(())
}

async fn performance_testing(client: &Client) -> Result<()> {
    use std::time::Instant;

    let models_to_test = vec!["gpt-4o-mini", "gpt-3.5-turbo"];
    let test_prompt = "Write a haiku about programming";

    println!("Performance comparison:");
    println!("{:<20} {:>10} {:>15}", "Model", "Latency", "Tokens/sec");
    println!("{:-<45}", "");

    for model in models_to_test {
        let start = Instant::now();

        let builder = client.chat().user(test_prompt);
        let response = client.send_chat(builder).await?;

        let elapsed = start.elapsed();

        if let Some(usage) = response.usage() {
            let total_tokens = f64::from(usage.total_tokens);
            let tokens_per_sec = total_tokens / elapsed.as_secs_f64();

            println!("{:<20} {:>10.2?} {:>15.1}", model, elapsed, tokens_per_sec);
        }
    }

    Ok(())
}

async fn model_migration(client: &Client) -> Result<()> {
    // Handle deprecated model migration
    let deprecated_mappings = HashMap::from([
        ("text-davinci-003", "gpt-3.5-turbo"),
        ("gpt-4-32k", "gpt-4o"),
        ("gpt-4-vision-preview", "gpt-4o"),
    ]);

    let requested_model = "text-davinci-003"; // Deprecated model

    if let Some(replacement) = deprecated_mappings.get(requested_model) {
        println!(
            "Warning: {} is deprecated. Using {} instead.",
            requested_model, replacement
        );

        let builder = client.chat().user("Hello from migrated model");
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("Response from {}: {}", replacement, content);
        }
    }

    Ok(())
}

async fn dynamic_model_selection(client: &Client) -> Result<()> {
    // Select model based on runtime conditions

    #[derive(Debug)]
    struct RequestContext {
        urgency: Urgency,
        complexity: Complexity,
        budget: Budget,
        needs_vision: bool,
    }

    #[derive(Debug)]
    enum Urgency {
        Low,
        Medium,
        High,
    }

    #[derive(Debug)]
    enum Complexity {
        Simple,
        Moderate,
        Complex,
    }

    #[derive(Debug)]
    enum Budget {
        Tight,
        Normal,
        Flexible,
    }

    const fn select_model(ctx: &RequestContext) -> &'static str {
        match (&ctx.urgency, &ctx.complexity, &ctx.budget) {
            // High urgency + simple = fast cheap model, or tight budget = cheapest
            (Urgency::High, Complexity::Simple, _) | (_, _, Budget::Tight) => "gpt-3.5-turbo",

            // Complex + flexible budget = best model
            (_, Complexity::Complex, Budget::Flexible) => "gpt-4o",

            // Vision required
            _ if ctx.needs_vision => "gpt-4o",

            // Default balanced choice
            _ => "gpt-4o-mini",
        }
    }

    // Example contexts
    let contexts = [
        RequestContext {
            urgency: Urgency::High,
            complexity: Complexity::Simple,
            budget: Budget::Tight,
            needs_vision: false,
        },
        RequestContext {
            urgency: Urgency::Low,
            complexity: Complexity::Complex,
            budget: Budget::Flexible,
            needs_vision: false,
        },
        RequestContext {
            urgency: Urgency::Medium,
            complexity: Complexity::Moderate,
            budget: Budget::Normal,
            needs_vision: true,
        },
    ];

    for (i, ctx) in contexts.iter().enumerate() {
        let model = select_model(ctx);
        println!("Context {}: {:?}", i + 1, ctx);
        println!("  Selected model: {}", model);

        let builder = client
            .chat()
            .user(format!("Hello from dynamically selected {}", model))
            .max_completion_tokens(20);
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("  Response: {}\n", content);
        }
    }

    Ok(())
}

examples/moderations.rs (line 235)

async fn response_filtering(client: &Client) -> Result<()> {
    // Filter AI responses before showing to users

    println!("Generating and moderating AI responses:");

    // Generate response
    let prompt = "Tell me about technology";
    let builder = client.chat().user(prompt).max_completion_tokens(100);
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Generated response: '{}'", content);

        // Moderate the response
        let moderation_result = simulate_moderation(content);

        if moderation_result.flagged {
            println!(
                "  Response flagged! Categories: {:?}",
                moderation_result.categories
            );
            println!("Action: Response blocked or regenerated");

            // Regenerate with more strict instructions
            let safe_builder = client
                .chat()
                .system("Provide helpful, safe, and appropriate responses only.")
                .user(prompt)
                .max_completion_tokens(100);
            let safe_response = client.send_chat(safe_builder).await?;

            if let Some(safe_content) = safe_response.content() {
                println!("Regenerated safe response: '{}'", safe_content);
            }
        } else {
            println!(" Response passed moderation");
        }
    }

    Ok(())
}

fn policy_enforcement(_client: &Client) {
    // Enforce content policies
    let policy = ModerationPolicy {
        thresholds: HashMap::from([
            ("harassment".to_string(), 0.5),
            ("violence".to_string(), 0.6),
            ("sexual".to_string(), 0.4),
        ]),
        auto_reject_categories: vec![
            "harassment/threatening".to_string(),
            "violence/graphic".to_string(),
        ],
        require_human_review: vec!["self-harm".to_string()],
    };

    let test_cases = vec![
        "Normal conversation about work",
        "Slightly aggressive language here",
        "Content requiring review",
    ];

    for content in test_cases {
        println!("Checking: '{}'", content);

        let result = simulate_moderation(content);
        let action = apply_policy(&result, &policy);

        match action {
            PolicyAction::Approve => println!("   Approved"),
            PolicyAction::Reject(reason) => println!("   Rejected: {}", reason),
            PolicyAction::Review(reason) => println!("   Human review needed: {}", reason),
        }
    }
}

async fn moderation_pipeline(client: &Client) -> Result<()> {
    // Complete moderation pipeline

    type FilterFn = Box<dyn Fn(&str) -> bool + Send + Sync>;

    struct ModerationPipeline {
        pre_filters: Vec<FilterFn>,
        post_filters: Vec<FilterFn>,
    }

    let pipeline = ModerationPipeline {
        pre_filters: vec![
            Box::new(|text| text.len() < 10000), // Length check
            Box::new(|text| !text.is_empty()),   // Non-empty check
        ],
        post_filters: vec![
            Box::new(|text| !text.contains("blockedword")), // Custom word filter
        ],
    };

    println!("Running moderation pipeline:");

    let user_input = "Please help me with this technical question about Rust programming.";

    // Step 1: Pre-filters
    println!("1. Pre-filters:");
    for (i, filter) in pipeline.pre_filters.iter().enumerate() {
        if filter(user_input) {
            println!("   Pre-filter {} passed", i + 1);
        } else {
            println!("   Pre-filter {} failed", i + 1);
            return Ok(());
        }
    }

    // Step 2: API moderation
    println!("2. API moderation:");
    let moderation_result = simulate_moderation(user_input);
    if moderation_result.flagged {
        println!("   Content flagged by API");
        return Ok(());
    }
    println!("   Passed API moderation");

    // Step 3: Generate response
    println!("3. Generating response:");
    let builder = client.chat().user(user_input).max_completion_tokens(50);
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("  Generated: '{}'", content);

        // Step 4: Post-filters
        println!("4. Post-filters:");
        for (i, filter) in pipeline.post_filters.iter().enumerate() {
            if filter(content) {
                println!("   Post-filter {} passed", i + 1);
            } else {
                println!("   Post-filter {} failed", i + 1);
                return Ok(());
            }
        }

        // Step 5: Response moderation
        println!("5. Response moderation:");
        let response_moderation = simulate_moderation(content);
        if response_moderation.flagged {
            println!("   Response flagged");
        } else {
            println!("   Response approved");
            println!("\nFinal output: '{}'", content);
        }
    }

    Ok(())
}

Additional examples can be found in:

• examples/error_handling.rs
• examples/chat_comprehensive.rs
• examples/tool_calling_simple.rs
• examples/vision_chat.rs
• examples/azure_comprehensive.rs
• examples/tool_calling_multiturn.rs
• examples/langfuse.rs

pub fn user_with_image_url( self, text: impl Into<String>, image_url: impl Into<String>, ) -> Self

Add a user message with both text and an image URL.

Examples found in repository

examples/vision_chat.rs (line 90)

async fn demonstrate_basic_image_analysis(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 1: Basic Image Analysis");
    println!("----------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "What do you see in this image? Please describe it in detail.";

    println!("Image URL: {image_url}");
    println!("Question: {question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Use the convenient user_with_image_url method
    let chat_builder = client
        .chat()
        .system("You are a helpful AI assistant that can analyze images. Provide detailed, accurate descriptions of what you see.")
        .user_with_image_url(question, image_url)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Show usage information
        if let Some(usage) = response.usage() {
            println!("\n Token usage:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate analysis of multiple images in a single message.
async fn demonstrate_multiple_images(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multiple Image Analysis");
    println!("---------------------------------------");

    let question = "Compare these two images. What are the differences and similarities?";

    println!("Question: {question}");
    println!("Image 1: {}", SAMPLE_IMAGE_URLS[0]);
    println!("Image 2: {}", SAMPLE_IMAGE_URLS[1]);
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts manually for multiple images
    let parts = vec![
        text_part(question),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[0], Detail::Auto),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[1], Detail::Auto),
    ];

    let chat_builder = client
        .chat()
        .system("You are an expert at comparing and analyzing images. Provide thoughtful comparisons focusing on visual elements, composition, and content.")
        .user_with_parts(parts)
        .temperature(0.4);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate different detail levels for image analysis.
async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate base64 image encoding and analysis.
async fn demonstrate_base64_image(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Base64 Image Analysis");
    println!("-----------------------------------");

    let question = "What is this image? It's very small, what can you tell about it?";

    println!("Question: {question}");
    println!("Image: Small test image encoded as base64");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts with base64 image
    let parts = vec![
        text_part(question),
        image_base64_part_with_detail(SAMPLE_BASE64_IMAGE, "image/png", Detail::High),
    ];

    let chat_builder = client
        .chat()
        .system("You are analyzing images provided in base64 format. Even if an image is very small or simple, try to provide what information you can.")
        .user_with_parts(parts)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate conversation context with images.
async fn demonstrate_conversation_with_images(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 5: Conversation Context with Images");
    println!("----------------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];

    // First message: Analyze the image
    println!("Step 1: Initial image analysis");
    print!("Assistant: ");
    io::stdout().flush()?;

    let mut chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .temperature(0.3);

    let response1 = client.send_chat(chat_builder).await?;
    let first_response = response1.content().unwrap_or("No response").to_string();
    println!("{first_response}");

    // Second message: Follow-up question (without re-uploading the image)
    println!("\nStep 2: Follow-up question");
    print!("Assistant: ");
    io::stdout().flush()?;

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .temperature(0.3);

    let response2 = client.send_chat(chat_builder).await?;

    if let Some(content) = response2.content() {
        println!("{content}");
    }

    // Third message: Ask for creative interpretation
    println!("\nStep 3: Creative interpretation");
    print!("Assistant: ");
    io::stdout().flush()?;

    let second_response = response2.content().unwrap_or("No response").to_string();

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .assistant(second_response)
        .user("Based on our discussion, write a short poem inspired by this image.")
        .temperature(0.7);

    let response3 = client.send_chat(chat_builder).await?;

    if let Some(content) = response3.content() {
        println!("{content}");
    }

    println!();
    Ok(())
}

/// Demonstrate error handling patterns for vision requests.
async fn demonstrate_error_handling(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 6: Error Handling Patterns");
    println!("------------------------------------");

    println!("Testing various error scenarios...\n");

    // Test 1: Invalid image URL
    println!("Test 1: Invalid image URL");
    let invalid_url = "https://this-domain-does-not-exist-12345.com/image.jpg";

    let invalid_builder = client
        .chat()
        .user_with_image_url("What do you see?", invalid_url)
        .temperature(0.3);

    match client.send_chat(invalid_builder).await {
        Ok(_) => println!(" Invalid URL request unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected invalid URL ({status}): {message}");
            }
            Error::Http(reqwest_err) => {
                println!(" HTTP error caught: {reqwest_err}");
            }
            Error::InvalidRequest(msg) => {
                println!(" Validation caught invalid URL: {msg}");
            }
            _ => {
                println!("ℹ  Other error type: {e}");
            }
        },
    }

    // Test 2: Empty message with image
    println!("\nTest 2: Empty text with image");
    let empty_text_builder = client
        .chat()
        .user_with_image_url("", SAMPLE_IMAGE_URLS[0])
        .temperature(0.3);

    match client.send_chat(empty_text_builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!(
                    " API handled empty text gracefully: {}",
                    content.chars().take(50).collect::<String>()
                );
            }
        }
        Err(e) => {
            println!("ℹ  Empty text error: {e}");
        }
    }

    // Test 3: Malformed base64 data
    println!("\nTest 3: Malformed base64 image data");
    let malformed_base64 = "this-is-not-valid-base64!@#$%";
    let malformed_parts = vec![
        text_part("What is this?"),
        image_base64_part_with_detail(malformed_base64, "image/png", Detail::Auto),
    ];

    let malformed_builder = client.chat().user_with_parts(malformed_parts);

    match client.send_chat(malformed_builder).await {
        Ok(_) => println!(" Malformed base64 unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected malformed base64 ({status}): {message}");
            }
            _ => {
                println!("ℹ  Other error for malformed base64: {e}");
            }
        },
    }

    println!("\n  Error handling patterns demonstrated:");
    println!("  • Invalid image URL handling");
    println!("  • Empty text with image handling");
    println!("  • Malformed base64 data validation");
    println!("  • API error classification");
    println!("  • Network error handling");

    println!();
    Ok(())
}

pub fn user_with_image_url_and_detail( self, text: impl Into<String>, image_url: impl Into<String>, detail: Detail, ) -> Self

Add a user message with both text and an image URL with specified detail level.

Examples found in repository

examples/vision_chat.rs (line 174)

async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

pub fn user_with_parts( self, parts: Vec<ChatCompletionRequestUserMessageContentPart>, ) -> Self

Add a user message with multiple content parts (text and/or images).

Examples found in repository

examples/vision_chat.rs (line 136)

async fn demonstrate_multiple_images(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multiple Image Analysis");
    println!("---------------------------------------");

    let question = "Compare these two images. What are the differences and similarities?";

    println!("Question: {question}");
    println!("Image 1: {}", SAMPLE_IMAGE_URLS[0]);
    println!("Image 2: {}", SAMPLE_IMAGE_URLS[1]);
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts manually for multiple images
    let parts = vec![
        text_part(question),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[0], Detail::Auto),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[1], Detail::Auto),
    ];

    let chat_builder = client
        .chat()
        .system("You are an expert at comparing and analyzing images. Provide thoughtful comparisons focusing on visual elements, composition, and content.")
        .user_with_parts(parts)
        .temperature(0.4);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate different detail levels for image analysis.
async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate base64 image encoding and analysis.
async fn demonstrate_base64_image(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Base64 Image Analysis");
    println!("-----------------------------------");

    let question = "What is this image? It's very small, what can you tell about it?";

    println!("Question: {question}");
    println!("Image: Small test image encoded as base64");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts with base64 image
    let parts = vec![
        text_part(question),
        image_base64_part_with_detail(SAMPLE_BASE64_IMAGE, "image/png", Detail::High),
    ];

    let chat_builder = client
        .chat()
        .system("You are analyzing images provided in base64 format. Even if an image is very small or simple, try to provide what information you can.")
        .user_with_parts(parts)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate conversation context with images.
async fn demonstrate_conversation_with_images(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 5: Conversation Context with Images");
    println!("----------------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];

    // First message: Analyze the image
    println!("Step 1: Initial image analysis");
    print!("Assistant: ");
    io::stdout().flush()?;

    let mut chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .temperature(0.3);

    let response1 = client.send_chat(chat_builder).await?;
    let first_response = response1.content().unwrap_or("No response").to_string();
    println!("{first_response}");

    // Second message: Follow-up question (without re-uploading the image)
    println!("\nStep 2: Follow-up question");
    print!("Assistant: ");
    io::stdout().flush()?;

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .temperature(0.3);

    let response2 = client.send_chat(chat_builder).await?;

    if let Some(content) = response2.content() {
        println!("{content}");
    }

    // Third message: Ask for creative interpretation
    println!("\nStep 3: Creative interpretation");
    print!("Assistant: ");
    io::stdout().flush()?;

    let second_response = response2.content().unwrap_or("No response").to_string();

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .assistant(second_response)
        .user("Based on our discussion, write a short poem inspired by this image.")
        .temperature(0.7);

    let response3 = client.send_chat(chat_builder).await?;

    if let Some(content) = response3.content() {
        println!("{content}");
    }

    println!();
    Ok(())
}

/// Demonstrate error handling patterns for vision requests.
async fn demonstrate_error_handling(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 6: Error Handling Patterns");
    println!("------------------------------------");

    println!("Testing various error scenarios...\n");

    // Test 1: Invalid image URL
    println!("Test 1: Invalid image URL");
    let invalid_url = "https://this-domain-does-not-exist-12345.com/image.jpg";

    let invalid_builder = client
        .chat()
        .user_with_image_url("What do you see?", invalid_url)
        .temperature(0.3);

    match client.send_chat(invalid_builder).await {
        Ok(_) => println!(" Invalid URL request unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected invalid URL ({status}): {message}");
            }
            Error::Http(reqwest_err) => {
                println!(" HTTP error caught: {reqwest_err}");
            }
            Error::InvalidRequest(msg) => {
                println!(" Validation caught invalid URL: {msg}");
            }
            _ => {
                println!("ℹ  Other error type: {e}");
            }
        },
    }

    // Test 2: Empty message with image
    println!("\nTest 2: Empty text with image");
    let empty_text_builder = client
        .chat()
        .user_with_image_url("", SAMPLE_IMAGE_URLS[0])
        .temperature(0.3);

    match client.send_chat(empty_text_builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!(
                    " API handled empty text gracefully: {}",
                    content.chars().take(50).collect::<String>()
                );
            }
        }
        Err(e) => {
            println!("ℹ  Empty text error: {e}");
        }
    }

    // Test 3: Malformed base64 data
    println!("\nTest 3: Malformed base64 image data");
    let malformed_base64 = "this-is-not-valid-base64!@#$%";
    let malformed_parts = vec![
        text_part("What is this?"),
        image_base64_part_with_detail(malformed_base64, "image/png", Detail::Auto),
    ];

    let malformed_builder = client.chat().user_with_parts(malformed_parts);

    match client.send_chat(malformed_builder).await {
        Ok(_) => println!(" Malformed base64 unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected malformed base64 ({status}): {message}");
            }
            _ => {
                println!("ℹ  Other error for malformed base64: {e}");
            }
        },
    }

    println!("\n  Error handling patterns demonstrated:");
    println!("  • Invalid image URL handling");
    println!("  • Empty text with image handling");
    println!("  • Malformed base64 data validation");
    println!("  • API error classification");
    println!("  • Network error handling");

    println!();
    Ok(())
}

pub fn assistant(self, content: impl Into<String>) -> Self

Add an assistant message to the conversation.

Examples found in repository

examples/chat_streaming.rs (line 160)

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/chat_comprehensive.rs (line 206)

async fn demonstrate_basic_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 1: Basic Chat Completion");
    println!("----------------------------------");

    let user_message = "Hello! Can you explain what you can help me with?";
    conversation.add_user_message(user_message.to_string());

    println!("User: {user_message}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build the chat request with conversation history
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat();

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {} // Ignore unknown roles
        }
    }

    // Send the request
    let response = client.send_chat(chat_builder.temperature(0.7)).await?;

    if let Some(content) = response.content() {
        println!("{content}");
        conversation.add_assistant_message(content.to_string(), None);

        // Track token usage if available
        if let Some(usage) = response.usage() {
            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate multi-turn conversation.
async fn demonstrate_multi_turn_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multi-turn Conversation");
    println!("------------------------------------");

    let questions = vec![
        "What's the capital of France?",
        "What's the population of that city?",
        "Can you tell me an interesting fact about it?",
    ];

    for question in questions {
        conversation.add_user_message(question.to_string());

        println!("User: {question}");
        print!("Assistant: ");
        io::stdout().flush()?;

        // Build chat request with full conversation history
        let messages = conversation.get_conversation_for_api();
        let mut chat_builder = client.chat();

        for (role, content) in messages {
            match role.as_str() {
                "system" => chat_builder = chat_builder.system(content),
                "user" => chat_builder = chat_builder.user(content),
                "assistant" => chat_builder = chat_builder.assistant(content),
                _ => {}
            }
        }

        let response = client.send_chat(chat_builder.temperature(0.3)).await?;

        if let Some(content) = response.content() {
            println!("{content}");
            conversation.add_assistant_message(content.to_string(), None);

            // Track token usage
            if let Some(usage) = response.usage() {
                conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
            }
        }

        println!();
        // Small delay between questions for readability
        tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

/// Demonstrate streaming chat response.
async fn demonstrate_streaming_chat(
    _client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Streaming Chat Response");
    println!("------------------------------------");

    // Add user message for streaming example
    let streaming_question = "Can you write a short poem about programming?";
    conversation.add_user_message(streaming_question.to_string());

    println!("User: {streaming_question}");
    println!("Assistant (streaming): ");

    // Note: Streaming is not yet fully implemented in the client
    // This is a placeholder showing the intended API
    println!(" Streaming functionality is being implemented...");
    println!("Future implementation will show real-time token-by-token responses");

    // Simulate what streaming would look like
    let simulated_response = "Programming flows like poetry in motion,\nEach function a verse, each loop a devotion.\nVariables dance through memory's halls,\nWhile algorithms answer logic's calls.";

    // Simulate typing effect
    for char in simulated_response.chars() {
        print!("{char}");
        io::stdout().flush()?;
        tokio::time::sleep(tokio::time::Duration::from_millis(30)).await;
    }
    println!("\n");

    // Add the response to conversation history
    conversation.add_assistant_message(simulated_response.to_string(), None);

    Ok(())
}

/// Demonstrate token usage tracking.
async fn demonstrate_token_tracking(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Token Usage Tracking");
    println!("---------------------------------");

    let efficiency_question = "In one sentence, what is machine learning?";
    conversation.add_user_message(efficiency_question.to_string());

    println!("User: {efficiency_question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build chat request
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat().max_completion_tokens(50); // Limit tokens for demo

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {}
        }
    }

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Display detailed token usage
        if let Some(usage) = response.usage() {
            println!("\n Token Usage Breakdown:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);

            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);

            conversation.add_assistant_message(content.to_string(), Some(usage.completion_tokens));
        } else {
            conversation.add_assistant_message(content.to_string(), None);
        }
    }

    println!();
    Ok(())
}

examples/vision_chat.rs (line 258)

async fn demonstrate_conversation_with_images(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 5: Conversation Context with Images");
    println!("----------------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];

    // First message: Analyze the image
    println!("Step 1: Initial image analysis");
    print!("Assistant: ");
    io::stdout().flush()?;

    let mut chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .temperature(0.3);

    let response1 = client.send_chat(chat_builder).await?;
    let first_response = response1.content().unwrap_or("No response").to_string();
    println!("{first_response}");

    // Second message: Follow-up question (without re-uploading the image)
    println!("\nStep 2: Follow-up question");
    print!("Assistant: ");
    io::stdout().flush()?;

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .temperature(0.3);

    let response2 = client.send_chat(chat_builder).await?;

    if let Some(content) = response2.content() {
        println!("{content}");
    }

    // Third message: Ask for creative interpretation
    println!("\nStep 3: Creative interpretation");
    print!("Assistant: ");
    io::stdout().flush()?;

    let second_response = response2.content().unwrap_or("No response").to_string();

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .assistant(second_response)
        .user("Based on our discussion, write a short poem inspired by this image.")
        .temperature(0.7);

    let response3 = client.send_chat(chat_builder).await?;

    if let Some(content) = response3.content() {
        println!("{content}");
    }

    println!();
    Ok(())
}

examples/azure_comprehensive.rs (line 65)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    println!("=== Azure OpenAI Comprehensive API Test ===\n");

    let client = Client::from_env()?.build();

    // Test 1: Simple chat completion
    println!("1. Testing simple chat completion...");
    let builder = client.chat_simple("What is 2+2? Answer in one word.");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Chat completion: {content}");
            }
        }
        Err(e) => println!("   ✗ Chat completion failed: {e}"),
    }

    // Test 2: Chat with system message
    println!("\n2. Testing chat with system message...");
    let builder = client.chat_with_system(
        "You are a helpful assistant that responds in one sentence.",
        "What is Rust?",
    );
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ System message chat: {content}");
            }
        }
        Err(e) => println!("   ✗ System message chat failed: {e}"),
    }

    // Test 3: Chat with temperature
    println!("\n3. Testing chat with custom parameters...");
    let builder = client
        .chat()
        .user("Say 'test' in a creative way")
        .temperature(0.7)
        .max_tokens(50);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Custom parameters: {content}");
            }
        }
        Err(e) => println!("   ✗ Custom parameters failed: {e}"),
    }

    // Test 4: Multiple messages conversation
    println!("\n4. Testing multi-message conversation...");
    let builder = client
        .chat()
        .system("You are a helpful assistant")
        .user("My name is Alice")
        .assistant("Hello Alice! Nice to meet you.")
        .user("What's my name?");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Multi-message: {content}");
            }
        }
        Err(e) => println!("   ✗ Multi-message failed: {e}"),
    }

    // Test 5: Chat with max_tokens limit
    println!("\n5. Testing with max_tokens limit...");
    let builder = client.chat().user("Explain quantum physics").max_tokens(20);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Limited tokens: {content}");
                println!("   (Note: response is truncated due to max_tokens=20)");
            }
        }
        Err(e) => println!("   ✗ Max tokens test failed: {e}"),
    }

    // Test 6: Using responses API
    println!("\n6. Testing responses API...");
    let builder = client.responses().user("What is the capital of France?");
    match client.send_responses(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Responses API: {content}");
            }
        }
        Err(e) => println!("   ✗ Responses API failed: {e}"),
    }

    println!("\n=== Test Summary ===");
    println!("Azure OpenAI integration tested across multiple endpoints!");
    println!("\nNote: Some advanced features like embeddings, streaming, and");
    println!("tool calling may require specific Azure OpenAI deployments.");

    Ok(())
}

examples/tool_calling_multiturn.rs (line 311)

async fn main() -> Result<()> {
    println!("=== Multi-turn Tool Calling Example ===\n");

    // Initialize client
    let client = Client::from_env()?.build();

    // Create storage for the memory tool
    let storage = Arc::new(Mutex::new(HashMap::new()));

    // Define available tools
    let tools = vec![get_calculator_tool(), get_memory_tool()];

    println!("Available tools:");
    println!("  - calculator: Perform arithmetic operations");
    println!("  - memory: Store and retrieve values");
    println!();

    // Example 1: Single tool call
    println!("Example 1: Single Tool Call");
    println!("User: What is 15 + 27?");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("What is 15 + 27?");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 2: Multiple sequential tool calls
    println!("\n\nExample 2: Multiple Sequential Tool Calls");
    println!("User: Calculate 10 * 5 and store the result in memory as 'product'");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("Calculate 10 * 5 and store the result in memory as 'product'");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 3: Retrieve from memory
    println!("\n\nExample 3: Retrieve from Memory");
    println!("User: What did I store in 'product'?");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("What did I store in 'product'?");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 4: Complex multi-step task
    println!("\n\nExample 4: Complex Multi-step Task");
    println!("User: Calculate 100 / 4, multiply that by 3, and tell me the final result");
    {
        let chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.")
            .user("Calculate 100 / 4, multiply that by 3, and tell me the final result");

        let result = handle_tool_loop(&client, chat_builder, &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    // Example 5: Conversation with history
    println!("\n\nExample 5: Conversation with History");
    {
        let mut chat_builder = client
            .chat()
            .system("You are a helpful assistant with access to a calculator and memory storage.");

        // First question
        println!("User: What is 8 + 7?");
        chat_builder = chat_builder.user("What is 8 + 7?");
        let result = handle_tool_loop(&client, chat_builder.clone(), &tools, &storage).await?;
        println!("Assistant: {}", result);

        // Add assistant response to history
        chat_builder = chat_builder.assistant(&result);

        // Follow-up question that depends on previous context
        println!("\nUser: Now multiply that by 3");
        chat_builder = chat_builder.user("Now multiply that by 3");
        let result = handle_tool_loop(&client, chat_builder.clone(), &tools, &storage).await?;
        println!("Assistant: {}", result);
    }

    println!("\n\n=== All examples completed successfully ===");
    println!("\nKey Takeaway:");
    println!("  When implementing multi-turn tool calling, ALWAYS use");
    println!("  assistant_with_tool_calls() to maintain proper conversation");
    println!("  history. This is essential for the model to understand the");
    println!("  tool results and continue the conversation correctly.");

    Ok(())
}

examples/langfuse.rs (line 94)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for logging
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive("openai_ergonomic=debug".parse()?),
        )
        .init();

    // 1. Build Langfuse exporter from environment variables
    let exporter = ExporterBuilder::from_env()?.build()?;

    // 2. Create tracer provider with batch processor
    let provider = SdkTracerProvider::builder()
        .with_span_processor(BatchSpanProcessor::builder(exporter, Tokio).build())
        .build();

    // Set as global provider
    global::set_tracer_provider(provider.clone());

    // 3. Get tracer and create interceptor
    let tracer = provider.tracer("openai-ergonomic");
    let langfuse_interceptor =
        std::sync::Arc::new(LangfuseInterceptor::new(tracer, LangfuseConfig::new()));

    // 4. Create the OpenAI client and add the Langfuse interceptor
    // Keep a reference to the interceptor so we can update context later
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor.clone()))
        .build();

    println!(" OpenAI client initialized with Langfuse observability");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Example 1: Simple chat completion
    println!("Example 1: Simple chat completion");
    println!("---------------------------------");
    let chat_builder = client
        .chat_simple("What is the capital of France? Answer in one word.")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 2: Chat completion with builder pattern
    println!("Example 2: Chat with builder pattern");
    println!("-------------------------------------");
    let chat_builder = client
        .chat()
        .system("You are a helpful assistant that speaks like a pirate.")
        .user("Tell me about the ocean in 2 sentences.")
        .temperature(0.7)
        .max_tokens(100)
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 3: Multiple messages in a conversation
    println!("Example 3: Conversation");
    println!("-----------------------");
    let chat_builder = client
        .chat()
        .system("You are a math tutor.")
        .user("What is 2 + 2?")
        .assistant("2 + 2 equals 4.")
        .user("And what about 3 + 3?")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 4: Error handling (intentionally trigger an error)
    println!("Example 4: Error handling");
    println!("-------------------------");
    // Create a builder with a non-existent model
    let chat_builder = ChatCompletionBuilder::new("non-existent-model")
        .user("This should fail")
        .build()?;
    let result = client.execute_chat(chat_builder).await;

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(e) => println!("Expected error captured: {e}\n"),
    }

    // Example 5: Embeddings
    println!("Example 5: Embeddings");
    println!("--------------------");
    let embeddings_builder = client.embeddings().text(
        "text-embedding-ada-002",
        "The quick brown fox jumps over the lazy dog",
    );
    let embeddings = client.embeddings().create(embeddings_builder).await?;
    println!("Generated {} embedding(s)\n", embeddings.data.len());

    // Example 6: Using custom metadata via interceptor context
    println!("Example 6: Custom metadata via interceptor context");
    println!("---------------------------------------------------");

    // Set session and user IDs on the interceptor's context
    langfuse_interceptor.set_session_id("demo-session-123");
    langfuse_interceptor.set_user_id("demo-user-456");
    langfuse_interceptor.add_tags(vec!["example".to_string(), "demo".to_string()]);

    let chat_builder = client
        .chat_simple("Say 'Hello from custom session!'")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response with custom metadata: {:?}\n", response.content());

    // Clear context for subsequent calls
    langfuse_interceptor.clear_context();

    println!(" All examples completed!");
    println!(" Check your Langfuse dashboard to see the traces");
    println!("   - Look for traces with operation name 'chat'");
    println!("   - Each trace includes request/response details, token usage, and timing");
    println!("   - Example 6 will have custom session_id, user_id, and tags");

    // Shutdown the tracer provider to flush all spans
    println!("\n⏳ Flushing spans to Langfuse...");
    provider.shutdown()?;

    Ok(())
}

pub fn assistant_with_tool_calls( self, content: impl Into<String>, tool_calls: Vec<ChatCompletionMessageToolCallsInner>, ) -> Self

Add an assistant message with tool calls to the conversation.

This is used when the assistant wants to call tools. Each tool call should be represented as a tuple of (tool_call_id, function_name, function_arguments).

Examples found in repository

examples/tool_calling.rs (lines 236-239)

async fn conversation_with_tools(client: &Client) -> Result<()> {
    // This example demonstrates proper multi-turn tool calling with full message history

    println!("=== Conversation with Tools (Full Implementation) ===");

    // Initialize the conversation
    let mut builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);

    // First request - the model will call the tool
    let response = client.send_chat(builder.clone()).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!("Step 1: Model requests tool call");
        for tool_call in &tool_calls {
            println!("  Tool: {}", tool_call.function_name());
            println!("  Args: {}", tool_call.function_arguments());
        }

        // IMPORTANT: Add the assistant's response (with tool calls) to the history
        // This is the key step for maintaining proper conversation context!
        builder = builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute the tools and add results
        println!("\nStep 2: Execute tools and add results to conversation");
        for tool_call in tool_calls {
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("  Tool result: {}", result);

            // Add the tool result to the conversation history
            builder = builder.tool(tool_call.id(), result);
        }

        // Send the follow-up request with tool results
        println!("\nStep 3: Send follow-up request with tool results");
        let final_response = client
            .send_chat(builder.tools(vec![get_weather_tool()]))
            .await?;

        if let Some(content) = final_response.content() {
            println!("  Final assistant response: {}", content);
        }
    }

    println!("\nNote: This demonstrates the complete tool calling loop with proper");
    println!("message history management using assistant_with_tool_calls()");

    Ok(())
}

examples/tool_calling_multiturn.rs (lines 196-199)

async fn handle_tool_loop(
    client: &Client,
    mut chat_builder: openai_ergonomic::builders::chat::ChatCompletionBuilder,
    tools: &[openai_client_base::models::ChatCompletionTool],
    storage: &Arc<Mutex<HashMap<String, String>>>,
) -> Result<String> {
    const MAX_ITERATIONS: usize = 10; // Prevent infinite loops
    let mut iteration = 0;

    loop {
        iteration += 1;
        if iteration > MAX_ITERATIONS {
            return Err(std::io::Error::other("Max iterations reached in tool loop").into());
        }

        println!("\n  [Iteration {}]", iteration);

        // Send request with tools
        let request = chat_builder.clone().tools(tools.to_vec());
        let response = client.send_chat(request).await?;

        // Check if there are tool calls
        let tool_calls = response.tool_calls();
        if tool_calls.is_empty() {
            // No more tool calls, return the final response
            if let Some(content) = response.content() {
                return Ok(content.to_string());
            }
            return Err(std::io::Error::other("No content in final response").into());
        }

        // Process tool calls
        println!("  Tool calls: {}", tool_calls.len());

        // IMPORTANT: Add assistant message with tool calls to history
        // This is the key step that maintains proper conversation context!
        chat_builder = chat_builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute each tool call and add results to history
        for tool_call in tool_calls {
            let tool_name = tool_call.function_name();
            let tool_args = tool_call.function_arguments();
            let tool_id = tool_call.id();

            println!("    → {}: {}", tool_name, tool_args);

            let result = match execute_tool(tool_name, tool_args, storage) {
                Ok(result) => {
                    println!("    ✓ Result: {}", result);
                    result
                }
                Err(e) => {
                    let error_msg = format!("Error: {}", e);
                    eprintln!("    ✗ {}", error_msg);
                    error_msg
                }
            };

            // Add tool result to the conversation
            chat_builder = chat_builder.tool(tool_id, result);
        }
    }
}

pub fn tool( self, tool_call_id: impl Into<String>, content: impl Into<String>, ) -> Self

Add a tool result message to the conversation.

This is used to provide the result of a tool call back to the assistant.

Examples found in repository

examples/tool_calling.rs (line 249)

async fn conversation_with_tools(client: &Client) -> Result<()> {
    // This example demonstrates proper multi-turn tool calling with full message history

    println!("=== Conversation with Tools (Full Implementation) ===");

    // Initialize the conversation
    let mut builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);

    // First request - the model will call the tool
    let response = client.send_chat(builder.clone()).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!("Step 1: Model requests tool call");
        for tool_call in &tool_calls {
            println!("  Tool: {}", tool_call.function_name());
            println!("  Args: {}", tool_call.function_arguments());
        }

        // IMPORTANT: Add the assistant's response (with tool calls) to the history
        // This is the key step for maintaining proper conversation context!
        builder = builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute the tools and add results
        println!("\nStep 2: Execute tools and add results to conversation");
        for tool_call in tool_calls {
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("  Tool result: {}", result);

            // Add the tool result to the conversation history
            builder = builder.tool(tool_call.id(), result);
        }

        // Send the follow-up request with tool results
        println!("\nStep 3: Send follow-up request with tool results");
        let final_response = client
            .send_chat(builder.tools(vec![get_weather_tool()]))
            .await?;

        if let Some(content) = final_response.content() {
            println!("  Final assistant response: {}", content);
        }
    }

    println!("\nNote: This demonstrates the complete tool calling loop with proper");
    println!("message history management using assistant_with_tool_calls()");

    Ok(())
}

examples/tool_calling_multiturn.rs (line 222)

async fn handle_tool_loop(
    client: &Client,
    mut chat_builder: openai_ergonomic::builders::chat::ChatCompletionBuilder,
    tools: &[openai_client_base::models::ChatCompletionTool],
    storage: &Arc<Mutex<HashMap<String, String>>>,
) -> Result<String> {
    const MAX_ITERATIONS: usize = 10; // Prevent infinite loops
    let mut iteration = 0;

    loop {
        iteration += 1;
        if iteration > MAX_ITERATIONS {
            return Err(std::io::Error::other("Max iterations reached in tool loop").into());
        }

        println!("\n  [Iteration {}]", iteration);

        // Send request with tools
        let request = chat_builder.clone().tools(tools.to_vec());
        let response = client.send_chat(request).await?;

        // Check if there are tool calls
        let tool_calls = response.tool_calls();
        if tool_calls.is_empty() {
            // No more tool calls, return the final response
            if let Some(content) = response.content() {
                return Ok(content.to_string());
            }
            return Err(std::io::Error::other("No content in final response").into());
        }

        // Process tool calls
        println!("  Tool calls: {}", tool_calls.len());

        // IMPORTANT: Add assistant message with tool calls to history
        // This is the key step that maintains proper conversation context!
        chat_builder = chat_builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute each tool call and add results to history
        for tool_call in tool_calls {
            let tool_name = tool_call.function_name();
            let tool_args = tool_call.function_arguments();
            let tool_id = tool_call.id();

            println!("    → {}: {}", tool_name, tool_args);

            let result = match execute_tool(tool_name, tool_args, storage) {
                Ok(result) => {
                    println!("    ✓ Result: {}", result);
                    result
                }
                Err(e) => {
                    let error_msg = format!("Error: {}", e);
                    eprintln!("    ✗ {}", error_msg);
                    error_msg
                }
            };

            // Add tool result to the conversation
            chat_builder = chat_builder.tool(tool_id, result);
        }
    }
}

pub fn temperature(self, temperature: f64) -> Self

Set the temperature for the completion.

Examples found in repository

examples/chat_streaming.rs (line 74)

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(())
}

examples/langfuse_streaming.rs (line 124)

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(())
}

examples/vision_chat.rs (line 91)

async fn demonstrate_basic_image_analysis(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 1: Basic Image Analysis");
    println!("----------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "What do you see in this image? Please describe it in detail.";

    println!("Image URL: {image_url}");
    println!("Question: {question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Use the convenient user_with_image_url method
    let chat_builder = client
        .chat()
        .system("You are a helpful AI assistant that can analyze images. Provide detailed, accurate descriptions of what you see.")
        .user_with_image_url(question, image_url)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Show usage information
        if let Some(usage) = response.usage() {
            println!("\n Token usage:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate analysis of multiple images in a single message.
async fn demonstrate_multiple_images(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multiple Image Analysis");
    println!("---------------------------------------");

    let question = "Compare these two images. What are the differences and similarities?";

    println!("Question: {question}");
    println!("Image 1: {}", SAMPLE_IMAGE_URLS[0]);
    println!("Image 2: {}", SAMPLE_IMAGE_URLS[1]);
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts manually for multiple images
    let parts = vec![
        text_part(question),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[0], Detail::Auto),
        image_url_part_with_detail(SAMPLE_IMAGE_URLS[1], Detail::Auto),
    ];

    let chat_builder = client
        .chat()
        .system("You are an expert at comparing and analyzing images. Provide thoughtful comparisons focusing on visual elements, composition, and content.")
        .user_with_parts(parts)
        .temperature(0.4);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate different detail levels for image analysis.
async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate base64 image encoding and analysis.
async fn demonstrate_base64_image(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Base64 Image Analysis");
    println!("-----------------------------------");

    let question = "What is this image? It's very small, what can you tell about it?";

    println!("Question: {question}");
    println!("Image: Small test image encoded as base64");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Create message parts with base64 image
    let parts = vec![
        text_part(question),
        image_base64_part_with_detail(SAMPLE_BASE64_IMAGE, "image/png", Detail::High),
    ];

    let chat_builder = client
        .chat()
        .system("You are analyzing images provided in base64 format. Even if an image is very small or simple, try to provide what information you can.")
        .user_with_parts(parts)
        .temperature(0.3);

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate conversation context with images.
async fn demonstrate_conversation_with_images(
    client: &Client,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 5: Conversation Context with Images");
    println!("----------------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];

    // First message: Analyze the image
    println!("Step 1: Initial image analysis");
    print!("Assistant: ");
    io::stdout().flush()?;

    let mut chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .temperature(0.3);

    let response1 = client.send_chat(chat_builder).await?;
    let first_response = response1.content().unwrap_or("No response").to_string();
    println!("{first_response}");

    // Second message: Follow-up question (without re-uploading the image)
    println!("\nStep 2: Follow-up question");
    print!("Assistant: ");
    io::stdout().flush()?;

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .temperature(0.3);

    let response2 = client.send_chat(chat_builder).await?;

    if let Some(content) = response2.content() {
        println!("{content}");
    }

    // Third message: Ask for creative interpretation
    println!("\nStep 3: Creative interpretation");
    print!("Assistant: ");
    io::stdout().flush()?;

    let second_response = response2.content().unwrap_or("No response").to_string();

    chat_builder = client
        .chat()
        .system("You are having a conversation about images. Remember details from previous messages to maintain context.")
        .user_with_image_url("What's the main subject of this image?", image_url)
        .assistant(&first_response)
        .user("What colors are most prominent in the image we just discussed?")
        .assistant(second_response)
        .user("Based on our discussion, write a short poem inspired by this image.")
        .temperature(0.7);

    let response3 = client.send_chat(chat_builder).await?;

    if let Some(content) = response3.content() {
        println!("{content}");
    }

    println!();
    Ok(())
}

/// Demonstrate error handling patterns for vision requests.
async fn demonstrate_error_handling(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 6: Error Handling Patterns");
    println!("------------------------------------");

    println!("Testing various error scenarios...\n");

    // Test 1: Invalid image URL
    println!("Test 1: Invalid image URL");
    let invalid_url = "https://this-domain-does-not-exist-12345.com/image.jpg";

    let invalid_builder = client
        .chat()
        .user_with_image_url("What do you see?", invalid_url)
        .temperature(0.3);

    match client.send_chat(invalid_builder).await {
        Ok(_) => println!(" Invalid URL request unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected invalid URL ({status}): {message}");
            }
            Error::Http(reqwest_err) => {
                println!(" HTTP error caught: {reqwest_err}");
            }
            Error::InvalidRequest(msg) => {
                println!(" Validation caught invalid URL: {msg}");
            }
            _ => {
                println!("ℹ  Other error type: {e}");
            }
        },
    }

    // Test 2: Empty message with image
    println!("\nTest 2: Empty text with image");
    let empty_text_builder = client
        .chat()
        .user_with_image_url("", SAMPLE_IMAGE_URLS[0])
        .temperature(0.3);

    match client.send_chat(empty_text_builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!(
                    " API handled empty text gracefully: {}",
                    content.chars().take(50).collect::<String>()
                );
            }
        }
        Err(e) => {
            println!("ℹ  Empty text error: {e}");
        }
    }

    // Test 3: Malformed base64 data
    println!("\nTest 3: Malformed base64 image data");
    let malformed_base64 = "this-is-not-valid-base64!@#$%";
    let malformed_parts = vec![
        text_part("What is this?"),
        image_base64_part_with_detail(malformed_base64, "image/png", Detail::Auto),
    ];

    let malformed_builder = client.chat().user_with_parts(malformed_parts);

    match client.send_chat(malformed_builder).await {
        Ok(_) => println!(" Malformed base64 unexpectedly succeeded"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API properly rejected malformed base64 ({status}): {message}");
            }
            _ => {
                println!("ℹ  Other error for malformed base64: {e}");
            }
        },
    }

    println!("\n  Error handling patterns demonstrated:");
    println!("  • Invalid image URL handling");
    println!("  • Empty text with image handling");
    println!("  • Malformed base64 data validation");
    println!("  • API error classification");
    println!("  • Network error handling");

    println!();
    Ok(())
}

examples/chat_comprehensive.rs (line 212)

async fn demonstrate_basic_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 1: Basic Chat Completion");
    println!("----------------------------------");

    let user_message = "Hello! Can you explain what you can help me with?";
    conversation.add_user_message(user_message.to_string());

    println!("User: {user_message}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build the chat request with conversation history
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat();

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {} // Ignore unknown roles
        }
    }

    // Send the request
    let response = client.send_chat(chat_builder.temperature(0.7)).await?;

    if let Some(content) = response.content() {
        println!("{content}");
        conversation.add_assistant_message(content.to_string(), None);

        // Track token usage if available
        if let Some(usage) = response.usage() {
            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
        }
    } else {
        println!("No response content received");
    }

    println!();
    Ok(())
}

/// Demonstrate multi-turn conversation.
async fn demonstrate_multi_turn_chat(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 2: Multi-turn Conversation");
    println!("------------------------------------");

    let questions = vec![
        "What's the capital of France?",
        "What's the population of that city?",
        "Can you tell me an interesting fact about it?",
    ];

    for question in questions {
        conversation.add_user_message(question.to_string());

        println!("User: {question}");
        print!("Assistant: ");
        io::stdout().flush()?;

        // Build chat request with full conversation history
        let messages = conversation.get_conversation_for_api();
        let mut chat_builder = client.chat();

        for (role, content) in messages {
            match role.as_str() {
                "system" => chat_builder = chat_builder.system(content),
                "user" => chat_builder = chat_builder.user(content),
                "assistant" => chat_builder = chat_builder.assistant(content),
                _ => {}
            }
        }

        let response = client.send_chat(chat_builder.temperature(0.3)).await?;

        if let Some(content) = response.content() {
            println!("{content}");
            conversation.add_assistant_message(content.to_string(), None);

            // Track token usage
            if let Some(usage) = response.usage() {
                conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);
            }
        }

        println!();
        // Small delay between questions for readability
        tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

/// Demonstrate streaming chat response.
async fn demonstrate_streaming_chat(
    _client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Streaming Chat Response");
    println!("------------------------------------");

    // Add user message for streaming example
    let streaming_question = "Can you write a short poem about programming?";
    conversation.add_user_message(streaming_question.to_string());

    println!("User: {streaming_question}");
    println!("Assistant (streaming): ");

    // Note: Streaming is not yet fully implemented in the client
    // This is a placeholder showing the intended API
    println!(" Streaming functionality is being implemented...");
    println!("Future implementation will show real-time token-by-token responses");

    // Simulate what streaming would look like
    let simulated_response = "Programming flows like poetry in motion,\nEach function a verse, each loop a devotion.\nVariables dance through memory's halls,\nWhile algorithms answer logic's calls.";

    // Simulate typing effect
    for char in simulated_response.chars() {
        print!("{char}");
        io::stdout().flush()?;
        tokio::time::sleep(tokio::time::Duration::from_millis(30)).await;
    }
    println!("\n");

    // Add the response to conversation history
    conversation.add_assistant_message(simulated_response.to_string(), None);

    Ok(())
}

/// Demonstrate token usage tracking.
async fn demonstrate_token_tracking(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Token Usage Tracking");
    println!("---------------------------------");

    let efficiency_question = "In one sentence, what is machine learning?";
    conversation.add_user_message(efficiency_question.to_string());

    println!("User: {efficiency_question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build chat request
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat().max_completion_tokens(50); // Limit tokens for demo

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {}
        }
    }

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Display detailed token usage
        if let Some(usage) = response.usage() {
            println!("\n Token Usage Breakdown:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);

            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);

            conversation.add_assistant_message(content.to_string(), Some(usage.completion_tokens));
        } else {
            conversation.add_assistant_message(content.to_string(), None);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error handling patterns.
async fn demonstrate_error_handling(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!("  Example 5: Error Handling Patterns");
    println!("------------------------------------");

    println!("Testing various error scenarios...\n");

    // Test 1: Invalid model
    println!("Test 1: Invalid model name");
    let invalid_model_builder = client.chat()
        .user("Hello")
        // Note: We can't easily test invalid model without modifying the builder
        // This shows the pattern for handling errors
        .temperature(0.7);

    match client.send_chat(invalid_model_builder).await {
        Ok(_) => println!(" Request succeeded (model validation not yet implemented)"),
        Err(e) => match &e {
            Error::Api {
                status, message, ..
            } => {
                println!(" API Error ({status}): {message}");
            }
            Error::Http(reqwest_err) => {
                println!(" HTTP Error: {reqwest_err}");
            }
            Error::InvalidRequest(msg) => {
                println!(" Invalid Request: {msg}");
            }
            _ => {
                println!(" Unexpected Error: {e}");
            }
        },
    }

    // Test 2: Empty message validation
    println!("\nTest 2: Empty message validation");
    let empty_builder = client.chat(); // No messages added

    match client.send_chat(empty_builder).await {
        Ok(_) => println!(" Empty request unexpectedly succeeded"),
        Err(Error::InvalidRequest(msg)) => {
            println!(" Validation caught empty request: {msg}");
        }
        Err(e) => {
            println!(" Unexpected error type: {e}");
        }
    }

    // Test 3: Configuration errors
    println!("\nTest 3: Configuration validation");
    println!(" Client configuration is valid (created successfully)");

    println!("\n  Error handling patterns demonstrated:");
    println!("  • API error classification");
    println!("  • Request validation");
    println!("  • Network error handling");
    println!("  • Configuration validation");

    println!();
    Ok(())
}

examples/azure_comprehensive.rs (line 48)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    println!("=== Azure OpenAI Comprehensive API Test ===\n");

    let client = Client::from_env()?.build();

    // Test 1: Simple chat completion
    println!("1. Testing simple chat completion...");
    let builder = client.chat_simple("What is 2+2? Answer in one word.");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Chat completion: {content}");
            }
        }
        Err(e) => println!("   ✗ Chat completion failed: {e}"),
    }

    // Test 2: Chat with system message
    println!("\n2. Testing chat with system message...");
    let builder = client.chat_with_system(
        "You are a helpful assistant that responds in one sentence.",
        "What is Rust?",
    );
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ System message chat: {content}");
            }
        }
        Err(e) => println!("   ✗ System message chat failed: {e}"),
    }

    // Test 3: Chat with temperature
    println!("\n3. Testing chat with custom parameters...");
    let builder = client
        .chat()
        .user("Say 'test' in a creative way")
        .temperature(0.7)
        .max_tokens(50);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Custom parameters: {content}");
            }
        }
        Err(e) => println!("   ✗ Custom parameters failed: {e}"),
    }

    // Test 4: Multiple messages conversation
    println!("\n4. Testing multi-message conversation...");
    let builder = client
        .chat()
        .system("You are a helpful assistant")
        .user("My name is Alice")
        .assistant("Hello Alice! Nice to meet you.")
        .user("What's my name?");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Multi-message: {content}");
            }
        }
        Err(e) => println!("   ✗ Multi-message failed: {e}"),
    }

    // Test 5: Chat with max_tokens limit
    println!("\n5. Testing with max_tokens limit...");
    let builder = client.chat().user("Explain quantum physics").max_tokens(20);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Limited tokens: {content}");
                println!("   (Note: response is truncated due to max_tokens=20)");
            }
        }
        Err(e) => println!("   ✗ Max tokens test failed: {e}"),
    }

    // Test 6: Using responses API
    println!("\n6. Testing responses API...");
    let builder = client.responses().user("What is the capital of France?");
    match client.send_responses(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Responses API: {content}");
            }
        }
        Err(e) => println!("   ✗ Responses API failed: {e}"),
    }

    println!("\n=== Test Summary ===");
    println!("Azure OpenAI integration tested across multiple endpoints!");
    println!("\nNote: Some advanced features like embeddings, streaming, and");
    println!("tool calling may require specific Azure OpenAI deployments.");

    Ok(())
}

examples/langfuse.rs (line 81)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for logging
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive("openai_ergonomic=debug".parse()?),
        )
        .init();

    // 1. Build Langfuse exporter from environment variables
    let exporter = ExporterBuilder::from_env()?.build()?;

    // 2. Create tracer provider with batch processor
    let provider = SdkTracerProvider::builder()
        .with_span_processor(BatchSpanProcessor::builder(exporter, Tokio).build())
        .build();

    // Set as global provider
    global::set_tracer_provider(provider.clone());

    // 3. Get tracer and create interceptor
    let tracer = provider.tracer("openai-ergonomic");
    let langfuse_interceptor =
        std::sync::Arc::new(LangfuseInterceptor::new(tracer, LangfuseConfig::new()));

    // 4. Create the OpenAI client and add the Langfuse interceptor
    // Keep a reference to the interceptor so we can update context later
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor.clone()))
        .build();

    println!(" OpenAI client initialized with Langfuse observability");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Example 1: Simple chat completion
    println!("Example 1: Simple chat completion");
    println!("---------------------------------");
    let chat_builder = client
        .chat_simple("What is the capital of France? Answer in one word.")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 2: Chat completion with builder pattern
    println!("Example 2: Chat with builder pattern");
    println!("-------------------------------------");
    let chat_builder = client
        .chat()
        .system("You are a helpful assistant that speaks like a pirate.")
        .user("Tell me about the ocean in 2 sentences.")
        .temperature(0.7)
        .max_tokens(100)
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 3: Multiple messages in a conversation
    println!("Example 3: Conversation");
    println!("-----------------------");
    let chat_builder = client
        .chat()
        .system("You are a math tutor.")
        .user("What is 2 + 2?")
        .assistant("2 + 2 equals 4.")
        .user("And what about 3 + 3?")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 4: Error handling (intentionally trigger an error)
    println!("Example 4: Error handling");
    println!("-------------------------");
    // Create a builder with a non-existent model
    let chat_builder = ChatCompletionBuilder::new("non-existent-model")
        .user("This should fail")
        .build()?;
    let result = client.execute_chat(chat_builder).await;

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(e) => println!("Expected error captured: {e}\n"),
    }

    // Example 5: Embeddings
    println!("Example 5: Embeddings");
    println!("--------------------");
    let embeddings_builder = client.embeddings().text(
        "text-embedding-ada-002",
        "The quick brown fox jumps over the lazy dog",
    );
    let embeddings = client.embeddings().create(embeddings_builder).await?;
    println!("Generated {} embedding(s)\n", embeddings.data.len());

    // Example 6: Using custom metadata via interceptor context
    println!("Example 6: Custom metadata via interceptor context");
    println!("---------------------------------------------------");

    // Set session and user IDs on the interceptor's context
    langfuse_interceptor.set_session_id("demo-session-123");
    langfuse_interceptor.set_user_id("demo-user-456");
    langfuse_interceptor.add_tags(vec!["example".to_string(), "demo".to_string()]);

    let chat_builder = client
        .chat_simple("Say 'Hello from custom session!'")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response with custom metadata: {:?}\n", response.content());

    // Clear context for subsequent calls
    langfuse_interceptor.clear_context();

    println!(" All examples completed!");
    println!(" Check your Langfuse dashboard to see the traces");
    println!("   - Look for traces with operation name 'chat'");
    println!("   - Each trace includes request/response details, token usage, and timing");
    println!("   - Example 6 will have custom session_id, user_id, and tags");

    // Shutdown the tracer provider to flush all spans
    println!("\n⏳ Flushing spans to Langfuse...");
    provider.shutdown()?;

    Ok(())
}

pub fn max_tokens(self, max_tokens: i32) -> Self

Set the maximum number of tokens to generate.

Examples found in repository

examples/chat_streaming.rs (line 75)

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(())
}

examples/langfuse_streaming.rs (line 125)

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(())
}

examples/azure_comprehensive.rs (line 49)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    println!("=== Azure OpenAI Comprehensive API Test ===\n");

    let client = Client::from_env()?.build();

    // Test 1: Simple chat completion
    println!("1. Testing simple chat completion...");
    let builder = client.chat_simple("What is 2+2? Answer in one word.");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Chat completion: {content}");
            }
        }
        Err(e) => println!("   ✗ Chat completion failed: {e}"),
    }

    // Test 2: Chat with system message
    println!("\n2. Testing chat with system message...");
    let builder = client.chat_with_system(
        "You are a helpful assistant that responds in one sentence.",
        "What is Rust?",
    );
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ System message chat: {content}");
            }
        }
        Err(e) => println!("   ✗ System message chat failed: {e}"),
    }

    // Test 3: Chat with temperature
    println!("\n3. Testing chat with custom parameters...");
    let builder = client
        .chat()
        .user("Say 'test' in a creative way")
        .temperature(0.7)
        .max_tokens(50);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Custom parameters: {content}");
            }
        }
        Err(e) => println!("   ✗ Custom parameters failed: {e}"),
    }

    // Test 4: Multiple messages conversation
    println!("\n4. Testing multi-message conversation...");
    let builder = client
        .chat()
        .system("You are a helpful assistant")
        .user("My name is Alice")
        .assistant("Hello Alice! Nice to meet you.")
        .user("What's my name?");
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Multi-message: {content}");
            }
        }
        Err(e) => println!("   ✗ Multi-message failed: {e}"),
    }

    // Test 5: Chat with max_tokens limit
    println!("\n5. Testing with max_tokens limit...");
    let builder = client.chat().user("Explain quantum physics").max_tokens(20);
    match client.send_chat(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Limited tokens: {content}");
                println!("   (Note: response is truncated due to max_tokens=20)");
            }
        }
        Err(e) => println!("   ✗ Max tokens test failed: {e}"),
    }

    // Test 6: Using responses API
    println!("\n6. Testing responses API...");
    let builder = client.responses().user("What is the capital of France?");
    match client.send_responses(builder).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("   ✓ Responses API: {content}");
            }
        }
        Err(e) => println!("   ✗ Responses API failed: {e}"),
    }

    println!("\n=== Test Summary ===");
    println!("Azure OpenAI integration tested across multiple endpoints!");
    println!("\nNote: Some advanced features like embeddings, streaming, and");
    println!("tool calling may require specific Azure OpenAI deployments.");

    Ok(())
}

examples/langfuse.rs (line 82)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for logging
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive("openai_ergonomic=debug".parse()?),
        )
        .init();

    // 1. Build Langfuse exporter from environment variables
    let exporter = ExporterBuilder::from_env()?.build()?;

    // 2. Create tracer provider with batch processor
    let provider = SdkTracerProvider::builder()
        .with_span_processor(BatchSpanProcessor::builder(exporter, Tokio).build())
        .build();

    // Set as global provider
    global::set_tracer_provider(provider.clone());

    // 3. Get tracer and create interceptor
    let tracer = provider.tracer("openai-ergonomic");
    let langfuse_interceptor =
        std::sync::Arc::new(LangfuseInterceptor::new(tracer, LangfuseConfig::new()));

    // 4. Create the OpenAI client and add the Langfuse interceptor
    // Keep a reference to the interceptor so we can update context later
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor.clone()))
        .build();

    println!(" OpenAI client initialized with Langfuse observability");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Example 1: Simple chat completion
    println!("Example 1: Simple chat completion");
    println!("---------------------------------");
    let chat_builder = client
        .chat_simple("What is the capital of France? Answer in one word.")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 2: Chat completion with builder pattern
    println!("Example 2: Chat with builder pattern");
    println!("-------------------------------------");
    let chat_builder = client
        .chat()
        .system("You are a helpful assistant that speaks like a pirate.")
        .user("Tell me about the ocean in 2 sentences.")
        .temperature(0.7)
        .max_tokens(100)
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 3: Multiple messages in a conversation
    println!("Example 3: Conversation");
    println!("-----------------------");
    let chat_builder = client
        .chat()
        .system("You are a math tutor.")
        .user("What is 2 + 2?")
        .assistant("2 + 2 equals 4.")
        .user("And what about 3 + 3?")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response: {:?}\n", response.content());

    // Example 4: Error handling (intentionally trigger an error)
    println!("Example 4: Error handling");
    println!("-------------------------");
    // Create a builder with a non-existent model
    let chat_builder = ChatCompletionBuilder::new("non-existent-model")
        .user("This should fail")
        .build()?;
    let result = client.execute_chat(chat_builder).await;

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(e) => println!("Expected error captured: {e}\n"),
    }

    // Example 5: Embeddings
    println!("Example 5: Embeddings");
    println!("--------------------");
    let embeddings_builder = client.embeddings().text(
        "text-embedding-ada-002",
        "The quick brown fox jumps over the lazy dog",
    );
    let embeddings = client.embeddings().create(embeddings_builder).await?;
    println!("Generated {} embedding(s)\n", embeddings.data.len());

    // Example 6: Using custom metadata via interceptor context
    println!("Example 6: Custom metadata via interceptor context");
    println!("---------------------------------------------------");

    // Set session and user IDs on the interceptor's context
    langfuse_interceptor.set_session_id("demo-session-123");
    langfuse_interceptor.set_user_id("demo-user-456");
    langfuse_interceptor.add_tags(vec!["example".to_string(), "demo".to_string()]);

    let chat_builder = client
        .chat_simple("Say 'Hello from custom session!'")
        .build()?;
    let response = client.execute_chat(chat_builder).await?;
    println!("Response with custom metadata: {:?}\n", response.content());

    // Clear context for subsequent calls
    langfuse_interceptor.clear_context();

    println!(" All examples completed!");
    println!(" Check your Langfuse dashboard to see the traces");
    println!("   - Look for traces with operation name 'chat'");
    println!("   - Each trace includes request/response details, token usage, and timing");
    println!("   - Example 6 will have custom session_id, user_id, and tags");

    // Shutdown the tracer provider to flush all spans
    println!("\n⏳ Flushing spans to Langfuse...");
    provider.shutdown()?;

    Ok(())
}

pub fn max_completion_tokens(self, max_completion_tokens: i32) -> Self

Set the maximum completion tokens (for newer models).

Examples found in repository

examples/retry_patterns.rs (line 369)

async fn fallback_chain(client: &Client) -> Result<()> {
    // Define fallback chain
    let strategies = vec![
        ("GPT-4o", "gpt-4o", 1024),
        ("GPT-4o-mini", "gpt-4o-mini", 512),
        ("GPT-3.5", "gpt-3.5-turbo", 256),
    ];

    let prompt = "Explain quantum computing";

    for (name, _model, max_tokens) in strategies {
        println!("Trying {} (max_tokens: {})", name, max_tokens);

        let builder = client.chat().user(prompt).max_completion_tokens(max_tokens);
        match client.send_chat(builder).await {
            Ok(response) => {
                println!("Success with {}", name);
                if let Some(content) = response.content() {
                    println!("Response: {}...", &content[..content.len().min(100)]);
                }
                return Ok(());
            }
            Err(e) => {
                println!("Failed with {}: {}", name, e);
            }
        }
    }

    println!("All fallback strategies exhausted");
    Ok(())
}

examples/models.rs (line 187)

async fn model_selection_by_task(client: &Client) -> Result<()> {
    // Task-specific model recommendations
    let task_models = vec![
        ("Simple Q&A", "gpt-3.5-turbo", "Fast and cost-effective"),
        ("Complex reasoning", "gpt-4o", "Best reasoning capabilities"),
        ("Code generation", "gpt-4o", "Excellent code understanding"),
        ("Vision tasks", "gpt-4o", "Native vision support"),
        (
            "Quick responses",
            "gpt-4o-mini",
            "Low latency, good quality",
        ),
        (
            "Bulk processing",
            "gpt-3.5-turbo",
            "Best cost/performance ratio",
        ),
    ];

    for (task, model, reason) in task_models {
        println!("Task: {}", task);
        println!("  Recommended: {}", model);
        println!("  Reason: {}", reason);

        // Demo the model
        let builder = client
            .chat()
            .user(format!("Say 'Hello from {}'", model))
            .max_completion_tokens(10);
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("  Response: {}\n", content);
        }
    }

    Ok(())
}

async fn cost_optimization(client: &Client) -> Result<()> {
    let models = get_model_registry();
    let test_prompt = "Explain the theory of relativity in one sentence";
    let estimated_input_tokens = 15;
    let estimated_output_tokens = 50;

    println!("Cost comparison for same task:");
    println!("Prompt: '{}'\n", test_prompt);

    let mut costs = Vec::new();

    for (name, info) in &models {
        if !info.deprecated {
            let input_cost = (f64::from(estimated_input_tokens) / 1000.0) * info.cost_per_1k_input;
            let output_cost =
                (f64::from(estimated_output_tokens) / 1000.0) * info.cost_per_1k_output;
            let total_cost = input_cost + output_cost;

            costs.push((name.clone(), total_cost));
        }
    }

    costs.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap());

    println!("{:<20} {:>15}", "Model", "Estimated Cost");
    println!("{:-<35}", "");
    for (model, cost) in costs {
        println!("{:<20} ${:>14.6}", model, cost);
    }

    // Demonstrate cheapest vs best
    println!("\nRunning with cheapest model (gpt-3.5-turbo):");
    let builder = client.chat().user(test_prompt);
    let cheap_response = client.send_chat(builder).await?;

    if let Some(content) = cheap_response.content() {
        println!("Response: {}", content);
    }

    Ok(())
}

async fn performance_testing(client: &Client) -> Result<()> {
    use std::time::Instant;

    let models_to_test = vec!["gpt-4o-mini", "gpt-3.5-turbo"];
    let test_prompt = "Write a haiku about programming";

    println!("Performance comparison:");
    println!("{:<20} {:>10} {:>15}", "Model", "Latency", "Tokens/sec");
    println!("{:-<45}", "");

    for model in models_to_test {
        let start = Instant::now();

        let builder = client.chat().user(test_prompt);
        let response = client.send_chat(builder).await?;

        let elapsed = start.elapsed();

        if let Some(usage) = response.usage() {
            let total_tokens = f64::from(usage.total_tokens);
            let tokens_per_sec = total_tokens / elapsed.as_secs_f64();

            println!("{:<20} {:>10.2?} {:>15.1}", model, elapsed, tokens_per_sec);
        }
    }

    Ok(())
}

async fn model_migration(client: &Client) -> Result<()> {
    // Handle deprecated model migration
    let deprecated_mappings = HashMap::from([
        ("text-davinci-003", "gpt-3.5-turbo"),
        ("gpt-4-32k", "gpt-4o"),
        ("gpt-4-vision-preview", "gpt-4o"),
    ]);

    let requested_model = "text-davinci-003"; // Deprecated model

    if let Some(replacement) = deprecated_mappings.get(requested_model) {
        println!(
            "Warning: {} is deprecated. Using {} instead.",
            requested_model, replacement
        );

        let builder = client.chat().user("Hello from migrated model");
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("Response from {}: {}", replacement, content);
        }
    }

    Ok(())
}

async fn dynamic_model_selection(client: &Client) -> Result<()> {
    // Select model based on runtime conditions

    #[derive(Debug)]
    struct RequestContext {
        urgency: Urgency,
        complexity: Complexity,
        budget: Budget,
        needs_vision: bool,
    }

    #[derive(Debug)]
    enum Urgency {
        Low,
        Medium,
        High,
    }

    #[derive(Debug)]
    enum Complexity {
        Simple,
        Moderate,
        Complex,
    }

    #[derive(Debug)]
    enum Budget {
        Tight,
        Normal,
        Flexible,
    }

    const fn select_model(ctx: &RequestContext) -> &'static str {
        match (&ctx.urgency, &ctx.complexity, &ctx.budget) {
            // High urgency + simple = fast cheap model, or tight budget = cheapest
            (Urgency::High, Complexity::Simple, _) | (_, _, Budget::Tight) => "gpt-3.5-turbo",

            // Complex + flexible budget = best model
            (_, Complexity::Complex, Budget::Flexible) => "gpt-4o",

            // Vision required
            _ if ctx.needs_vision => "gpt-4o",

            // Default balanced choice
            _ => "gpt-4o-mini",
        }
    }

    // Example contexts
    let contexts = [
        RequestContext {
            urgency: Urgency::High,
            complexity: Complexity::Simple,
            budget: Budget::Tight,
            needs_vision: false,
        },
        RequestContext {
            urgency: Urgency::Low,
            complexity: Complexity::Complex,
            budget: Budget::Flexible,
            needs_vision: false,
        },
        RequestContext {
            urgency: Urgency::Medium,
            complexity: Complexity::Moderate,
            budget: Budget::Normal,
            needs_vision: true,
        },
    ];

    for (i, ctx) in contexts.iter().enumerate() {
        let model = select_model(ctx);
        println!("Context {}: {:?}", i + 1, ctx);
        println!("  Selected model: {}", model);

        let builder = client
            .chat()
            .user(format!("Hello from dynamically selected {}", model))
            .max_completion_tokens(20);
        let response = client.send_chat(builder).await?;

        if let Some(content) = response.content() {
            println!("  Response: {}\n", content);
        }
    }

    Ok(())
}

examples/vision_chat.rs (line 176)

async fn demonstrate_detail_levels(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 3: Different Detail Levels");
    println!("------------------------------------");

    let image_url = SAMPLE_IMAGE_URLS[0];
    let question = "Analyze this image";

    // Test different detail levels
    let detail_levels = vec![
        (Detail::Low, "Low detail (faster, less detailed)"),
        (Detail::High, "High detail (slower, more detailed)"),
        (Detail::Auto, "Auto detail (balanced)"),
    ];

    for (detail, description) in detail_levels {
        println!("\n{description}:");
        print!("Assistant: ");
        io::stdout().flush()?;

        let chat_builder = client
            .chat()
            .system("Analyze the image and describe what you see. Adjust your response detail based on the image quality provided.")
            .user_with_image_url_and_detail(question, image_url, detail)
            .temperature(0.2)
            .max_completion_tokens(100); // Limit response length for comparison

        let response = client.send_chat(chat_builder).await?;

        if let Some(content) = response.content() {
            println!("{content}");
        }
    }

    println!();
    Ok(())
}

examples/moderations.rs (line 235)

async fn response_filtering(client: &Client) -> Result<()> {
    // Filter AI responses before showing to users

    println!("Generating and moderating AI responses:");

    // Generate response
    let prompt = "Tell me about technology";
    let builder = client.chat().user(prompt).max_completion_tokens(100);
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Generated response: '{}'", content);

        // Moderate the response
        let moderation_result = simulate_moderation(content);

        if moderation_result.flagged {
            println!(
                "  Response flagged! Categories: {:?}",
                moderation_result.categories
            );
            println!("Action: Response blocked or regenerated");

            // Regenerate with more strict instructions
            let safe_builder = client
                .chat()
                .system("Provide helpful, safe, and appropriate responses only.")
                .user(prompt)
                .max_completion_tokens(100);
            let safe_response = client.send_chat(safe_builder).await?;

            if let Some(safe_content) = safe_response.content() {
                println!("Regenerated safe response: '{}'", safe_content);
            }
        } else {
            println!(" Response passed moderation");
        }
    }

    Ok(())
}

fn policy_enforcement(_client: &Client) {
    // Enforce content policies
    let policy = ModerationPolicy {
        thresholds: HashMap::from([
            ("harassment".to_string(), 0.5),
            ("violence".to_string(), 0.6),
            ("sexual".to_string(), 0.4),
        ]),
        auto_reject_categories: vec![
            "harassment/threatening".to_string(),
            "violence/graphic".to_string(),
        ],
        require_human_review: vec!["self-harm".to_string()],
    };

    let test_cases = vec![
        "Normal conversation about work",
        "Slightly aggressive language here",
        "Content requiring review",
    ];

    for content in test_cases {
        println!("Checking: '{}'", content);

        let result = simulate_moderation(content);
        let action = apply_policy(&result, &policy);

        match action {
            PolicyAction::Approve => println!("   Approved"),
            PolicyAction::Reject(reason) => println!("   Rejected: {}", reason),
            PolicyAction::Review(reason) => println!("   Human review needed: {}", reason),
        }
    }
}

async fn moderation_pipeline(client: &Client) -> Result<()> {
    // Complete moderation pipeline

    type FilterFn = Box<dyn Fn(&str) -> bool + Send + Sync>;

    struct ModerationPipeline {
        pre_filters: Vec<FilterFn>,
        post_filters: Vec<FilterFn>,
    }

    let pipeline = ModerationPipeline {
        pre_filters: vec![
            Box::new(|text| text.len() < 10000), // Length check
            Box::new(|text| !text.is_empty()),   // Non-empty check
        ],
        post_filters: vec![
            Box::new(|text| !text.contains("blockedword")), // Custom word filter
        ],
    };

    println!("Running moderation pipeline:");

    let user_input = "Please help me with this technical question about Rust programming.";

    // Step 1: Pre-filters
    println!("1. Pre-filters:");
    for (i, filter) in pipeline.pre_filters.iter().enumerate() {
        if filter(user_input) {
            println!("   Pre-filter {} passed", i + 1);
        } else {
            println!("   Pre-filter {} failed", i + 1);
            return Ok(());
        }
    }

    // Step 2: API moderation
    println!("2. API moderation:");
    let moderation_result = simulate_moderation(user_input);
    if moderation_result.flagged {
        println!("   Content flagged by API");
        return Ok(());
    }
    println!("   Passed API moderation");

    // Step 3: Generate response
    println!("3. Generating response:");
    let builder = client.chat().user(user_input).max_completion_tokens(50);
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("  Generated: '{}'", content);

        // Step 4: Post-filters
        println!("4. Post-filters:");
        for (i, filter) in pipeline.post_filters.iter().enumerate() {
            if filter(content) {
                println!("   Post-filter {} passed", i + 1);
            } else {
                println!("   Post-filter {} failed", i + 1);
                return Ok(());
            }
        }

        // Step 5: Response moderation
        println!("5. Response moderation:");
        let response_moderation = simulate_moderation(content);
        if response_moderation.flagged {
            println!("   Response flagged");
        } else {
            println!("   Response approved");
            println!("\nFinal output: '{}'", content);
        }
    }

    Ok(())
}

examples/chat_comprehensive.rs (line 338)

async fn demonstrate_token_tracking(
    client: &Client,
    conversation: &mut ConversationManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 4: Token Usage Tracking");
    println!("---------------------------------");

    let efficiency_question = "In one sentence, what is machine learning?";
    conversation.add_user_message(efficiency_question.to_string());

    println!("User: {efficiency_question}");
    print!("Assistant: ");
    io::stdout().flush()?;

    // Build chat request
    let messages = conversation.get_conversation_for_api();
    let mut chat_builder = client.chat().max_completion_tokens(50); // Limit tokens for demo

    for (role, content) in messages {
        match role.as_str() {
            "system" => chat_builder = chat_builder.system(content),
            "user" => chat_builder = chat_builder.user(content),
            "assistant" => chat_builder = chat_builder.assistant(content),
            _ => {}
        }
    }

    let response = client.send_chat(chat_builder).await?;

    if let Some(content) = response.content() {
        println!("{content}");

        // Display detailed token usage
        if let Some(usage) = response.usage() {
            println!("\n Token Usage Breakdown:");
            println!("  Prompt tokens: {}", usage.prompt_tokens);
            println!("  Completion tokens: {}", usage.completion_tokens);
            println!("  Total tokens: {}", usage.total_tokens);

            conversation.update_token_usage(usage.prompt_tokens, usage.completion_tokens);

            conversation.add_assistant_message(content.to_string(), Some(usage.completion_tokens));
        } else {
            conversation.add_assistant_message(content.to_string(), None);
        }
    }

    println!();
    Ok(())
}

pub fn stream(self, stream: bool) -> Self

Enable streaming for the completion.

pub fn tools(self, tools: Vec<ChatCompletionTool>) -> Self

Add tools that the model can use.

Examples found in repository

examples/tool_calling.rs (line 132)

async fn simple_tool_call(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("What's the weather like in San Francisco?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        for tool_call in tool_calls {
            println!("Tool called: {}", tool_call.function_name());
            println!("Arguments: {}", tool_call.function_arguments());

            // Execute the function
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("Function result: {}", result);
        }
    }

    Ok(())
}

async fn multiple_tools(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("What's the weather in NYC and what time is it there?")
        .tools(vec![get_weather_tool(), get_time_tool()]);
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        match tool_call.function_name() {
            "get_weather" => {
                let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
                let result = execute_weather_function(params)?;
                println!("Weather result: {}", result);
            }
            "get_current_time" => {
                let params: serde_json::Value =
                    serde_json::from_str(tool_call.function_arguments())?;
                if let Some(timezone) = params["timezone"].as_str() {
                    let result = execute_time_function(timezone);
                    println!("Time result: {}", result);
                }
            }
            _ => println!("Unknown tool: {}", tool_call.function_name()),
        }
    }

    Ok(())
}

async fn tool_choice_control(client: &Client) -> Result<()> {
    // Force specific tool
    println!("Forcing weather tool:");
    let builder = client
        .chat()
        .user("Tell me about Paris")
        .tools(vec![get_weather_tool(), get_time_tool()])
        .tool_choice(ToolChoiceHelper::specific("get_weather"));
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        println!("Forced tool: {}", tool_call.function_name());
    }

    // Disable tools
    println!("\nDisabling tools:");
    let builder = client
        .chat()
        .user("What's the weather?")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::none());
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Response without tools: {}", content);
    }

    Ok(())
}

async fn conversation_with_tools(client: &Client) -> Result<()> {
    // This example demonstrates proper multi-turn tool calling with full message history

    println!("=== Conversation with Tools (Full Implementation) ===");

    // Initialize the conversation
    let mut builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);

    // First request - the model will call the tool
    let response = client.send_chat(builder.clone()).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!("Step 1: Model requests tool call");
        for tool_call in &tool_calls {
            println!("  Tool: {}", tool_call.function_name());
            println!("  Args: {}", tool_call.function_arguments());
        }

        // IMPORTANT: Add the assistant's response (with tool calls) to the history
        // This is the key step for maintaining proper conversation context!
        builder = builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute the tools and add results
        println!("\nStep 2: Execute tools and add results to conversation");
        for tool_call in tool_calls {
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(params)?;
            println!("  Tool result: {}", result);

            // Add the tool result to the conversation history
            builder = builder.tool(tool_call.id(), result);
        }

        // Send the follow-up request with tool results
        println!("\nStep 3: Send follow-up request with tool results");
        let final_response = client
            .send_chat(builder.tools(vec![get_weather_tool()]))
            .await?;

        if let Some(content) = final_response.content() {
            println!("  Final assistant response: {}", content);
        }
    }

    println!("\nNote: This demonstrates the complete tool calling loop with proper");
    println!("message history management using assistant_with_tool_calls()");

    Ok(())
}

fn streaming_with_tools(_client: &Client) {
    println!("Streaming response with tools:");

    // Note: Streaming with tool calls is more complex and requires
    // proper handling of partial tool call chunks. For now, this is
    // a placeholder showing the concept.

    println!("This would demonstrate streaming tool calls if streaming API was available");
    println!("In streaming mode, tool calls would arrive as chunks that need to be assembled");
}

async fn parallel_tool_calls(client: &Client) -> Result<()> {
    let builder = client
        .chat()
        .user("Check the weather in Tokyo, London, and New York")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Modern models can call multiple tools in parallel
    let tool_calls = response.tool_calls();
    println!("Parallel tool calls: {}", tool_calls.len());

    // Collect arguments first to avoid lifetime issues
    let args_vec: Vec<String> = tool_calls
        .iter()
        .map(|tc| tc.function_arguments().to_string())
        .collect();

    // Execute all in parallel using tokio
    let mut handles = Vec::new();
    for args in args_vec {
        let handle = tokio::spawn(async move {
            let params: WeatherParams = serde_json::from_str(&args)?;
            execute_weather_function(params)
        });
        handles.push(handle);
    }

    // Wait for all results
    for (i, handle) in handles.into_iter().enumerate() {
        match handle.await {
            Ok(Ok(result)) => println!("Location {}: {}", i + 1, result),
            Ok(Err(e)) => println!("Location {} error: {}", i + 1, e),
            Err(e) => println!("Task {} panicked: {}", i + 1, e),
        }
    }

    Ok(())
}

examples/tool_calling_simple.rs (line 51)

async fn main() -> Result<()> {
    println!("=== Tool Calling Example ===");

    let client = Client::from_env()?.build();

    // Simple tool call
    let builder = client
        .chat()
        .user("What's the weather like in San Francisco?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        for tool_call in tool_calls {
            println!("Tool called: {}", tool_call.function_name());
            println!("Arguments: {}", tool_call.function_arguments());

            // Execute the function
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(&params);
            println!("Function result: {}", result);
        }
    } else if let Some(content) = response.content() {
        println!("Response: {}", content);
    }

    // Forced tool choice
    println!("\n=== Forced Tool Choice ===");
    let builder = client
        .chat()
        .user("Tell me about Paris")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::specific("get_weather"));
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        println!("Forced tool: {}", tool_call.function_name());
    }

    // No tools
    println!("\n=== No Tools Mode ===");
    let builder = client
        .chat()
        .user("What's the weather?")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::none());
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Response without tools: {}", content);
    }

    Ok(())
}

examples/tool_calling_multiturn.rs (line 178)

async fn handle_tool_loop(
    client: &Client,
    mut chat_builder: openai_ergonomic::builders::chat::ChatCompletionBuilder,
    tools: &[openai_client_base::models::ChatCompletionTool],
    storage: &Arc<Mutex<HashMap<String, String>>>,
) -> Result<String> {
    const MAX_ITERATIONS: usize = 10; // Prevent infinite loops
    let mut iteration = 0;

    loop {
        iteration += 1;
        if iteration > MAX_ITERATIONS {
            return Err(std::io::Error::other("Max iterations reached in tool loop").into());
        }

        println!("\n  [Iteration {}]", iteration);

        // Send request with tools
        let request = chat_builder.clone().tools(tools.to_vec());
        let response = client.send_chat(request).await?;

        // Check if there are tool calls
        let tool_calls = response.tool_calls();
        if tool_calls.is_empty() {
            // No more tool calls, return the final response
            if let Some(content) = response.content() {
                return Ok(content.to_string());
            }
            return Err(std::io::Error::other("No content in final response").into());
        }

        // Process tool calls
        println!("  Tool calls: {}", tool_calls.len());

        // IMPORTANT: Add assistant message with tool calls to history
        // This is the key step that maintains proper conversation context!
        chat_builder = chat_builder.assistant_with_tool_calls(
            response.content().unwrap_or(""),
            tool_calls.iter().map(|tc| (*tc).clone()).collect(),
        );

        // Execute each tool call and add results to history
        for tool_call in tool_calls {
            let tool_name = tool_call.function_name();
            let tool_args = tool_call.function_arguments();
            let tool_id = tool_call.id();

            println!("    → {}: {}", tool_name, tool_args);

            let result = match execute_tool(tool_name, tool_args, storage) {
                Ok(result) => {
                    println!("    ✓ Result: {}", result);
                    result
                }
                Err(e) => {
                    let error_msg = format!("Error: {}", e);
                    eprintln!("    ✗ {}", error_msg);
                    error_msg
                }
            };

            // Add tool result to the conversation
            chat_builder = chat_builder.tool(tool_id, result);
        }
    }
}

pub fn tool_choice(self, tool_choice: ChatCompletionToolChoiceOption) -> Self

Set the tool choice option.

Examples found in repository

examples/tool_calling.rs (line 188)

async fn tool_choice_control(client: &Client) -> Result<()> {
    // Force specific tool
    println!("Forcing weather tool:");
    let builder = client
        .chat()
        .user("Tell me about Paris")
        .tools(vec![get_weather_tool(), get_time_tool()])
        .tool_choice(ToolChoiceHelper::specific("get_weather"));
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        println!("Forced tool: {}", tool_call.function_name());
    }

    // Disable tools
    println!("\nDisabling tools:");
    let builder = client
        .chat()
        .user("What's the weather?")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::none());
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Response without tools: {}", content);
    }

    Ok(())
}

examples/tool_calling_simple.rs (line 76)

async fn main() -> Result<()> {
    println!("=== Tool Calling Example ===");

    let client = Client::from_env()?.build();

    // Simple tool call
    let builder = client
        .chat()
        .user("What's the weather like in San Francisco?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        for tool_call in tool_calls {
            println!("Tool called: {}", tool_call.function_name());
            println!("Arguments: {}", tool_call.function_arguments());

            // Execute the function
            let params: WeatherParams = serde_json::from_str(tool_call.function_arguments())?;
            let result = execute_weather_function(&params);
            println!("Function result: {}", result);
        }
    } else if let Some(content) = response.content() {
        println!("Response: {}", content);
    }

    // Forced tool choice
    println!("\n=== Forced Tool Choice ===");
    let builder = client
        .chat()
        .user("Tell me about Paris")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::specific("get_weather"));
    let response = client.send_chat(builder).await?;

    for tool_call in response.tool_calls() {
        println!("Forced tool: {}", tool_call.function_name());
    }

    // No tools
    println!("\n=== No Tools Mode ===");
    let builder = client
        .chat()
        .user("What's the weather?")
        .tools(vec![get_weather_tool()])
        .tool_choice(ToolChoiceHelper::none());
    let response = client.send_chat(builder).await?;

    if let Some(content) = response.content() {
        println!("Response without tools: {}", content);
    }

    Ok(())
}

pub fn response_format( self, format: CreateChatCompletionRequestAllOfResponseFormat, ) -> Self

Set the response format.

pub fn n(self, n: i32) -> Self

Set the number of completions to generate.

pub fn stop(self, stop: Vec<String>) -> Self

Set stop sequences.

pub fn presence_penalty(self, presence_penalty: f64) -> Self

Set the presence penalty.

pub fn frequency_penalty(self, frequency_penalty: f64) -> Self

Set the frequency penalty.

pub fn top_p(self, top_p: f64) -> Self

Set the top-p value.

pub fn user_id(self, user: impl Into<String>) -> Self

Set the user identifier.

pub fn seed(self, seed: i32) -> Self

Set the random seed for deterministic outputs.

Trait Implementations

impl Builder<CreateChatCompletionRequest> for ChatCompletionBuilder

fn build(self) -> Result<CreateChatCompletionRequest>

Build the final request type.

impl Clone for ChatCompletionBuilder

fn clone(&self) -> ChatCompletionBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChatCompletionBuilder

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

Formats the value using the given formatter.