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/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/langfuse.rs (line 79)

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 user(self, content: impl Into<String>) -> Self

Add a user message to the conversation.

Examples found in repository

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 is a simplified version that demonstrates the concept
    // without getting into the complexities of message history management

    println!("=== Conversation with Tools (Simplified) ===");

    // First request with tool call
    let builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls and simulate responses
    for tool_call in response.tool_calls() {
        println!("Tool called: {}", tool_call.function_name());
        println!("Arguments: {}", tool_call.function_arguments());

        // In a real implementation, you would:
        // 1. Parse the arguments
        // 2. Execute the actual function
        // 3. Create tool messages with results
        // 4. Send another request with the tool results

        println!("Simulated weather result: Sunny, 24°C");
    }

    println!("Note: Full conversation with tool results requires complex message handling");
    println!("This simplified version demonstrates tool calling detection");

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

examples/error_handling.rs (line 85)

async fn pattern_matching_errors() {
    let Ok(client_builder) = Client::from_env() else {
        return;
    };
    let client = client_builder.build();

    // Simulate various errors by using invalid parameters
    let builder = client.chat().user("test");
    let result = client.send_chat(builder).await;

    match result {
        Ok(_) => println!("Unexpected success"),
        Err(e) => match e {
            Error::Api { message, .. } => {
                println!("API Error: {}", message);
            }
            Error::RateLimit(message) => {
                println!("Rate limited: {}", message);
            }
            Error::Authentication(message) => {
                println!("Authentication failed: {}", message);
            }
            Error::Http(source) => {
                println!("Network error: {}", source);
            }
            Error::Json(source) => {
                println!("Serialization error: {}", source);
            }
            Error::Stream(message) => {
                println!("Stream error: {}", message);
            }
            Error::InvalidRequest(message) => {
                println!("Invalid request: {}", message);
            }
            Error::Config(message) => {
                println!("Configuration error: {}", message);
            }
            _ => {
                println!("Other error: {}", e);
            }
        },
    }
}

async fn rate_limit_handling() {
    const MAX_RETRIES: u32 = 3;

    let Ok(client_builder) = Client::from_env() else {
        return;
    };
    let client = client_builder.build();

    // Retry logic for rate limiting
    let mut retries = 0;

    loop {
        match client.send_chat(client.chat_simple("Hello")).await {
            Ok(response) => {
                if let Some(content) = response.content() {
                    println!("Success: {}", content);
                } else {
                    println!("Success: (no content)");
                }
                break;
            }
            Err(Error::RateLimit(_message)) => {
                if retries >= MAX_RETRIES {
                    println!("Max retries exceeded");
                    break;
                }

                let wait_time = Duration::from_secs(1);
                println!("Rate limited. Waiting {:?} before retry...", wait_time);
                sleep(wait_time).await;
                retries += 1;
            }
            Err(e) => {
                println!("Other error: {}", e);
                break;
            }
        }
    }
}

async fn token_limit_handling() {
    let Ok(client_builder) = Client::from_env() else {
        return;
    };
    let client = client_builder.build();

    // Generate a very long prompt that might exceed token limits
    let long_text = "Lorem ipsum ".repeat(10000);

    match client.send_chat(client.chat_simple(&long_text)).await {
        Ok(_) => println!("Processed long text successfully"),
        Err(Error::InvalidRequest(message)) if message.contains("token") => {
            println!("Token limit issue: {}", message);

            // Retry with truncated text
            let truncated = &long_text[..1000];
            println!("Retrying with truncated text...");

            match client.send_chat(client.chat_simple(truncated)).await {
                Ok(response) => {
                    if let Some(content) = response.content() {
                        println!("Success with truncated: {}", content);
                    } else {
                        println!("Success with truncated: (no content)");
                    }
                }
                Err(e) => println!("Still failed: {}", e),
            }
        }
        Err(e) => println!("Other error: {}", e),
    }
}

async fn auth_error_handling() -> Result<()> {
    // Try with invalid API key
    let config = Config::builder().api_key("invalid-api-key").build();
    let invalid_client = Client::builder(config)?.build();

    match invalid_client
        .send_chat(invalid_client.chat_simple("Hello"))
        .await
    {
        Ok(_) => println!("Unexpected success"),
        Err(Error::Authentication(message)) => {
            println!("Authentication failed as expected: {}", message);

            // Suggest remediation
            println!("Suggestions:");
            println!("1. Check your OPENAI_API_KEY environment variable");
            println!("2. Verify API key at https://platform.openai.com/api-keys");
            println!("3. Ensure your API key has necessary permissions");
        }
        Err(e) => println!("Unexpected error type: {}", e),
    }

    Ok(())
}

async fn network_error_handling() -> Result<()> {
    use openai_ergonomic::Config;
    use reqwest_middleware::ClientBuilder;

    // Create a reqwest client with very short timeout to simulate network issues
    let reqwest_client = reqwest::Client::builder()
        .timeout(Duration::from_secs(1))
        .build()
        .expect("Failed to build reqwest client");

    let http_client = ClientBuilder::new(reqwest_client).build();

    let config = Config::builder()
        .api_key("test-key")
        .http_client(http_client)
        .build();

    let client = Client::builder(config)?.build();

    match client.send_chat(client.chat_simple("Hello")).await {
        Ok(_) => println!("Unexpected success"),
        Err(Error::Http(source)) => {
            println!("Network error as expected: {}", source);

            // Implement exponential backoff
            let mut backoff = Duration::from_millis(100);
            for attempt in 1..=3 {
                println!("Retry attempt {} after {:?}", attempt, backoff);
                sleep(backoff).await;
                backoff *= 2;

                // In real scenario, retry with proper timeout
                // match client.send_chat(client.chat_simple("Hello")).await { ... }
            }
        }
        Err(e) => println!("Other error: {}", e),
    }

    Ok(())
}

async fn custom_error_context() -> Result<()> {
    let client = Client::from_env()?.build();

    // Wrap errors with custom context
    let result = client
        .send_chat(client.chat_simple("Analyze this data"))
        .await
        .map_err(|e| {
            eprintln!("Context: Failed during data analysis task");
            eprintln!("Timestamp: {:?}", std::time::SystemTime::now());
            eprintln!("Original error: {}", e);
            e
        })?;

    if let Some(content) = result.content() {
        println!("Result: {}", content);
    } else {
        println!("Result: (no content)");
    }
    Ok(())
}

async fn error_recovery_strategies() -> Result<()> {
    let client = Client::from_env()?.build();

    // Strategy 1: Fallback to simpler model
    let result = try_with_fallback(&client, "gpt-4o", "gpt-3.5-turbo").await?;
    println!("Fallback strategy result: {}", result);

    // Strategy 2: Circuit breaker pattern
    let circuit_breaker = CircuitBreaker::new();
    if circuit_breaker.is_open() {
        println!("Circuit breaker is open, skipping API calls");
        return Ok(());
    }

    match client.send_chat(client.chat_simple("Test")).await {
        Ok(response) => {
            circuit_breaker.record_success();
            if let Some(content) = response.content() {
                println!("Circuit breaker success: {}", content);
            } else {
                println!("Circuit breaker success: (no content)");
            }
        }
        Err(e) => {
            circuit_breaker.record_failure();
            println!("Circuit breaker failure: {}", e);
        }
    }

    // Strategy 3: Request hedging (parallel requests with first success wins)
    let hedge_result = hedged_request(&client).await?;
    println!("Hedged request result: {}", hedge_result);

    Ok(())
}

async fn try_with_fallback(client: &Client, primary: &str, _fallback: &str) -> Result<String> {
    // Try primary model first
    let builder = client.chat().user("Hello");
    match client.send_chat(builder).await {
        Ok(response) => Ok(response.content().unwrap_or("").to_string()),
        Err(e) => {
            println!("Primary model failed ({}): {}, trying fallback", primary, e);

            // Try fallback model
            let fallback_builder = client.chat().user("Hello");
            client
                .send_chat(fallback_builder)
                .await
                .map(|r| r.content().unwrap_or("").to_string())
        }
    }
}

examples/chat_comprehensive.rs (line 205)

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

Additional examples can be found in:

• examples/tool_calling_simple.rs
• examples/vision_chat.rs
• examples/azure_comprehensive.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_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/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 temperature(self, temperature: f64) -> Self

Set the temperature for the completion.

Examples found in repository

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/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 is a simplified version that demonstrates the concept
    // without getting into the complexities of message history management

    println!("=== Conversation with Tools (Simplified) ===");

    // First request with tool call
    let builder = client
        .chat()
        .user("What's the weather in Tokyo?")
        .tools(vec![get_weather_tool()]);
    let response = client.send_chat(builder).await?;

    // Check for tool calls and simulate responses
    for tool_call in response.tool_calls() {
        println!("Tool called: {}", tool_call.function_name());
        println!("Arguments: {}", tool_call.function_arguments());

        // In a real implementation, you would:
        // 1. Parse the arguments
        // 2. Execute the actual function
        // 3. Create tool messages with results
        // 4. Send another request with the tool results

        println!("Simulated weather result: Sunny, 24°C");
    }

    println!("Note: Full conversation with tool results requires complex message handling");
    println!("This simplified version demonstrates tool calling detection");

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

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.