Struct ChatCompletionResponseWrapper 

pub struct ChatCompletionResponseWrapper { /* private fields */ }

Wrapper for chat completion responses with ergonomic helpers.

Implementations

impl ChatCompletionResponseWrapper

pub fn new(response: CreateChatCompletionResponse) -> Self

Create a new response wrapper.

pub fn with_base_url( response: CreateChatCompletionResponse, base_url: String, ) -> Self

Create a response wrapper with a base URL for generating links.

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

Get the first message content from the response.

Examples found in repository

examples/error_handling.rs (line 68)

async fn basic_error_handling() {
    let client = match Client::from_env() {
        Ok(client_builder) => client_builder.build(),
        Err(e) => {
            println!("Failed to create client: {}", e);
            return;
        }
    };

    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)");
            }
        }
        Err(e) => println!("Error: {}", e),
    }
}

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

async fn hedged_request(client: &Client) -> Result<String> {
    use futures::future::select;
    use std::pin::pin;

    // Launch two requests in parallel
    let request1 = async {
        client
            .send_chat(client.chat_simple("Hello from request 1"))
            .await
    };
    let request2 = async {
        client
            .send_chat(client.chat_simple("Hello from request 2"))
            .await
    };

    let fut1 = pin!(request1);
    let fut2 = pin!(request2);

    // Return first successful response
    match select(fut1, fut2).await {
        futures::future::Either::Left((result, _)) => {
            println!("Request 1 completed first");
            result.map(|r| r.content().unwrap_or("").to_string())
        }
        futures::future::Either::Right((result, _)) => {
            println!("Request 2 completed first");
            result.map(|r| r.content().unwrap_or("").to_string())
        }
    }
}

examples/retry_patterns.rs (line 71)

async fn simple_retry(client: &Client) -> Result<()> {
    const MAX_RETRIES: u32 = 3;

    for attempt in 1..=MAX_RETRIES {
        println!("Attempt {}/{}", attempt, MAX_RETRIES);

        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)");
                }
                return Ok(());
            }
            Err(e) if attempt < MAX_RETRIES => {
                println!("Failed (attempt {}): {}. Retrying...", attempt, e);
                sleep(Duration::from_secs(1)).await;
            }
            Err(e) => {
                println!("All retries exhausted");
                return Err(e);
            }
        }
    }

    Ok(())
}

async fn exponential_backoff(client: &Client) -> Result<()> {
    const MAX_RETRIES: u32 = 5;
    const BASE_DELAY: Duration = Duration::from_millis(100);
    const MAX_DELAY: Duration = Duration::from_secs(32);

    let mut delay = BASE_DELAY;

    for attempt in 1..=MAX_RETRIES {
        match client
            .send_chat(client.chat_simple("Hello with backoff"))
            .await
        {
            Ok(response) => {
                if let Some(content) = response.content() {
                    println!("Success after {} attempts: {}", attempt, content);
                } else {
                    println!("Success after {} attempts: (no content)", attempt);
                }
                return Ok(());
            }
            Err(Error::RateLimit(_message)) => {
                // Use default delay for rate limiting
                let wait_time = delay;
                println!(
                    "Rate limited (attempt {}). Waiting {:?}...",
                    attempt, wait_time
                );
                sleep(wait_time).await;

                // Double the delay for next attempt
                delay = (delay * 2).min(MAX_DELAY);
            }
            Err(e) if attempt < MAX_RETRIES => {
                println!("Error (attempt {}): {}. Waiting {:?}...", attempt, e, delay);
                sleep(delay).await;

                // Exponential increase with cap
                delay = (delay * 2).min(MAX_DELAY);
            }
            Err(e) => return Err(e),
        }
    }

    Ok(())
}

async fn retry_with_jitter(client: &Client) -> Result<()> {
    const MAX_RETRIES: u32 = 5;
    const BASE_DELAY_MS: u64 = 100;

    for attempt in 1..=MAX_RETRIES {
        match client
            .send_chat(client.chat_simple("Hello with jitter"))
            .await
        {
            Ok(response) => {
                if let Some(content) = response.content() {
                    println!("Success: {}", content);
                } else {
                    println!("Success: (no content)");
                }
                return Ok(());
            }
            Err(e) if attempt < MAX_RETRIES => {
                // Calculate delay with jitter using random() instead of thread_rng for Send compatibility
                let base = BASE_DELAY_MS * 2_u64.pow(attempt - 1);
                let jitter = rand::random::<u64>() % (base / 2 + 1);
                let delay = Duration::from_millis(base + jitter);

                println!(
                    "Attempt {} failed: {}. Retrying in {:?} (with jitter)...",
                    attempt, e, delay
                );
                sleep(delay).await;
            }
            Err(e) => return Err(e),
        }
    }

    Ok(())
}

async fn circuit_breaker_example(client: &Client) -> Result<()> {
    let circuit_breaker = Arc::new(CircuitBreaker::new(3, Duration::from_secs(5)));

    for i in 1..=10 {
        println!("Request {}: ", i);

        // Check circuit state
        match circuit_breaker
            .call(|| async {
                client
                    .send_chat(client.chat_simple("Circuit breaker test"))
                    .await
            })
            .await
        {
            Ok(response) => {
                if let Some(content) = response.content() {
                    println!("  Success: {}", content);
                } else {
                    println!("  Success: (no content)");
                }
            }
            Err(CircuitBreakerError::Open) => {
                println!("  Circuit is OPEN - skipping request");
                sleep(Duration::from_secs(1)).await;
            }
            Err(CircuitBreakerError::RequestFailed(e)) => {
                println!("  Request failed: {}", e);
            }
        }

        // Small delay between requests
        sleep(Duration::from_millis(500)).await;
    }

    Ok(())
}

async fn timeout_management(client: &Client) {
    // Example 1: Per-request timeout
    println!("Per-request timeout:");
    match timeout(
        Duration::from_secs(5),
        client.send_chat(client.chat_simple("Hello")),
    )
    .await
    {
        Ok(Ok(response)) => {
            if let Some(content) = response.content() {
                println!("Response received: {}", content);
            } else {
                println!("Response received: (no content)");
            }
        }
        Ok(Err(e)) => println!("API error: {}", e),
        Err(_) => println!("Request timed out after 5 seconds"),
    }

    // Example 2: Deadline-based timeout
    println!("\nDeadline-based timeout:");
    let deadline = Instant::now() + Duration::from_secs(10);

    while Instant::now() < deadline {
        let remaining = deadline - Instant::now();
        println!("Time remaining: {:?}", remaining);

        match timeout(
            remaining,
            client.send_chat(client.chat_simple("Quick response")),
        )
        .await
        {
            Ok(Ok(response)) => {
                if let Some(content) = response.content() {
                    println!("Got response: {}", content);
                } else {
                    println!("Got response: (no content)");
                }
                break;
            }
            Ok(Err(e)) => {
                println!("Error: {}. Retrying...", e);
                sleep(Duration::from_secs(1)).await;
            }
            Err(_) => {
                println!("Deadline exceeded");
                break;
            }
        }
    }

    // Example 3: Adaptive timeout
    println!("\nAdaptive timeout:");
    let mut adaptive_timeout = Duration::from_secs(2);

    for _attempt in 1..=3 {
        let start = Instant::now();

        match timeout(
            adaptive_timeout,
            client.send_chat(client.chat_simple("Adaptive")),
        )
        .await
        {
            Ok(Ok(response)) => {
                let elapsed = start.elapsed();
                println!(
                    "Success in {:?}. Next timeout would be {:?}.",
                    elapsed,
                    elapsed * 2
                );
                // Adjust timeout based on actual response time for potential future requests
                // adaptive_timeout = elapsed * 2; // Not used since we break out of the loop
                if let Some(content) = response.content() {
                    println!("Response: {}", content);
                } else {
                    println!("Response: (no content)");
                }
                break;
            }
            Ok(Err(e)) => println!("Error: {}", e),
            Err(_) => {
                println!(
                    "Timeout after {:?}. Increasing for next attempt.",
                    adaptive_timeout
                );
                adaptive_timeout *= 2;
            }
        }
    }
}

async fn request_hedging(client: &Client) -> Result<()> {
    use futures::future::{select, Either};
    use std::pin::pin;

    println!("Launching hedged requests...");

    // Launch multiple requests with staggered starts
    let request1 = async {
        println!("Request 1 started");
        client
            .send_chat(client.chat_simple("Hedged request 1"))
            .await
    };

    let request2 = async {
        sleep(Duration::from_millis(200)).await;
        println!("Request 2 started (200ms delay)");
        client
            .send_chat(client.chat_simple("Hedged request 2"))
            .await
    };

    let fut1 = pin!(request1);
    let fut2 = pin!(request2);

    // Return first successful response
    match select(fut1, fut2).await {
        Either::Left((result, _)) => {
            println!("Request 1 won the race");
            result.map(|r| {
                if let Some(content) = r.content() {
                    println!("Result: {}", content);
                } else {
                    println!("Result: (no content)");
                }
            })
        }
        Either::Right((result, _)) => {
            println!("Request 2 won the race");
            result.map(|r| {
                if let Some(content) = r.content() {
                    println!("Result: {}", content);
                } else {
                    println!("Result: (no content)");
                }
            })
        }
    }
}

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

async fn idempotency_example(_client: &Client) -> Result<()> {
    // Generate idempotency key
    let idempotency_key = generate_idempotency_key();
    println!("Using idempotency key: {}", idempotency_key);

    // Simulate retrying the same request
    for attempt in 1..=3 {
        println!("\nAttempt {} with same idempotency key", attempt);

        // In a real implementation, you'd pass the idempotency key in headers
        let mut headers = std::collections::HashMap::new();
        headers.insert("Idempotency-Key".to_string(), idempotency_key.clone());
        println!("  Would send {} headers", headers.len());

        let config = Config::builder()
            .api_key(std::env::var("OPENAI_API_KEY").unwrap_or_default())
            .build();

        // Note: Headers (including idempotency key) are not yet supported in current API

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

        match client_with_idempotency
            .send_chat(client_with_idempotency.chat_simple("Idempotent request"))
            .await
        {
            Ok(response) => {
                if let Some(content) = response.content() {
                    println!("Response: {}", content);
                } else {
                    println!("Response: (no content)");
                }
                // Server should return same response for same idempotency key
            }
            Err(e) => println!("Error: {}", e),
        }

        if attempt < 3 {
            sleep(Duration::from_secs(1)).await;
        }
    }

    Ok(())
}

examples/tool_calling.rs (line 204)

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/auth_patterns.rs (line 82)

async fn env_var_auth() -> Result<()> {
    // Standard environment variables:
    // - OPENAI_API_KEY: Your API key
    // - OPENAI_ORG_ID: Optional organization ID
    // - OPENAI_PROJECT_ID: Optional project ID
    // - OPENAI_BASE_URL: Optional custom base URL

    // Check if environment variables are set
    if env::var("OPENAI_API_KEY").is_err() {
        println!("Warning: OPENAI_API_KEY not set");
        println!("Set it with: export OPENAI_API_KEY=your-key-here");
        return Ok(());
    }

    // Create client from environment
    let client = Client::from_env()?.build();
    println!("Client created from environment variables");

    // Test the client
    match client.send_chat(client.chat_simple("Hello")).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("Response: {}", content);
            } else {
                println!("Response: (no content)");
            }
        }
        Err(e) => println!("Error: {}", e),
    }

    Ok(())
}

async fn direct_api_key() -> Result<()> {
    // Create client with direct API key
    let api_key = "sk-your-api-key-here"; // Replace with actual key
    let config = Config::builder().api_key(api_key).build();
    let client = Client::builder(config)?.build();

    println!("Client created with direct API key");

    // Note: This will fail with invalid key
    match client.send_chat(client.chat_simple("Hello")).await {
        Ok(response) => {
            if let Some(content) = response.content() {
                println!("Response: {}", content);
            } else {
                println!("Response: (no content)");
            }
        }
        Err(e) => println!("Expected error with demo key: {}", e),
    }

    Ok(())
}

examples/models.rs (line 190)

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/responses_comprehensive.rs (line 132)

async fn basic_responses_example(client: &Client) -> Result<(), Error> {
    println!("Creating a basic response with system context...");

    // Build a simple request with system and user messages
    let builder = client
        .responses()
        .system("You are a helpful assistant who provides concise, accurate answers.")
        .user("What is the capital of France?")
        .temperature(0.7)
        .max_completion_tokens(100);

    let response = client.send_responses(builder).await?;

    // Extract and display the response
    if let Some(content) = response.content() {
        println!(" Assistant: {content}");
    } else {
        println!("  No content in response");
    }

    // Show response metadata
    println!(" Response metadata:");
    println!("   - Model: {}", response.model().unwrap_or("unknown"));
    println!(
        "   - Finish reason: {}",
        response
            .finish_reason()
            .unwrap_or_else(|| "unknown".to_string())
    );

    if let Some(usage) = response.usage() {
        println!(
            "   - Tokens used: {} prompt + {} completion = {} total",
            usage.prompt_tokens, usage.completion_tokens, usage.total_tokens
        );
    }

    Ok(())
}

/// Example 2: Function calling with custom tools
async fn function_calling_example(client: &Client) -> Result<(), Error> {
    println!("Setting up function calling with custom tools...");

    // Define a weather function tool
    let weather_tool = tool_function(
        "get_weather",
        "Get the current weather information for a specific location",
        json!({
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city name, e.g., 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit preference"
                }
            },
            "required": ["location"],
            "additionalProperties": false
        }),
    );

    // Define a time function tool
    let time_tool = tool_function(
        "get_current_time",
        "Get the current time in a specific timezone",
        json!({
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Timezone name, e.g., 'America/New_York'"
                }
            },
            "required": ["timezone"],
            "additionalProperties": false
        }),
    );

    // Make a request that should trigger function calling
    let builder = client
        .responses()
        .system("You are a helpful assistant with access to weather and time information. Use the provided tools when users ask about weather or time.")
        .user("What's the weather like in London and what time is it there?")
        .tool(weather_tool)
        .tool(time_tool)
        .tool_choice(ToolChoiceHelper::auto())
        .temperature(0.3);

    let response = client.send_responses(builder).await?;

    // Check if the model wants to call functions
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!(" Model requested {} tool call(s):", tool_calls.len());

        for (i, tool_call) in tool_calls.iter().enumerate() {
            println!("   {}. Function: {}", i + 1, tool_call.function_name());
            println!("      Arguments: {}", tool_call.function_arguments());

            // In a real application, you would:
            // 1. Parse the arguments
            // 2. Execute the actual function
            // 3. Send the results back to the model
            println!("      [Simulated] Executing function call...");
            match tool_call.function_name() {
                "get_weather" => {
                    println!("      [Simulated] Weather: 22°C, partly cloudy");
                }
                "get_current_time" => {
                    println!("      [Simulated] Time: 14:30 GMT");
                }
                _ => {
                    println!("      [Simulated] Unknown function");
                }
            }
        }
    } else if let Some(content) = response.content() {
        println!(" Assistant response: {content}");
    }

    Ok(())
}

/// Example 3: Web search integration
async fn web_search_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating web search tool integration...");

    // Create a web search tool
    let web_search_tool = tool_web_search();

    // Ask a question that would benefit from current information
    let builder = client
        .responses()
        .system("You are a helpful assistant with access to web search. When users ask about current events, recent information, or real-time data, use the web search tool to find accurate, up-to-date information.")
        .user("What are the latest developments in artificial intelligence this week?")
        .tool(web_search_tool)
        .tool_choice(ToolChoiceHelper::auto())
        .temperature(0.3)
        .max_completion_tokens(200);

    let response = client.send_responses(builder).await?;

    // Handle the response
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!(" Model requested web search:");

        for tool_call in &tool_calls {
            if tool_call.function_name() == "web_search" {
                println!("   Search query: {}", tool_call.function_arguments());
                println!("   [Simulated] Performing web search...");
                println!("   [Simulated] Found recent AI news and developments");

                // In a real implementation:
                // 1. Parse the search query from arguments
                // 2. Perform actual web search
                // 3. Return results to the model
                // 4. Get final response with search results
            }
        }
    } else if let Some(content) = response.content() {
        println!(" Assistant response: {content}");
    }

    println!(" Note: Web search requires additional implementation to execute actual searches");

    Ok(())
}

/// Example 4: Structured JSON outputs with schemas
async fn structured_output_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating structured JSON outputs...");

    // Define a schema for recipe information
    let recipe_schema = json!({
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Name of the recipe"
            },
            "ingredients": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Ingredient name"
                        },
                        "amount": {
                            "type": "string",
                            "description": "Amount needed"
                        }
                    },
                    "required": ["name", "amount"],
                    "additionalProperties": false
                },
                "description": "List of ingredients"
            },
            "instructions": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "description": "Step-by-step cooking instructions"
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Preparation time in minutes"
            },
            "difficulty": {
                "type": "string",
                "enum": ["easy", "medium", "hard"],
                "description": "Recipe difficulty level"
            }
        },
        "required": ["name", "ingredients", "instructions", "prep_time_minutes", "difficulty"],
        "additionalProperties": false
    });

    // Request a recipe in structured JSON format
    let builder = client
        .responses()
        .system("You are a cooking expert. Provide recipes in the exact JSON format specified.")
        .user("Give me a simple recipe for chocolate chip cookies")
        .json_schema("recipe", recipe_schema)
        .temperature(0.5);

    let response = client.send_responses(builder).await?;

    if let Some(content) = response.content() {
        println!(" Structured recipe output:");

        // Try to parse and pretty-print the JSON
        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);
            }
            Err(_) => {
                println!("Raw response: {content}");
            }
        }
    }

    // Example of simple JSON mode (without schema)
    println!("\n Simple JSON mode example:");
    let simple_builder = client
        .responses()
        .system("Respond in valid JSON format with keys: summary, key_points, sentiment")
        .user("Analyze this text: 'The new product launch exceeded expectations with great customer feedback.'")
        .json_mode()
        .temperature(0.3);

    let simple_response = client.send_responses(simple_builder).await?;

    if let Some(content) = simple_response.content() {
        println!(" Analysis result: {content}");
    }

    Ok(())
}

/// Example 5: Advanced configuration and parameters
async fn advanced_configuration_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating advanced response configuration...");

    // Example with multiple completions and various parameters
    let builder = client
        .responses()
        .system("You are a creative writing assistant. Write in different styles when asked.")
        .user("Write a short tagline for a futuristic coffee shop")
        .temperature(0.9)  // High creativity
        .max_completion_tokens(50)
        .n(1)  // Generate 1 completion
        .top_p(0.9)
        .frequency_penalty(0.1)
        .presence_penalty(0.1)
        .stop(vec!["\n".to_string(), ".".to_string()])
        .seed(42)  // For reproducible results
        .user_id("example_user_123");

    let response = client.send_responses(builder).await?;

    println!(" Creative tagline generation:");
    if let Some(content) = response.content() {
        println!("   Result: {content}");
    }

    // Example with reasoning effort (for o3 models)
    println!("\n Example with reasoning effort (o3 models):");
    let reasoning_builder = client
        .responses()
        .system("You are a logic puzzle solver. Think through problems step by step.")
        .user("If a train leaves Station A at 2 PM going 60 mph, and another train leaves Station B at 3 PM going 80 mph, and the stations are 280 miles apart, when do they meet?")
        .reasoning_effort("medium")
        .temperature(0.1); // Low temperature for accuracy

    let reasoning_response = client.send_responses(reasoning_builder).await?;

    if let Some(content) = reasoning_response.content() {
        println!("   Solution: {content}");
    } else {
        println!("   Note: Reasoning effort requires compatible model (e.g., o3)");
    }

    // Show model information
    println!("\n Model and usage information:");
    println!("   Model used: {}", response.model().unwrap_or("unknown"));
    if let Some(usage) = response.usage() {
        println!(
            "   Token usage: {} total ({} prompt + {} completion)",
            usage.total_tokens, usage.prompt_tokens, usage.completion_tokens
        );
    }

    Ok(())
}

Additional examples can be found in:

• examples/vision_chat.rs
• examples/moderations.rs
• examples/chat_comprehensive.rs
• examples/structured_outputs.rs
• examples/tool_calling_simple.rs
• examples/langfuse_simple.rs
• examples/tool_calling_multiturn.rs
• examples/azure_comprehensive.rs
• examples/azure_openai.rs
• examples/http_middleware_retry.rs
• examples/langfuse.rs
• examples/quickstart.rs

pub fn choices(&self) -> &[CreateChatCompletionResponseChoicesInner]

Get all choices from the response.

pub fn tool_calls(&self) -> Vec<&ChatCompletionMessageToolCallsInner>

Get tool calls from the first choice, if any.

Examples found in repository

examples/tool_calling.rs (line 136)

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

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

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

    Ok(())
}

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

    Ok(())
}

examples/tool_calling_simple.rs (line 55)

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/tool_calling_multiturn.rs (line 182)

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

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

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

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

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

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

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

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

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

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

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

examples/responses_comprehensive.rs (line 214)

async fn function_calling_example(client: &Client) -> Result<(), Error> {
    println!("Setting up function calling with custom tools...");

    // Define a weather function tool
    let weather_tool = tool_function(
        "get_weather",
        "Get the current weather information for a specific location",
        json!({
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city name, e.g., 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit preference"
                }
            },
            "required": ["location"],
            "additionalProperties": false
        }),
    );

    // Define a time function tool
    let time_tool = tool_function(
        "get_current_time",
        "Get the current time in a specific timezone",
        json!({
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Timezone name, e.g., 'America/New_York'"
                }
            },
            "required": ["timezone"],
            "additionalProperties": false
        }),
    );

    // Make a request that should trigger function calling
    let builder = client
        .responses()
        .system("You are a helpful assistant with access to weather and time information. Use the provided tools when users ask about weather or time.")
        .user("What's the weather like in London and what time is it there?")
        .tool(weather_tool)
        .tool(time_tool)
        .tool_choice(ToolChoiceHelper::auto())
        .temperature(0.3);

    let response = client.send_responses(builder).await?;

    // Check if the model wants to call functions
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!(" Model requested {} tool call(s):", tool_calls.len());

        for (i, tool_call) in tool_calls.iter().enumerate() {
            println!("   {}. Function: {}", i + 1, tool_call.function_name());
            println!("      Arguments: {}", tool_call.function_arguments());

            // In a real application, you would:
            // 1. Parse the arguments
            // 2. Execute the actual function
            // 3. Send the results back to the model
            println!("      [Simulated] Executing function call...");
            match tool_call.function_name() {
                "get_weather" => {
                    println!("      [Simulated] Weather: 22°C, partly cloudy");
                }
                "get_current_time" => {
                    println!("      [Simulated] Time: 14:30 GMT");
                }
                _ => {
                    println!("      [Simulated] Unknown function");
                }
            }
        }
    } else if let Some(content) = response.content() {
        println!(" Assistant response: {content}");
    }

    Ok(())
}

/// Example 3: Web search integration
async fn web_search_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating web search tool integration...");

    // Create a web search tool
    let web_search_tool = tool_web_search();

    // Ask a question that would benefit from current information
    let builder = client
        .responses()
        .system("You are a helpful assistant with access to web search. When users ask about current events, recent information, or real-time data, use the web search tool to find accurate, up-to-date information.")
        .user("What are the latest developments in artificial intelligence this week?")
        .tool(web_search_tool)
        .tool_choice(ToolChoiceHelper::auto())
        .temperature(0.3)
        .max_completion_tokens(200);

    let response = client.send_responses(builder).await?;

    // Handle the response
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        println!(" Model requested web search:");

        for tool_call in &tool_calls {
            if tool_call.function_name() == "web_search" {
                println!("   Search query: {}", tool_call.function_arguments());
                println!("   [Simulated] Performing web search...");
                println!("   [Simulated] Found recent AI news and developments");

                // In a real implementation:
                // 1. Parse the search query from arguments
                // 2. Perform actual web search
                // 3. Return results to the model
                // 4. Get final response with search results
            }
        }
    } else if let Some(content) = response.content() {
        println!(" Assistant response: {content}");
    }

    println!(" Note: Web search requires additional implementation to execute actual searches");

    Ok(())
}

examples/quickstart.rs (line 200)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let builder = client
        .responses()
        .user("Write a short haiku about programming")
        .temperature(0.7)
        .stream(true);
    // Note: Full streaming implementation is in development
    // For now, we'll demonstrate non-streaming responses with real-time simulation
    let response = client.send_responses(builder).await;

    match response {
        Ok(chat_response) => {
            print!(": ");
            io::stdout().flush().unwrap();

            // Simulate streaming by printing character by character
            if let Some(content) = chat_response.content() {
                for char in content.chars() {
                    print!("{char}");
                    io::stdout().flush().unwrap();
                    // Small delay to simulate streaming
                    tokio::time::sleep(std::time::Duration::from_millis(30)).await;
                }
            }
            println!(); // New line after "streaming"
        }
        Err(e) => {
            println!("\n Failed to get streaming response: {e}");
        }
    }

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

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

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

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

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

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

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

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

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

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

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

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

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

    let mut total_tokens = 0;

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

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

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

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

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

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

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

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

    Ok(())
}

pub fn is_refusal(&self) -> bool

Check if the response was refused.

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

Get the refusal message if the response was refused.

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

Get the finish reason for the first choice.

Examples found in repository

examples/responses_comprehensive.rs (line 144)

async fn basic_responses_example(client: &Client) -> Result<(), Error> {
    println!("Creating a basic response with system context...");

    // Build a simple request with system and user messages
    let builder = client
        .responses()
        .system("You are a helpful assistant who provides concise, accurate answers.")
        .user("What is the capital of France?")
        .temperature(0.7)
        .max_completion_tokens(100);

    let response = client.send_responses(builder).await?;

    // Extract and display the response
    if let Some(content) = response.content() {
        println!(" Assistant: {content}");
    } else {
        println!("  No content in response");
    }

    // Show response metadata
    println!(" Response metadata:");
    println!("   - Model: {}", response.model().unwrap_or("unknown"));
    println!(
        "   - Finish reason: {}",
        response
            .finish_reason()
            .unwrap_or_else(|| "unknown".to_string())
    );

    if let Some(usage) = response.usage() {
        println!(
            "   - Tokens used: {} prompt + {} completion = {} total",
            usage.prompt_tokens, usage.completion_tokens, usage.total_tokens
        );
    }

    Ok(())
}

pub fn url(&self) -> Option<String>

Generate a URL for this response if base_url was provided.

pub fn inner(&self) -> &CreateChatCompletionResponse

Get the inner response object.

Examples found in repository

examples/quickstart.rs (line 82)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let builder = client
        .responses()
        .user("Write a short haiku about programming")
        .temperature(0.7)
        .stream(true);
    // Note: Full streaming implementation is in development
    // For now, we'll demonstrate non-streaming responses with real-time simulation
    let response = client.send_responses(builder).await;

    match response {
        Ok(chat_response) => {
            print!(": ");
            io::stdout().flush().unwrap();

            // Simulate streaming by printing character by character
            if let Some(content) = chat_response.content() {
                for char in content.chars() {
                    print!("{char}");
                    io::stdout().flush().unwrap();
                    // Small delay to simulate streaming
                    tokio::time::sleep(std::time::Duration::from_millis(30)).await;
                }
            }
            println!(); // New line after "streaming"
        }
        Err(e) => {
            println!("\n Failed to get streaming response: {e}");
        }
    }

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

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

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

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

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

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

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

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

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

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

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

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

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

    let mut total_tokens = 0;

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

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

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

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

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

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

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

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

    Ok(())
}

Trait Implementations

impl Clone for ChatCompletionResponseWrapper

fn clone(&self) -> ChatCompletionResponseWrapper

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChatCompletionResponseWrapper

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

Formats the value using the given formatter.

impl Response for ChatCompletionResponseWrapper

fn id(&self) -> Option<&str>

Get the unique identifier for this response, if available.

fn model(&self) -> Option<&str>

Get the model that generated this response, if available.

fn usage(&self) -> Option<&CompletionUsage>

Get any usage information from the response, if available.