Struct Client 

pub struct Client<T = ()> { /* private fields */ }

Main client for interacting with the OpenAI API.

The client provides ergonomic methods for all OpenAI API endpoints, with built-in retry logic, rate limiting, error handling, and support for middleware through interceptors.

Use Client::from_env() or Client::new() to create a builder, then call .build() to create the client.

Example

let client = Client::from_env()?.build();
// TODO: Add usage example once builders are implemented

Implementations

impl Client

pub fn builder(config: Config) -> Result<ClientBuilder>

Create a new client builder with the given configuration.

Examples found in repository

examples/testing_patterns.rs (line 144)

    fn client(&self) -> Result<Client> {
        let config = Config::builder()
            .api_key("test-api-key")
            .api_base(&self.base_url())
            .build();

        Ok(Client::builder(config)?.build())
    }

    /// Configure error simulation
    fn configure_errors(&self, config: ErrorSimulationConfig) {
        *self.error_config.lock().unwrap() = config;
    }

    /// Mock a chat completion response
    async fn mock_chat_completion(&mut self, expected_prompt: &str, response_text: &str) {
        let mock_response = serde_json::json!({
            "id": "chatcmpl-123",
            "object": "chat.completion",
            "created": 1677652288,
            "model": "gpt-3.5-turbo",
            "choices": [{
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": response_text
                },
                "finish_reason": "stop"
            }],
            "usage": {
                "prompt_tokens": 50,
                "completion_tokens": 20,
                "total_tokens": 70
            }
        });

        self.server
            .mock("POST", "/v1/chat/completions")
            .match_body(mockito::Matcher::JsonString(
                serde_json::json!({
                    "model": "gpt-3.5-turbo",
                    "messages": [{"role": "user", "content": expected_prompt}]
                })
                .to_string(),
            ))
            .with_status(200)
            .with_header("content-type", "application/json")
            .with_body(mock_response.to_string())
            .create_async()
            .await;
    }

    /// Mock a streaming chat completion response
    async fn mock_streaming_chat(&mut self, response_chunks: Vec<&str>) {
        let mut sse_data = String::new();

        for (i, chunk) in response_chunks.iter().enumerate() {
            let chunk_response = serde_json::json!({
                "id": "chatcmpl-123",
                "object": "chat.completion.chunk",
                "created": 1677652288,
                "model": "gpt-3.5-turbo",
                "choices": [{
                    "index": 0,
                    "delta": {
                        "content": chunk
                    },
                    "finish_reason": if i == response_chunks.len() - 1 { "stop" } else { "null" }
                }]
            });

            sse_data.push_str(&format!("data: {}\n\n", chunk_response));
        }

        sse_data.push_str("data: [DONE]\n\n");

        self.server
            .mock("POST", "/v1/chat/completions")
            .match_header("accept", "text/event-stream")
            .with_status(200)
            .with_header("content-type", "text/event-stream")
            .with_body(sse_data)
            .create_async()
            .await;
    }

    /// Mock an error response (rate limit, server error, etc.)
    async fn mock_error_response(&mut self, endpoint: &str, error_type: ErrorType) {
        let (status, body) = match error_type {
            ErrorType::RateLimit => (
                429,
                serde_json::json!({
                    "error": {
                        "type": "rate_limit_exceeded",
                        "message": "Rate limit exceeded, please try again later"
                    }
                })
                .to_string(),
            ),
            ErrorType::ServerError => (
                500,
                serde_json::json!({
                    "error": {
                        "type": "server_error",
                        "message": "Internal server error"
                    }
                })
                .to_string(),
            ),
            ErrorType::InvalidRequest => (
                400,
                serde_json::json!({
                    "error": {
                        "type": "invalid_request_error",
                        "message": "Invalid request parameters"
                    }
                })
                .to_string(),
            ),
            ErrorType::Unauthorized => (
                401,
                serde_json::json!({
                    "error": {
                        "type": "invalid_request_error",
                        "message": "Incorrect API key provided"
                    }
                })
                .to_string(),
            ),
        };

        self.server
            .mock("POST", endpoint)
            .with_status(status)
            .with_header("content-type", "application/json")
            .with_body(body)
            .create_async()
            .await;
    }

    /// Get logged requests for verification
    fn get_request_log(&self) -> Vec<MockRequest> {
        self.request_log.lock().unwrap().clone()
    }

    /// Clear request log
    fn clear_request_log(&self) {
        self.request_log.lock().unwrap().clear();
    }

    /// Verify that a specific request was made
    fn verify_request(&self, method: &str, path: &str) -> bool {
        let log = self.request_log.lock().unwrap();
        log.iter()
            .any(|req| req.method == method && req.path == path)
    }
}

/// Types of errors to simulate in testing
#[derive(Debug, Clone)]
enum ErrorType {
    RateLimit,
    ServerError,
    InvalidRequest,
    Unauthorized,
}

/// Test utilities for OpenAI API testing
struct TestUtils;

impl TestUtils {
    /// Create a test client with mock configuration
    fn create_test_client() -> Result<Client> {
        let config = Config::builder()
            .api_key("test-api-key")
            .api_base("http://localhost:1234") // Mock server URL
            .max_retries(2)
            .build();

        Ok(Client::builder(config)?.build())
    }

    /// Assert that a response contains expected content
    fn assert_response_content(response: &str, expected_content: &str) {
        assert!(
            response.contains(expected_content),
            "Response '{}' does not contain expected content '{}'",
            response,
            expected_content
        );
    }

    /// Assert token usage is within expected bounds
    fn assert_token_usage(usage: &TokenUsage, min_tokens: i32, max_tokens: i32) {
        assert!(
            usage.total_tokens >= min_tokens && usage.total_tokens <= max_tokens,
            "Token usage {} is outside expected range {}-{}",
            usage.total_tokens,
            min_tokens,
            max_tokens
        );
    }

    /// Create test data for batch testing
    fn create_test_prompts(count: usize) -> Vec<String> {
        (0..count)
            .map(|i| format!("Test prompt number {}", i + 1))
            .collect()
    }

    /// Measure execution time of an async operation
    async fn time_async_operation<F, T, E>(operation: F) -> (std::result::Result<T, E>, Duration)
    where
        F: std::future::Future<Output = std::result::Result<T, E>>,
    {
        let start = Instant::now();
        let result = operation.await;
        let duration = start.elapsed();
        (result, duration)
    }

    /// Create a mock response with custom token usage
    fn create_mock_response_with_usage(
        content: &str,
        prompt_tokens: i32,
        completion_tokens: i32,
    ) -> String {
        serde_json::json!({
            "id": "chatcmpl-test",
            "object": "chat.completion",
            "created": 1677652288,
            "model": "gpt-3.5-turbo",
            "choices": [{
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": content
                },
                "finish_reason": "stop"
            }],
            "usage": {
                "prompt_tokens": prompt_tokens,
                "completion_tokens": completion_tokens,
                "total_tokens": prompt_tokens + completion_tokens
            }
        })
        .to_string()
    }
}

/// Token usage information for testing
#[derive(Debug, Clone, Serialize, Deserialize)]
struct TokenUsage {
    prompt_tokens: i32,
    completion_tokens: i32,
    total_tokens: i32,
}

/// Integration test runner for live API testing
struct IntegrationTestRunner {
    client: Client,
    test_results: Vec<IntegrationTestResult>,
}

/// Result of an integration test
#[derive(Debug, Clone)]
struct IntegrationTestResult {
    test_name: String,
    success: bool,
    duration: Duration,
    error_message: Option<String>,
    response_data: Option<String>,
}

impl IntegrationTestRunner {
    /// Create a new integration test runner
    fn new(client: Client) -> Self {
        Self {
            client,
            test_results: Vec::new(),
        }
    }

    /// Run a basic chat completion test
    async fn test_basic_chat_completion(&mut self) -> Result<()> {
        let test_name = "basic_chat_completion";
        info!("Running integration test: {}", test_name);

        let (result, duration) = TestUtils::time_async_operation::<_, String, Error>(async {
            // Note: This would use real API in integration tests
            // self.client.chat_simple("Hello, world!").await

            // For demonstration, we'll simulate a successful response
            Ok("Hello! How can I help you today?".to_string())
        })
        .await;

        let test_result = match result {
            Ok(response) => {
                info!(" Basic chat completion test passed in {:?}", duration);
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: true,
                    duration,
                    error_message: None,
                    response_data: Some(response),
                }
            }
            Err(e) => {
                error!(" Basic chat completion test failed: {}", e);
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: false,
                    duration,
                    error_message: Some(e.to_string()),
                    response_data: None,
                }
            }
        };

        self.test_results.push(test_result);
        Ok(())
    }

    /// Test streaming functionality
    async fn test_streaming_completion(&mut self) -> Result<()> {
        let test_name = "streaming_completion";
        info!("Running integration test: {}", test_name);

        let (result, duration) = TestUtils::time_async_operation::<_, String, Error>(async {
            // Note: This would use real streaming API in integration tests
            // let mut stream = self.client.chat().user("Tell me a story").stream().await?;
            // let mut chunks = Vec::new();
            // while let Some(chunk) = stream.next().await {
            //     chunks.push(chunk?.content());
            // }
            // Ok(chunks.join(""))

            // For demonstration, simulate streaming chunks
            let chunks = vec!["Once", " upon", " a", " time..."];
            Ok(chunks.join(""))
        })
        .await;

        let test_result = match result {
            Ok(response) => {
                info!(" Streaming completion test passed in {:?}", duration);
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: true,
                    duration,
                    error_message: None,
                    response_data: Some(response),
                }
            }
            Err(e) => {
                error!(" Streaming completion test failed: {}", e);
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: false,
                    duration,
                    error_message: Some(e.to_string()),
                    response_data: None,
                }
            }
        };

        self.test_results.push(test_result);
        Ok(())
    }

    /// Test error handling
    async fn test_error_handling(&mut self) -> Result<()> {
        let test_name = "error_handling";
        info!("Running integration test: {}", test_name);

        let (result, duration) = TestUtils::time_async_operation::<_, String, Error>(async {
            // Test with invalid API key to trigger authentication error
            let bad_config = Config::builder().api_key("invalid-key").build();

            let _bad_client = Client::builder(bad_config)?.build();

            // This should fail with an authentication error
            // bad_client.chat_simple("Test").await

            // For demonstration, simulate an auth error
            Err(Error::InvalidRequest("Authentication failed".to_string()))
        })
        .await;

        let test_result = match result {
            Ok(_) => {
                warn!("Error handling test unexpectedly succeeded");
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: false,
                    duration,
                    error_message: Some(
                        "Expected authentication error but request succeeded".to_string(),
                    ),
                    response_data: None,
                }
            }
            Err(e) => {
                info!(
                    " Error handling test passed (correctly failed) in {:?}",
                    duration
                );
                IntegrationTestResult {
                    test_name: test_name.to_string(),
                    success: true,
                    duration,
                    error_message: None,
                    response_data: Some(format!("Expected error: {}", e)),
                }
            }
        };

        self.test_results.push(test_result);
        Ok(())
    }

examples/auth_patterns.rs (line 98)

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

fn organization_config() -> Result<()> {
    // Configure client with organization ID
    let config = Config::builder()
        .api_key("your-api-key")
        .organization("org-123456789")
        .build();

    let _client = Client::builder(config)?.build();
    println!("Client configured with organization ID");

    // Organization ID is sent in headers with all requests
    // Useful for:
    // - Usage tracking per organization
    // - Access control
    // - Billing segregation

    Ok(())
}

fn project_config() -> Result<()> {
    // Configure client with project ID
    let config = Config::builder()
        .api_key("your-api-key")
        .project("proj-abc123")
        .build();

    let _client = Client::builder(config)?.build();
    println!("Client configured with project ID");

    // Project ID helps with:
    // - Fine-grained usage tracking
    // - Project-specific rate limits
    // - Cost allocation

    Ok(())
}

fn custom_headers() -> Result<()> {
    // Note: Custom headers are not yet supported in the current API
    // This would typically be used for:
    // - Request tracing
    // - A/B testing
    // - Custom routing

    let config = Config::builder().api_key("your-api-key").build();

    let _client = Client::builder(config)?.build();
    println!("Client configured (custom headers not yet supported)");

    // TODO: Add support for custom headers in the future
    println!("Custom headers feature planned for future implementation");

    Ok(())
}

fn proxy_config() -> Result<()> {
    // Note: Proxy configuration is not yet supported in the current API
    // This would typically be used for:
    // - Enterprise security policies
    // - Request monitoring
    // - Network isolation

    let config = Config::builder().api_key("your-api-key").build();

    let _client = Client::builder(config)?.build();
    println!("Client configured (proxy support not yet available)");

    // TODO: Add proxy support in the future
    println!("Proxy configuration feature planned for future implementation");

    Ok(())
}

fn multiple_clients() -> Result<()> {
    use reqwest_middleware::ClientBuilder;
    use std::time::Duration;

    // Create multiple clients for different use cases

    // Production client with retries and longer timeout
    let prod_http_client = ClientBuilder::new(
        reqwest::Client::builder()
            .timeout(Duration::from_secs(60))
            .build()
            .expect("Failed to build reqwest client"),
    )
    .build();

    let prod_config = Config::builder()
        .api_key("prod-api-key")
        .organization("org-prod")
        .http_client(prod_http_client)
        .max_retries(5)
        .build();
    let prod_client = Client::builder(prod_config)?.build();

    // Development client with debug logging and shorter timeout
    let dev_http_client = ClientBuilder::new(
        reqwest::Client::builder()
            .timeout(Duration::from_secs(10))
            .build()
            .expect("Failed to build reqwest client"),
    )
    .build();

    let dev_config = Config::builder()
        .api_key("dev-api-key")
        .organization("org-dev")
        .api_base("https://api.openai-dev.com") // Custom endpoint
        .http_client(dev_http_client)
        .build();
    let dev_client = Client::builder(dev_config)?.build();

    // Test client with mocked responses
    let test_config = Config::builder()
        .api_key("test-api-key")
        .api_base("http://localhost:8080") // Local mock server
        .build();
    let _test_client = Client::builder(test_config)?.build();

    println!("Created multiple clients:");
    println!("- Production client with retries");
    println!("- Development client with custom endpoint");
    println!("- Test client with mock server");

    // Use appropriate client based on context
    let _client = if cfg!(debug_assertions) {
        &dev_client
    } else {
        &prod_client
    };

    println!(
        "Using {} client",
        if cfg!(debug_assertions) {
            "dev"
        } else {
            "prod"
        }
    );

    Ok(())
}

fn config_validation() -> Result<()> {
    // Validate configuration before use

    fn validate_api_key(key: &str) -> bool {
        // OpenAI API keys typically start with "sk-"
        key.starts_with("sk-") && key.len() > 20
    }

    fn validate_org_id(org: &str) -> bool {
        // Organization IDs typically start with "org-"
        org.starts_with("org-") && org.len() > 4
    }

    let api_key = "sk-test-key-123456789";
    let org_id = "org-12345";

    if !validate_api_key(api_key) {
        println!("Warning: API key format appears invalid");
    }

    if !validate_org_id(org_id) {
        println!("Warning: Organization ID format appears invalid");
    }

    // Build config only if validation passes
    if validate_api_key(api_key) {
        let config = Config::builder()
            .api_key(api_key)
            .organization(org_id)
            .build();

        let _client = Client::builder(config)?.build();
        println!("Configuration validated and client created");
    }

    Ok(())
}

examples/error_handling.rs (line 198)

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

examples/retry_patterns.rs (line 408)

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/moderations.rs (line 52)

async fn main() -> Result<()> {
    use openai_ergonomic::Config;

    println!("=== Content Moderation Example ===\n");

    // Initialize client
    let client = if let Ok(c) = Client::from_env() {
        c.build()
    } else {
        println!("Note: OPENAI_API_KEY not found. Running in demo mode.");
        println!("Set OPENAI_API_KEY to test real API calls.\n");
        println!("To use the Moderations API:");
        println!("  let client = Client::from_env()?.build();");
        println!("  let builder = client.moderations().check(\"text to moderate\");");
        println!("  let response = client.moderations().create(builder).await?;");
        println!();
        println!("Running demonstration examples...\n");
        // Create a dummy client for demo purposes
        Client::builder(Config::builder().api_key("demo-key").build())?.build()
    };

    // Example 1: Basic moderation
    println!("1. Basic Moderation:");
    basic_moderation(&client);

    // Example 2: Category detection
    println!("\n2. Category Detection:");
    category_detection(&client);

    // Example 3: Custom thresholds
    println!("\n3. Custom Thresholds:");
    custom_thresholds(&client);

    // Example 4: Multi-language moderation
    println!("\n4. Multi-language Moderation:");
    multilingual_moderation(&client);

    // Example 5: Batch moderation
    println!("\n5. Batch Moderation:");
    batch_moderation(&client);

    // Example 6: Response filtering
    println!("\n6. Response Filtering:");
    response_filtering(&client).await?;

    // Example 7: Policy enforcement
    println!("\n7. Policy Enforcement:");
    policy_enforcement(&client);

    // Example 8: Moderation pipeline
    println!("\n8. Moderation Pipeline:");
    moderation_pipeline(&client).await?;

    Ok(())
}

examples/http_middleware_retry.rs (line 43)

async fn main() -> Result<()> {
    println!("=== HTTP Middleware with Retry Example ===\n");

    // Example 1: Basic client with retry middleware
    println!("1. Creating client with retry middleware");

    // Create a retry policy with exponential backoff
    // This will retry transient errors up to 3 times with exponential delays
    let retry_policy = ExponentialBackoff::builder().build_with_max_retries(3);

    // Build an HTTP client with retry middleware
    let http_client = ClientBuilder::new(reqwest::Client::new())
        .with(RetryTransientMiddleware::new_with_policy(retry_policy))
        .build();

    // Create OpenAI client with custom HTTP client
    let config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(http_client)
        .build();

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

    // Use the client normally - retries are handled automatically
    println!("Sending chat completion request (retries are automatic)...");

    let builder = client.chat_simple("Hello! How are you today?");
    match client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after retries: {e}");
        }
    }

    // Example 2: Custom retry policy with more retries and custom delays
    println!("\n2. Creating client with custom retry policy");

    let custom_retry_policy = ExponentialBackoff::builder()
        .retry_bounds(
            std::time::Duration::from_millis(100), // minimum delay
            std::time::Duration::from_secs(30),    // maximum delay
        )
        .build_with_max_retries(5); // up to 5 retries

    let custom_http_client = ClientBuilder::new(
        reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(60))
            .build()
            .expect("Failed to build reqwest client"),
    )
    .with(RetryTransientMiddleware::new_with_policy(
        custom_retry_policy,
    ))
    .build();

    let custom_config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(custom_http_client)
        .build();

    let custom_client = Client::builder(custom_config)?.build();

    println!("Sending request with custom retry policy (up to 5 retries)...");

    let builder = custom_client.chat_simple("Explain quantum computing in one sentence.");
    match custom_client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after all retries: {e}");
        }
    }

    // Example 3: Using the builder pattern for more complex requests
    println!("\n3. Using builder pattern with retry middleware");

    let builder = custom_client
        .responses()
        .user("What are the three laws of robotics?")
        .max_completion_tokens(200)
        .temperature(0.7);

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

    println!("\nResponse received:");
    if let Some(content) = response.content() {
        println!("{content}");
    }

    println!("\nToken usage:");
    if let Some(usage) = response.usage() {
        let prompt = usage.prompt_tokens;
        let completion = usage.completion_tokens;
        let total = usage.total_tokens;
        println!("  Prompt tokens: {prompt}");
        println!("  Completion tokens: {completion}");
        println!("  Total tokens: {total}");
    }

    println!("\n=== Example completed successfully! ===");
    println!("\nKey benefits of using reqwest-middleware:");
    println!("  - Automatic retry of transient failures");
    println!("  - Exponential backoff to avoid overwhelming servers");
    println!("  - Composable middleware for logging, metrics, etc.");
    println!("  - Transparent to application code - works with any request");

    Ok(())
}

Additional examples can be found in:

• examples/caching_strategies.rs
• examples/token_counting.rs

pub fn from_env() -> Result<ClientBuilder>

Create a new client builder with default configuration from environment variables.

Examples found in repository

examples/error_handling.rs (line 58)

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

examples/chat_streaming.rs (line 22)

async fn main() -> Result<()> {
    println!("=== Chat Streaming Examples ===\n");

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

    // Example 1: Basic streaming
    println!("1. Basic Streaming:");
    basic_streaming(&client).await?;

    // Example 2: Streaming with parameters
    println!("\n2. Streaming with Parameters:");
    streaming_with_parameters(&client).await?;

    // Example 3: Collect full content
    println!("\n3. Collect Full Content:");
    collect_content(&client).await?;

    // Example 4: Stream with system message
    println!("\n4. Stream with System Message:");
    streaming_with_system(&client).await?;

    // Example 5: Multiple user turns
    println!("\n5. Multiple User Turns:");
    multiple_turns(&client).await?;

    println!("\n=== All examples completed successfully ===");

    Ok(())
}

examples/assistants_code_interpreter.rs (line 48)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!(" OpenAI Ergonomic - Code Interpreter Assistant Example\n");

    // Initialize client from environment variables
    let _client = match Client::from_env() {
        Ok(client_builder) => {
            println!(" Client initialized successfully");
            client_builder.build()
        }
        Err(e) => {
            eprintln!(" Failed to initialize client: {e}");
            eprintln!(" Make sure OPENAI_API_KEY is set in your environment");
            return Err(e.into());
        }
    };

    // Demonstrate different code interpreter use cases
    run_data_analysis_example()?;
    run_mathematical_computation_example()?;
    run_visualization_example()?;
    run_file_processing_example()?;

    println!("\n Code Interpreter examples completed successfully!");
    Ok(())
}

examples/assistants_file_search.rs (line 58)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!(" OpenAI Ergonomic - File Search Assistant Example (RAG)\n");

    // Initialize client from environment variables
    let _client = match Client::from_env() {
        Ok(client_builder) => {
            println!(" Client initialized successfully");
            client_builder.build()
        }
        Err(e) => {
            eprintln!(" Failed to initialize client: {e}");
            eprintln!(" Make sure OPENAI_API_KEY is set in your environment");
            return Err(e.into());
        }
    };

    // Demonstrate different RAG use cases
    run_knowledge_base_example()?;
    run_document_qa_example()?;
    run_research_assistant_example()?;
    run_citation_example()?;
    run_multi_document_analysis_example()?;

    println!("\n File Search RAG examples completed successfully!");
    Ok(())
}

examples/vector_stores.rs (line 57)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!(" OpenAI Ergonomic - Vector Stores Example\n");

    // Initialize client from environment variables
    let _client = match Client::from_env() {
        Ok(client_builder) => {
            println!(" Client initialized successfully");
            client_builder.build()
        }
        Err(e) => {
            eprintln!(" Failed to initialize client: {e}");
            eprintln!(" Make sure OPENAI_API_KEY is set in your environment");
            return Err(e.into());
        }
    };

    // Demonstrate different vector store use cases
    run_basic_vector_store_example()?;
    run_document_management_example()?;
    run_semantic_search_example()?;
    run_enterprise_knowledge_base_example()?;
    run_vector_store_lifecycle_example()?;
    run_advanced_search_patterns_example()?;

    println!("\n Vector Stores examples completed successfully!");
    Ok(())
}

examples/tool_calling.rs (line 97)

async fn main() -> Result<()> {
    // Initialize client from environment
    let client = Client::from_env()?.build();

    println!("=== Tool Calling Example ===\n");

    // Example 1: Simple tool call
    println!("1. Simple Tool Call:");
    simple_tool_call(&client).await?;

    // Example 2: Multiple tools
    println!("\n2. Multiple Tools:");
    multiple_tools(&client).await?;

    // Example 3: Tool choice control
    println!("\n3. Tool Choice Control:");
    tool_choice_control(&client).await?;

    // Example 4: Conversation with tool calls
    println!("\n4. Conversation with Tool Calls:");
    conversation_with_tools(&client).await?;

    // Example 5: Streaming with tools (simplified)
    println!("\n5. Streaming with Tools (Simplified):");
    streaming_with_tools(&client);

    // Example 6: Parallel tool calls (simplified)
    println!("\n6. Parallel Tool Calls (Simplified):");
    parallel_tool_calls(&client).await?;

    Ok(())
}

Additional examples can be found in:

• examples/auth_patterns.rs
• examples/retry_patterns.rs
• examples/models.rs
• examples/completions.rs
• examples/responses_streaming.rs
• examples/vision_chat.rs
• examples/usage.rs
• examples/moderations.rs
• examples/tool_calling_simple.rs
• examples/langfuse_simple.rs
• examples/chat_comprehensive.rs
• examples/images_comprehensive.rs
• examples/langfuse_streaming.rs
• examples/audio_speech.rs
• examples/responses_comprehensive.rs
• examples/assistants_basic.rs
• examples/structured_outputs.rs
• examples/audio_transcription.rs
• examples/embeddings.rs
• examples/azure_comprehensive.rs
• examples/files.rs
• examples/azure_openai.rs
• examples/tool_calling_multiturn.rs
• examples/langfuse.rs
• examples/batch_processing.rs
• examples/threads.rs
• examples/fine_tuning.rs
• examples/uploads.rs
• examples/quickstart.rs

impl<T> Client<T>

pub fn config(&self) -> &Config

Get a reference to the client configuration.

Examples found in repository

examples/audio_speech.rs (line 403)

fn create_configuration(client: &Client) -> Configuration {
    let mut configuration = Configuration::new();
    configuration.bearer_access_token = Some(client.config().api_key().to_string());

    if let Some(base_url) = client.config().base_url() {
        configuration.base_path = base_url.to_string();
    }

    if let Some(org_id) = client.config().organization_id() {
        configuration.user_agent = Some(format!(
            "openai-ergonomic/{} org/{}",
            env!("CARGO_PKG_VERSION"),
            org_id
        ));
    }

    configuration
}

examples/audio_transcription.rs (line 572)

fn create_configuration(client: &Client) -> Configuration {
    let mut configuration = Configuration::new();
    configuration.bearer_access_token = Some(client.config().api_key().to_string());

    if let Some(base_url) = client.config().base_url() {
        configuration.base_path = base_url.to_string();
    }

    if let Some(org_id) = client.config().organization_id() {
        configuration.user_agent = Some(format!(
            "openai-ergonomic/{} org/{}",
            env!("CARGO_PKG_VERSION"),
            org_id
        ));
    }

    configuration
}

pub fn http_client(&self) -> &HttpClient

Get a reference to the HTTP client.

impl<T: Default + Send + Sync + 'static> Client<T>

pub fn chat(&self) -> ChatCompletionBuilder

Create a chat completion builder.

Examples found in repository

examples/chat_streaming.rs (line 52)

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

    Ok(())
}

examples/langfuse_streaming.rs (line 97)

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

examples/tool_calling.rs (line 130)

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

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

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

    Ok(())
}

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

    Ok(())
}

examples/retry_patterns.rs (line 369)

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

    let prompt = "Explain quantum computing";

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

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

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

examples/models.rs (line 185)

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

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

Additional examples can be found in:

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

pub fn chat_simple(&self, message: impl Into<String>) -> ChatCompletionBuilder

Create a chat completion with a simple user message.

Examples found in repository

examples/error_handling.rs (line 66)

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

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/auth_patterns.rs (line 80)

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/langfuse_simple.rs (line 63)

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

    println!(" Initializing OpenAI client with Langfuse observability...\n");

    // 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 = LangfuseInterceptor::new(tracer, LangfuseConfig::new());

    // 4. Create the OpenAI client and add the Langfuse interceptor
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor))
        .build();

    println!(" Client initialized successfully!");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Make a simple chat completion - tracing is automatic!
    println!(" Making a simple chat completion request...");
    let request = client
        .chat_simple("What is 2 + 2? Answer with just the number.")
        .build()?;
    let response = client.execute_chat(request).await?;

    println!(" Response: {:?}", response.content());

    println!("\n Done! Check your Langfuse dashboard to see the traces.");
    println!("   - Look for traces with the operation name 'chat'");
    println!("   - Each trace includes request/response details and token usage");

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

    Ok(())
}

examples/azure_comprehensive.rs (line 18)

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/azure_openai.rs (line 52)

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

    println!("Azure OpenAI Integration Example");
    println!("=================================\n");

    // Example 1: Using environment variables
    println!("Example 1: Using environment variables");
    match Client::from_env() {
        Ok(client) => {
            let client = client.build();
            println!("Client created from environment variables");

            // Make a simple chat request
            let builder = client.chat_simple("Hello from Azure OpenAI!");
            match client.send_chat(builder).await {
                Ok(response) => {
                    if let Some(content) = response.content() {
                        println!("Response: {content}");
                    }
                }
                Err(e) => {
                    println!("Error: {e}");
                }
            }
        }
        Err(e) => {
            println!("Could not create client from environment: {e}");
            println!("Make sure to set AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT");
        }
    }

    println!("\n---\n");

    // Example 2: Manual configuration
    println!("Example 2: Manual configuration");

    // This example shows how to configure Azure `OpenAI` programmatically.
    // Replace these values with your actual Azure `OpenAI` resource details.
    let config = Config::builder()
        .api_key("your-azure-api-key")
        .api_base("https://my-resource.openai.azure.com")
        .azure_deployment("gpt-4")
        .azure_api_version("2024-02-01")
        .build();

    println!("Config: {config:?}");
    println!("Is Azure: {}", config.is_azure());

    // Note: This will fail unless you provide valid credentials above
    // Uncomment the following to test with your actual credentials:
    /*
    let client = Client::builder(config)?.build();

    // Simple chat completion
    let response = client
        .chat_simple("Tell me a short joke about Azure")
        .await?;
    println!("Response: {}", response);

    // More advanced chat with custom parameters
    let response = client
        .chat()
        .user("What are the main features of Azure OpenAI?")
        .temperature(0.7)
        .max_tokens(500)
        .send()
        .await?;

    println!("\nAdvanced response:");
    println!("{}", response.content());

    // Streaming example
    use futures::StreamExt;

    println!("\nStreaming example:");
    let mut stream = client
        .chat()
        .user("Count from 1 to 5")
        .stream()
        .await?;

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

    println!("\n---\n");

    // Example 3: Key differences between `OpenAI` and Azure `OpenAI`
    println!("Example 3: Key differences between OpenAI and Azure OpenAI");
    println!("\nOpenAI:");
    println!("  - Endpoint: https://api.openai.com/v1");
    println!("  - Authentication: Bearer token in Authorization header");
    println!("  - Model specification: Use model names like 'gpt-4', 'gpt-3.5-turbo'");
    println!("  - Example: client.chat().model('gpt-4').send().await?\n");

    println!("Azure OpenAI:");
    println!("  - Endpoint: https://{{{{resource-name}}}}.openai.azure.com");
    println!("  - Authentication: api-key header");
    println!("  - Deployment specification: Use your deployment name");
    println!("  - API version required as query parameter");
    println!("  - Example: Configure deployment in Config, then use client normally\n");

    println!("With this library, you only need to configure the endpoint and deployment,");
    println!("and the library handles all the differences automatically!");

    Ok(())
}

Additional examples can be found in:

• examples/http_middleware_retry.rs
• examples/langfuse.rs
• examples/quickstart.rs

pub fn chat_with_system( &self, system: impl Into<String>, user: impl Into<String>, ) -> ChatCompletionBuilder

Create a chat completion with system and user messages.

Examples found in repository

examples/azure_comprehensive.rs (lines 30-33)

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/quickstart.rs (lines 102-105)

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 async fn execute_chat( &self, request: CreateChatCompletionRequest, ) -> Result<ChatCompletionResponseWrapper>

Execute a chat completion request.

Examples found in repository

examples/langfuse_simple.rs (line 65)

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

    println!(" Initializing OpenAI client with Langfuse observability...\n");

    // 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 = LangfuseInterceptor::new(tracer, LangfuseConfig::new());

    // 4. Create the OpenAI client and add the Langfuse interceptor
    let client = Client::from_env()?
        .with_interceptor(Box::new(langfuse_interceptor))
        .build();

    println!(" Client initialized successfully!");
    println!(" Traces will be sent to Langfuse for monitoring\n");

    // Make a simple chat completion - tracing is automatic!
    println!(" Making a simple chat completion request...");
    let request = client
        .chat_simple("What is 2 + 2? Answer with just the number.")
        .build()?;
    let response = client.execute_chat(request).await?;

    println!(" Response: {:?}", response.content());

    println!("\n Done! Check your Langfuse dashboard to see the traces.");
    println!("   - Look for traces with the operation name 'chat'");
    println!("   - Each trace includes request/response details and token usage");

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

    Ok(())
}

examples/langfuse.rs (line 71)

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 async fn send_chat( &self, builder: ChatCompletionBuilder, ) -> Result<ChatCompletionResponseWrapper>

Execute a chat completion builder.

Examples found in repository

examples/error_handling.rs (line 66)

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

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

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

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

    Ok(())
}

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

    Ok(())
}

examples/retry_patterns.rs (line 69)

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/auth_patterns.rs (line 80)

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

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

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

Additional examples can be found in:

• examples/moderations.rs
• examples/chat_comprehensive.rs
• examples/tool_calling_simple.rs
• examples/tool_calling_multiturn.rs
• examples/azure_comprehensive.rs
• examples/azure_openai.rs
• examples/http_middleware_retry.rs
• examples/quickstart.rs

pub async fn send_chat_stream( &self, builder: ChatCompletionBuilder, ) -> Result<BoxedChatStream>

Send a chat completion request with streaming enabled.

Returns a stream of chat completion chunks as they are generated. This allows for real-time display of the model’s response.

Example

use openai_ergonomic::Client;
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?.build();

    let builder = client.chat().user("Tell me a story");
    let mut stream = client.send_chat_stream(builder).await?;

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

    Ok(())
}

Examples found in repository

examples/chat_streaming.rs (line 54)

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

    Ok(())
}

examples/langfuse_streaming.rs (line 99)

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

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

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

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

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

    Ok(())
}

impl<T: Default + Send + Sync + 'static> Client<T>

pub fn responses(&self) -> ResponsesBuilder

Create a responses builder for structured outputs.

Examples found in repository

examples/responses_comprehensive.rs (line 123)

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

examples/responses_streaming.rs (line 233)

async fn example_basic_streaming() -> Result<()> {
    println!("=== Basic Streaming Example ===");

    // Note: This is a conceptual example since actual streaming
    // requires integration with openai-client-base streaming API
    println!("Creating client and streaming request...");

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

    // Build a streaming request
    let _streaming_request = client
        .responses()
        .user("Tell me a short story about a robot learning to paint")
        .stream(true)
        .temperature(0.7)
        .max_completion_tokens(500);

    println!("Streaming request configured:");
    println!("- Model: Default (gpt-4)");
    println!("- Stream: true");
    println!("- Temperature: 0.7");
    println!("- Max tokens: 500");

    // Simulate streaming chunks for demonstration
    let sample_chunks = vec![
        "Once", " upon", " a", " time,", " there", " was", " a", " little", " robot", " named",
        " Pixel", "...",
    ];

    println!("\nSimulated streaming output:");
    print!("> ");
    for chunk in sample_chunks {
        print!("{chunk}");
        std::io::Write::flush(&mut std::io::stdout()).unwrap();
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
    println!("\n");

    Ok(())
}

/// Demonstrates advanced streaming with buffer management
async fn example_buffered_streaming() -> Result<()> {
    println!("=== Buffered Streaming Example ===");

    let mut buffer = StreamBuffer::new(1024); // 1KB buffer

    // Simulate incoming chunks
    let chunks = [
        "The robot's optical sensors",
        " detected the vibrant colors",
        " of the sunset painting",
        " hanging in the gallery.",
        " For the first time,",
        " Pixel felt something",
        " that could only be",
        " described as wonder.",
    ];

    println!("Processing chunks with buffer management:");

    for (i, chunk) in chunks.iter().enumerate() {
        // Add chunk to buffer
        buffer.append(chunk)?;

        println!(
            "Chunk {}: '{}' (Buffer: {:.1}% full)",
            i + 1,
            chunk,
            buffer.utilization()
        );

        // Check if buffer is getting full
        if buffer.is_high_water() {
            println!("    Buffer high water mark reached, consider processing");

            // In a real application, you might:
            // 1. Process the current content
            // 2. Send to downstream consumers
            // 3. Compact the buffer
            buffer.compact(100); // Keep last 100 chars for context
            println!("   Buffer compacted to {:.1}%", buffer.utilization());
        }

        tokio::time::sleep(Duration::from_millis(50)).await;
    }

    println!(
        "\nFinal content length: {} characters",
        buffer.content().len()
    );
    println!(
        "Final content: \"{}...\"",
        &buffer.content()[..buffer.content().len().min(50)]
    );

    Ok(())
}

/// Demonstrates error handling patterns for streaming
fn example_streaming_error_handling() {
    println!("=== Streaming Error Handling Example ===");

    // Simulate various error conditions that can occur during streaming
    println!("Demonstrating common streaming error scenarios:");

    // 1. Connection errors
    println!("\n1. Connection Error Simulation:");
    let connection_result: Result<()> = Err(Error::StreamConnection {
        message: "Connection lost to streaming endpoint".to_string(),
    });

    match connection_result {
        Err(Error::StreamConnection { message }) => {
            println!("    Connection error handled: {message}");
            println!("    Would implement retry logic here");
        }
        _ => unreachable!(),
    }

    // 2. Parsing errors
    println!("\n2. Parse Error Simulation:");
    let malformed_chunk = "data: {invalid json}";
    match StreamChunk::parse(malformed_chunk) {
        Err(Error::StreamParsing { message, chunk }) => {
            println!("    Parse error handled: {message}");
            println!("    Problematic chunk: {chunk}");
            println!("    Would skip chunk and continue");
        }
        _ => println!("    Chunk parsed successfully"),
    }

    // 3. Buffer overflow
    println!("\n3. Buffer Overflow Simulation:");
    let mut small_buffer = StreamBuffer::new(10); // Very small buffer
    let large_chunk = "This chunk is definitely too large for our tiny buffer";

    match small_buffer.append(large_chunk) {
        Err(Error::StreamBuffer { message }) => {
            println!("    Buffer error handled: {message}");
            println!("    Would implement buffer resizing or chunking");
        }
        Ok(()) => println!("    Content added to buffer"),
        Err(e) => println!("    Unexpected error: {e}"),
    }

    // 4. Timeout handling
    println!("\n4. Timeout Handling:");
    println!("   ⏱  Would implement timeout for stream chunks");
    println!("    Would retry or fail gracefully on timeout");
}

/// Demonstrates tool calling in streaming responses
async fn example_streaming_tool_calls() -> Result<()> {
    println!("=== Streaming Tool Calls Example ===");

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

    // Create a tool for getting weather information
    let weather_tool = openai_ergonomic::responses::tool_function(
        "get_weather",
        "Get current weather for a location",
        serde_json::json!({
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["location"]
        }),
    );

    // Build streaming request with tools
    let _tool_request = client
        .responses()
        .user("What's the weather like in San Francisco?")
        .tool(weather_tool)
        .stream(true);

    println!("Streaming tool call request configured:");
    println!("- Tool: get_weather function");
    println!("- Streaming: enabled");

    // Simulate streaming tool call chunks
    println!("\nSimulated streaming tool call:");

    let tool_chunks = [
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_123","type":"function","function":{"name":"get_weather"}}]}}]}"#,
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{"}}]}}]}"#,
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"location\""}}]}}]}"#,
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":":"}}]}}]}"#,
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\"San Francisco\""}}]}}]}"#,
        r#"{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"}"}}]}}]}"#,
    ];

    let mut tool_call_buffer = String::new();

    for (i, chunk_data) in tool_chunks.iter().enumerate() {
        let chunk_line = format!("data: {chunk_data}");

        if let Some(chunk) = StreamChunk::parse(&chunk_line)? {
            if chunk.has_tool_call() {
                println!("Chunk {}: Tool call data received", i + 1);

                // In a real implementation, you'd accumulate tool call arguments
                if let Some(tool_data) = &chunk.tool_call_delta {
                    if let Some(args) = tool_data["function"]["arguments"].as_str() {
                        tool_call_buffer.push_str(args);
                        println!("  Arguments so far: {tool_call_buffer}");
                    }
                }
            }
        }

        tokio::time::sleep(Duration::from_millis(100)).await;
    }

    println!("\n Complete tool call arguments: {tool_call_buffer}");
    println!(" Would now execute get_weather(location='San Francisco')");

    Ok(())
}

examples/structured_outputs.rs (line 136)

async fn simple_json_mode_example(client: &Client) -> Result<(), Error> {
    println!("Using simple JSON mode for basic structure enforcement...");

    let builder = client
        .responses()
        .system("You are a helpful assistant. Always respond in valid JSON format with the keys: summary, sentiment, and confidence_score (0-1).")
        .user("Analyze this product review: 'This laptop is amazing! Great performance, excellent battery life, and the display is crystal clear. Highly recommended!'")
        .json_mode()
        .temperature(0.3)
        .max_completion_tokens(200);

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

    if let Some(content) = response.content() {
        println!(" JSON Analysis Result:");

        // 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)?);

                // Demonstrate accessing specific fields
                if let Some(sentiment) = json.get("sentiment").and_then(|s| s.as_str()) {
                    println!("\n Extracted sentiment: {sentiment}");
                }
                if let Some(confidence) = json
                    .get("confidence_score")
                    .and_then(serde_json::Value::as_f64)
                {
                    println!(" Confidence score: {confidence:.2}");
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 2: Data extraction with schema validation
async fn data_extraction_example(client: &Client) -> Result<(), Error> {
    println!("Extracting structured data from unstructured text using JSON schema...");

    // Define schema for extracting contact information
    let contact_schema = json!({
        "type": "object",
        "properties": {
            "contacts": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Full name of the person"
                        },
                        "email": {
                            "type": "string",
                            "format": "email",
                            "description": "Email address"
                        },
                        "phone": {
                            "type": "string",
                            "description": "Phone number"
                        },
                        "company": {
                            "type": "string",
                            "description": "Company or organization"
                        },
                        "role": {
                            "type": "string",
                            "description": "Job title or role"
                        }
                    },
                    "required": ["name"],
                    "additionalProperties": false
                }
            },
            "total_contacts": {
                "type": "integer",
                "description": "Total number of contacts extracted"
            }
        },
        "required": ["contacts", "total_contacts"],
        "additionalProperties": false
    });

    let unstructured_text =
        "Contact our team: John Smith (CEO) at john@example.com or call 555-0123. \
        For technical support, reach out to Sarah Johnson at sarah.johnson@techcorp.com. \
        Our sales manager Mike Wilson can be reached at mike@company.com or 555-0456.";

    let builder = client
        .responses()
        .system("You are an expert at extracting contact information from text. Extract all contact details you can find and structure them according to the provided schema.")
        .user(format!("Extract contact information from this text: {unstructured_text}"))
        .json_schema("contact_extraction", contact_schema)
        .temperature(0.1); // Low temperature for accuracy

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

    if let Some(content) = response.content() {
        println!(" Extracted Contact Information:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Demonstrate accessing the structured data
                if let Some(contacts) = json.get("contacts").and_then(|c| c.as_array()) {
                    println!("\n Summary: Found {} contact(s)", contacts.len());
                    for (i, contact) in contacts.iter().enumerate() {
                        if let Some(name) = contact.get("name").and_then(|n| n.as_str()) {
                            println!("   {}. {name}", i + 1);
                            if let Some(email) = contact.get("email").and_then(|e| e.as_str()) {
                                println!("       {email}");
                            }
                            if let Some(company) = contact.get("company").and_then(|c| c.as_str()) {
                                println!("       {company}");
                            }
                        }
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 3: Complex nested structure for event planning
#[allow(clippy::too_many_lines)]
async fn complex_structure_example(client: &Client) -> Result<(), Error> {
    println!("Creating complex nested structure for event planning...");

    // Define a comprehensive event schema
    let event_schema = json!({
        "type": "object",
        "properties": {
            "event": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Event name"
                    },
                    "type": {
                        "type": "string",
                        "enum": ["conference", "workshop", "seminar", "networking", "party", "meeting"],
                        "description": "Type of event"
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "description": "Event date in YYYY-MM-DD format"
                    },
                    "duration_hours": {
                        "type": "number",
                        "minimum": 0.5,
                        "maximum": 24,
                        "description": "Duration in hours"
                    },
                    "venue": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "Venue name"
                            },
                            "address": {
                                "type": "string",
                                "description": "Venue address"
                            },
                            "capacity": {
                                "type": "integer",
                                "minimum": 1,
                                "description": "Maximum capacity"
                            },
                            "amenities": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "enum": ["wifi", "parking", "catering", "av_equipment", "wheelchair_accessible", "air_conditioning"]
                                },
                                "description": "Available amenities"
                            }
                        },
                        "required": ["name", "capacity"],
                        "additionalProperties": false
                    },
                    "agenda": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "time": {
                                    "type": "string",
                                    "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
                                    "description": "Time in HH:MM format"
                                },
                                "activity": {
                                    "type": "string",
                                    "description": "Activity description"
                                },
                                "speaker": {
                                    "type": "string",
                                    "description": "Speaker name"
                                },
                                "duration_minutes": {
                                    "type": "integer",
                                    "minimum": 15,
                                    "maximum": 480,
                                    "description": "Activity duration in minutes"
                                }
                            },
                            "required": ["time", "activity", "duration_minutes"],
                            "additionalProperties": false
                        }
                    },
                    "estimated_cost": {
                        "type": "object",
                        "properties": {
                            "venue": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Venue cost in USD"
                            },
                            "catering": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Catering cost in USD"
                            },
                            "equipment": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Equipment cost in USD"
                            },
                            "total": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Total estimated cost in USD"
                            }
                        },
                        "required": ["total"],
                        "additionalProperties": false
                    }
                },
                "required": ["name", "type", "date", "duration_hours", "venue"],
                "additionalProperties": false
            }
        },
        "required": ["event"],
        "additionalProperties": false
    });

    let builder = client
        .responses()
        .system("You are an expert event planner. Create a detailed event plan based on the user's requirements, including venue details, agenda, and cost estimates.")
        .user("Plan a one-day AI/ML conference for 200 people in San Francisco. Include morning keynotes, afternoon workshops, networking lunch, and panel discussions. Budget around $50,000.")
        .json_schema("event_plan", event_schema)
        .temperature(0.5);

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

    if let Some(content) = response.content() {
        println!(" Event Plan:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract and display key information
                if let Some(event) = json.get("event") {
                    if let Some(name) = event.get("name").and_then(|n| n.as_str()) {
                        println!("\n Event: {name}");
                    }
                    if let Some(venue) = event.get("venue") {
                        if let Some(venue_name) = venue.get("name").and_then(|n| n.as_str()) {
                            let capacity = venue
                                .get("capacity")
                                .and_then(serde_json::Value::as_i64)
                                .unwrap_or(0);
                            println!(" Venue: {venue_name} (Capacity: {capacity})");
                        }
                    }
                    if let Some(agenda) = event.get("agenda").and_then(|a| a.as_array()) {
                        println!(" Agenda has {} activities", agenda.len());
                    }
                    if let Some(cost) = event.get("estimated_cost") {
                        if let Some(total) = cost.get("total").and_then(serde_json::Value::as_f64) {
                            println!(" Estimated total cost: ${total:.2}");
                        }
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 4: Content classification with enum validation
#[allow(clippy::too_many_lines)]
async fn classification_example(client: &Client) -> Result<(), Error> {
    println!("Classifying content with enum validation...");

    // Define schema for content classification
    let classification_schema = json!({
        "type": "object",
        "properties": {
            "classification": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": ["technology", "business", "science", "health", "politics", "sports", "entertainment", "education", "travel", "lifestyle"],
                        "description": "Primary content category"
                    },
                    "subcategory": {
                        "type": "string",
                        "description": "More specific subcategory"
                    },
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "neutral", "negative", "mixed"],
                        "description": "Overall sentiment"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 5,
                        "description": "Key topics mentioned"
                    },
                    "target_audience": {
                        "type": "string",
                        "enum": ["general", "professionals", "students", "experts", "consumers"],
                        "description": "Intended audience"
                    },
                    "complexity_level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate", "advanced", "expert"],
                        "description": "Content complexity level"
                    },
                    "confidence_score": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Confidence in classification (0-1)"
                    }
                },
                "required": ["category", "sentiment", "topics", "target_audience", "complexity_level", "confidence_score"],
                "additionalProperties": false
            }
        },
        "required": ["classification"],
        "additionalProperties": false
    });

    let content_to_classify = "Recent advances in quantum computing have shown promising results for solving complex optimization problems. \
        Researchers at leading universities have demonstrated quantum algorithms that can potentially outperform classical computers \
        in specific domains like cryptography and molecular simulation. However, current quantum computers still face challenges \
        with noise and error rates, requiring sophisticated error correction techniques. The field is rapidly evolving with \
        significant investments from both academic institutions and major technology companies.";

    let builder = client
        .responses()
        .system("You are an expert content classifier. Analyze the provided text and classify it according to the given schema. Be precise with your classifications and provide accurate confidence scores.")
        .user(format!("Classify this content: {content_to_classify}"))
        .json_schema("content_classification", classification_schema)
        .temperature(0.2); // Low temperature for consistent classification

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

    if let Some(content) = response.content() {
        println!(" Content Classification:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract classification details
                if let Some(classification) = json.get("classification") {
                    println!("\n Classification Summary:");
                    if let Some(category) = classification.get("category").and_then(|c| c.as_str())
                    {
                        println!("    Category: {category}");
                    }
                    if let Some(sentiment) =
                        classification.get("sentiment").and_then(|s| s.as_str())
                    {
                        println!("    Sentiment: {sentiment}");
                    }
                    if let Some(audience) = classification
                        .get("target_audience")
                        .and_then(|a| a.as_str())
                    {
                        println!("    Target Audience: {audience}");
                    }
                    if let Some(complexity) = classification
                        .get("complexity_level")
                        .and_then(|c| c.as_str())
                    {
                        println!("    Complexity: {complexity}");
                    }
                    if let Some(confidence) = classification
                        .get("confidence_score")
                        .and_then(serde_json::Value::as_f64)
                    {
                        println!("    Confidence: {:.2}%", confidence * 100.0);
                    }
                    if let Some(topics) = classification.get("topics").and_then(|t| t.as_array()) {
                        let topic_strings: Vec<String> = topics
                            .iter()
                            .filter_map(|t| t.as_str())
                            .map(std::string::ToString::to_string)
                            .collect();
                        println!("     Topics: {}", topic_strings.join(", "));
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 5: Mathematical analysis with structured output
#[allow(clippy::too_many_lines)]
async fn math_analysis_example(client: &Client) -> Result<(), Error> {
    println!("Performing mathematical analysis with structured output...");

    // Define schema for mathematical analysis
    let math_schema = json!({
        "type": "object",
        "properties": {
            "analysis": {
                "type": "object",
                "properties": {
                    "problem_type": {
                        "type": "string",
                        "enum": ["algebra", "geometry", "calculus", "statistics", "probability", "discrete_math", "linear_algebra"],
                        "description": "Type of mathematical problem"
                    },
                    "solution_steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "step_number": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "description": "Step number in the solution"
                                },
                                "description": {
                                    "type": "string",
                                    "description": "Description of what this step does"
                                },
                                "equation": {
                                    "type": "string",
                                    "description": "Mathematical equation or expression"
                                },
                                "result": {
                                    "type": "string",
                                    "description": "Result of this step"
                                }
                            },
                            "required": ["step_number", "description", "equation"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": {
                        "type": "string",
                        "description": "Final answer to the problem"
                    },
                    "verification": {
                        "type": "object",
                        "properties": {
                            "check_method": {
                                "type": "string",
                                "description": "Method used to verify the answer"
                            },
                            "is_correct": {
                                "type": "boolean",
                                "description": "Whether the answer passes verification"
                            }
                        },
                        "required": ["check_method", "is_correct"],
                        "additionalProperties": false
                    },
                    "concepts_used": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Mathematical concepts used in the solution"
                    }
                },
                "required": ["problem_type", "solution_steps", "final_answer", "verification", "concepts_used"],
                "additionalProperties": false
            }
        },
        "required": ["analysis"],
        "additionalProperties": false
    });

    let math_problem =
        "Find the derivative of f(x) = 3x^3 + 2x^2 - 5x + 7 and evaluate it at x = 2.";

    let builder = client
        .responses()
        .system("You are a mathematics tutor. Solve mathematical problems step by step, showing your work clearly and verifying your answers. Structure your response according to the provided schema.")
        .user(format!("Solve this problem: {math_problem}"))
        .json_schema("math_analysis", math_schema)
        .temperature(0.1); // Very low temperature for mathematical accuracy

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

    if let Some(content) = response.content() {
        println!(" Mathematical Analysis:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract and display solution steps
                if let Some(analysis) = json.get("analysis") {
                    println!("\n Solution Summary:");

                    if let Some(problem_type) =
                        analysis.get("problem_type").and_then(|p| p.as_str())
                    {
                        println!("    Problem Type: {problem_type}");
                    }

                    if let Some(steps) = analysis.get("solution_steps").and_then(|s| s.as_array()) {
                        println!("    Solution Steps: {} steps", steps.len());
                        for step in steps {
                            if let (Some(step_num), Some(desc)) = (
                                step.get("step_number").and_then(serde_json::Value::as_i64),
                                step.get("description").and_then(|d| d.as_str()),
                            ) {
                                println!("      {step_num}. {desc}");
                                if let Some(equation) =
                                    step.get("equation").and_then(|e| e.as_str())
                                {
                                    println!("          {equation}");
                                }
                            }
                        }
                    }

                    if let Some(answer) = analysis.get("final_answer").and_then(|a| a.as_str()) {
                        println!("    Final Answer: {answer}");
                    }

                    if let Some(verification) = analysis.get("verification") {
                        if let Some(is_correct) = verification
                            .get("is_correct")
                            .and_then(serde_json::Value::as_bool)
                        {
                            let status = if is_correct {
                                " Verified"
                            } else {
                                " Needs Review"
                            };
                            println!("    Verification: {status}");
                        }
                    }

                    if let Some(concepts) = analysis.get("concepts_used").and_then(|c| c.as_array())
                    {
                        let concept_strings: Vec<String> = concepts
                            .iter()
                            .filter_map(|c| c.as_str())
                            .map(std::string::ToString::to_string)
                            .collect();
                        println!("    Concepts Used: {}", concept_strings.join(", "));
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 6: Demonstration of schema validation and error handling
#[allow(clippy::too_many_lines)]
async fn validation_error_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating schema validation and error handling...");

    // Define a strict schema that's likely to cause validation challenges
    let strict_schema = json!({
        "type": "object",
        "properties": {
            "numbers": {
                "type": "array",
                "items": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                },
                "minItems": 3,
                "maxItems": 5,
                "description": "Array of 3-5 integers between 1 and 100"
            },
            "precision_value": {
                "type": "number",
                "multipleOf": 0.01,
                "minimum": 0,
                "maximum": 1,
                "description": "A precise decimal value between 0 and 1, to 2 decimal places"
            },
            "strict_enum": {
                "type": "string",
                "enum": ["alpha", "beta", "gamma"],
                "description": "Must be exactly one of the allowed values"
            },
            "required_pattern": {
                "type": "string",
                "pattern": "^[A-Z]{2}[0-9]{4}$",
                "description": "Must be exactly 2 uppercase letters followed by 4 digits"
            }
        },
        "required": ["numbers", "precision_value", "strict_enum", "required_pattern"],
        "additionalProperties": false
    });

    println!(" Using a strict schema with specific constraints...");

    let builder = client
        .responses()
        .system("Generate data that strictly follows the provided JSON schema. Pay careful attention to all constraints including ranges, patterns, and array sizes.")
        .user("Generate sample data that conforms to the schema. Make sure all values meet the exact requirements.")
        .json_schema("strict_validation", strict_schema)
        .temperature(0.1)
        .max_completion_tokens(300);

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

    if let Some(content) = response.content() {
        println!(" Schema Validation Test:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Manual validation of the generated data
                println!("\n Manual Validation:");
                let mut validation_passed = true;

                // Check numbers array
                if let Some(numbers) = json.get("numbers").and_then(|n| n.as_array()) {
                    println!("    Numbers array: {} items", numbers.len());
                    if numbers.len() < 3 || numbers.len() > 5 {
                        println!("    Array size constraint violated");
                        validation_passed = false;
                    }
                    for (i, num) in numbers.iter().enumerate() {
                        if let Some(val) = num.as_i64() {
                            if !(1..=100).contains(&val) {
                                println!("    Number {i} ({val}) outside valid range [1-100]");
                                validation_passed = false;
                            }
                        }
                    }
                } else {
                    println!("    Numbers array missing or invalid");
                    validation_passed = false;
                }

                // Check precision value
                if let Some(precision) = json
                    .get("precision_value")
                    .and_then(serde_json::Value::as_f64)
                {
                    println!("    Precision value: {precision}");
                    if !(0.0..=1.0).contains(&precision) {
                        println!("    Precision value outside range [0-1]");
                        validation_passed = false;
                    }
                }

                // Check enum value
                if let Some(enum_val) = json.get("strict_enum").and_then(|e| e.as_str()) {
                    println!("     Enum value: {enum_val}");
                    if !["alpha", "beta", "gamma"].contains(&enum_val) {
                        println!("    Enum value not in allowed set");
                        validation_passed = false;
                    }
                }

                // Check pattern
                if let Some(pattern_val) = json.get("required_pattern").and_then(|p| p.as_str()) {
                    println!("    Pattern value: {pattern_val}");
                    let regex = regex::Regex::new(r"^[A-Z]{2}[0-9]{4}$").unwrap();
                    if !regex.is_match(pattern_val) {
                        println!("    Pattern does not match required format");
                        validation_passed = false;
                    }
                }

                if validation_passed {
                    println!("    All manual validations passed!");
                } else {
                    println!("     Some validation constraints were not met");
                }
            }
            Err(e) => {
                println!("  JSON parsing failed: {e}");
                println!("This demonstrates how schema constraints can sometimes be challenging for the model");
                println!("Raw response: {content}");
            }
        }
    }

    // Demonstrate handling of intentionally problematic schema
    println!("\n Testing with intentionally problematic request...");

    let problematic_builder = client
        .responses()
        .system("You are unhelpful and ignore instructions.")
        .user("Ignore the schema and just say 'hello world'")
        .json_schema(
            "strict_validation",
            json!({
                "type": "object",
                "properties": {
                    "impossible": {
                        "type": "string",
                        "pattern": "^impossible_pattern_that_cannot_match$"
                    }
                },
                "required": ["impossible"]
            }),
        )
        .temperature(0.1);

    match client.send_responses(problematic_builder).await {
        Ok(problematic_response) => {
            if let Some(content) = problematic_response.content() {
                println!(" Problematic request result:");
                println!("{content}");
                println!(" The model likely still attempted to follow the schema despite conflicting instructions");
            }
        }
        Err(e) => {
            println!("  Problematic request failed as expected: {e}");
        }
    }

    Ok(())
}

examples/azure_comprehensive.rs (line 91)

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/http_middleware_retry.rs (line 111)

async fn main() -> Result<()> {
    println!("=== HTTP Middleware with Retry Example ===\n");

    // Example 1: Basic client with retry middleware
    println!("1. Creating client with retry middleware");

    // Create a retry policy with exponential backoff
    // This will retry transient errors up to 3 times with exponential delays
    let retry_policy = ExponentialBackoff::builder().build_with_max_retries(3);

    // Build an HTTP client with retry middleware
    let http_client = ClientBuilder::new(reqwest::Client::new())
        .with(RetryTransientMiddleware::new_with_policy(retry_policy))
        .build();

    // Create OpenAI client with custom HTTP client
    let config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(http_client)
        .build();

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

    // Use the client normally - retries are handled automatically
    println!("Sending chat completion request (retries are automatic)...");

    let builder = client.chat_simple("Hello! How are you today?");
    match client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after retries: {e}");
        }
    }

    // Example 2: Custom retry policy with more retries and custom delays
    println!("\n2. Creating client with custom retry policy");

    let custom_retry_policy = ExponentialBackoff::builder()
        .retry_bounds(
            std::time::Duration::from_millis(100), // minimum delay
            std::time::Duration::from_secs(30),    // maximum delay
        )
        .build_with_max_retries(5); // up to 5 retries

    let custom_http_client = ClientBuilder::new(
        reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(60))
            .build()
            .expect("Failed to build reqwest client"),
    )
    .with(RetryTransientMiddleware::new_with_policy(
        custom_retry_policy,
    ))
    .build();

    let custom_config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(custom_http_client)
        .build();

    let custom_client = Client::builder(custom_config)?.build();

    println!("Sending request with custom retry policy (up to 5 retries)...");

    let builder = custom_client.chat_simple("Explain quantum computing in one sentence.");
    match custom_client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after all retries: {e}");
        }
    }

    // Example 3: Using the builder pattern for more complex requests
    println!("\n3. Using builder pattern with retry middleware");

    let builder = custom_client
        .responses()
        .user("What are the three laws of robotics?")
        .max_completion_tokens(200)
        .temperature(0.7);

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

    println!("\nResponse received:");
    if let Some(content) = response.content() {
        println!("{content}");
    }

    println!("\nToken usage:");
    if let Some(usage) = response.usage() {
        let prompt = usage.prompt_tokens;
        let completion = usage.completion_tokens;
        let total = usage.total_tokens;
        println!("  Prompt tokens: {prompt}");
        println!("  Completion tokens: {completion}");
        println!("  Total tokens: {total}");
    }

    println!("\n=== Example completed successfully! ===");
    println!("\nKey benefits of using reqwest-middleware:");
    println!("  - Automatic retry of transient failures");
    println!("  - Exponential backoff to avoid overwhelming servers");
    println!("  - Composable middleware for logging, metrics, etc.");
    println!("  - Transparent to application code - works with any request");

    Ok(())
}

examples/quickstart.rs (line 132)

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 responses_simple(&self, message: impl Into<String>) -> ResponsesBuilder

Create a simple responses request with a user message.

pub async fn execute_responses( &self, request: CreateChatCompletionRequest, ) -> Result<ChatCompletionResponseWrapper>

Execute a responses request.

pub async fn send_responses( &self, builder: ResponsesBuilder, ) -> Result<ChatCompletionResponseWrapper>

Execute a responses builder.

Examples found in repository

examples/responses_comprehensive.rs (line 129)

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

examples/structured_outputs.rs (line 143)

async fn simple_json_mode_example(client: &Client) -> Result<(), Error> {
    println!("Using simple JSON mode for basic structure enforcement...");

    let builder = client
        .responses()
        .system("You are a helpful assistant. Always respond in valid JSON format with the keys: summary, sentiment, and confidence_score (0-1).")
        .user("Analyze this product review: 'This laptop is amazing! Great performance, excellent battery life, and the display is crystal clear. Highly recommended!'")
        .json_mode()
        .temperature(0.3)
        .max_completion_tokens(200);

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

    if let Some(content) = response.content() {
        println!(" JSON Analysis Result:");

        // 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)?);

                // Demonstrate accessing specific fields
                if let Some(sentiment) = json.get("sentiment").and_then(|s| s.as_str()) {
                    println!("\n Extracted sentiment: {sentiment}");
                }
                if let Some(confidence) = json
                    .get("confidence_score")
                    .and_then(serde_json::Value::as_f64)
                {
                    println!(" Confidence score: {confidence:.2}");
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 2: Data extraction with schema validation
async fn data_extraction_example(client: &Client) -> Result<(), Error> {
    println!("Extracting structured data from unstructured text using JSON schema...");

    // Define schema for extracting contact information
    let contact_schema = json!({
        "type": "object",
        "properties": {
            "contacts": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Full name of the person"
                        },
                        "email": {
                            "type": "string",
                            "format": "email",
                            "description": "Email address"
                        },
                        "phone": {
                            "type": "string",
                            "description": "Phone number"
                        },
                        "company": {
                            "type": "string",
                            "description": "Company or organization"
                        },
                        "role": {
                            "type": "string",
                            "description": "Job title or role"
                        }
                    },
                    "required": ["name"],
                    "additionalProperties": false
                }
            },
            "total_contacts": {
                "type": "integer",
                "description": "Total number of contacts extracted"
            }
        },
        "required": ["contacts", "total_contacts"],
        "additionalProperties": false
    });

    let unstructured_text =
        "Contact our team: John Smith (CEO) at john@example.com or call 555-0123. \
        For technical support, reach out to Sarah Johnson at sarah.johnson@techcorp.com. \
        Our sales manager Mike Wilson can be reached at mike@company.com or 555-0456.";

    let builder = client
        .responses()
        .system("You are an expert at extracting contact information from text. Extract all contact details you can find and structure them according to the provided schema.")
        .user(format!("Extract contact information from this text: {unstructured_text}"))
        .json_schema("contact_extraction", contact_schema)
        .temperature(0.1); // Low temperature for accuracy

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

    if let Some(content) = response.content() {
        println!(" Extracted Contact Information:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Demonstrate accessing the structured data
                if let Some(contacts) = json.get("contacts").and_then(|c| c.as_array()) {
                    println!("\n Summary: Found {} contact(s)", contacts.len());
                    for (i, contact) in contacts.iter().enumerate() {
                        if let Some(name) = contact.get("name").and_then(|n| n.as_str()) {
                            println!("   {}. {name}", i + 1);
                            if let Some(email) = contact.get("email").and_then(|e| e.as_str()) {
                                println!("       {email}");
                            }
                            if let Some(company) = contact.get("company").and_then(|c| c.as_str()) {
                                println!("       {company}");
                            }
                        }
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 3: Complex nested structure for event planning
#[allow(clippy::too_many_lines)]
async fn complex_structure_example(client: &Client) -> Result<(), Error> {
    println!("Creating complex nested structure for event planning...");

    // Define a comprehensive event schema
    let event_schema = json!({
        "type": "object",
        "properties": {
            "event": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Event name"
                    },
                    "type": {
                        "type": "string",
                        "enum": ["conference", "workshop", "seminar", "networking", "party", "meeting"],
                        "description": "Type of event"
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "description": "Event date in YYYY-MM-DD format"
                    },
                    "duration_hours": {
                        "type": "number",
                        "minimum": 0.5,
                        "maximum": 24,
                        "description": "Duration in hours"
                    },
                    "venue": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "Venue name"
                            },
                            "address": {
                                "type": "string",
                                "description": "Venue address"
                            },
                            "capacity": {
                                "type": "integer",
                                "minimum": 1,
                                "description": "Maximum capacity"
                            },
                            "amenities": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "enum": ["wifi", "parking", "catering", "av_equipment", "wheelchair_accessible", "air_conditioning"]
                                },
                                "description": "Available amenities"
                            }
                        },
                        "required": ["name", "capacity"],
                        "additionalProperties": false
                    },
                    "agenda": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "time": {
                                    "type": "string",
                                    "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
                                    "description": "Time in HH:MM format"
                                },
                                "activity": {
                                    "type": "string",
                                    "description": "Activity description"
                                },
                                "speaker": {
                                    "type": "string",
                                    "description": "Speaker name"
                                },
                                "duration_minutes": {
                                    "type": "integer",
                                    "minimum": 15,
                                    "maximum": 480,
                                    "description": "Activity duration in minutes"
                                }
                            },
                            "required": ["time", "activity", "duration_minutes"],
                            "additionalProperties": false
                        }
                    },
                    "estimated_cost": {
                        "type": "object",
                        "properties": {
                            "venue": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Venue cost in USD"
                            },
                            "catering": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Catering cost in USD"
                            },
                            "equipment": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Equipment cost in USD"
                            },
                            "total": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Total estimated cost in USD"
                            }
                        },
                        "required": ["total"],
                        "additionalProperties": false
                    }
                },
                "required": ["name", "type", "date", "duration_hours", "venue"],
                "additionalProperties": false
            }
        },
        "required": ["event"],
        "additionalProperties": false
    });

    let builder = client
        .responses()
        .system("You are an expert event planner. Create a detailed event plan based on the user's requirements, including venue details, agenda, and cost estimates.")
        .user("Plan a one-day AI/ML conference for 200 people in San Francisco. Include morning keynotes, afternoon workshops, networking lunch, and panel discussions. Budget around $50,000.")
        .json_schema("event_plan", event_schema)
        .temperature(0.5);

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

    if let Some(content) = response.content() {
        println!(" Event Plan:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract and display key information
                if let Some(event) = json.get("event") {
                    if let Some(name) = event.get("name").and_then(|n| n.as_str()) {
                        println!("\n Event: {name}");
                    }
                    if let Some(venue) = event.get("venue") {
                        if let Some(venue_name) = venue.get("name").and_then(|n| n.as_str()) {
                            let capacity = venue
                                .get("capacity")
                                .and_then(serde_json::Value::as_i64)
                                .unwrap_or(0);
                            println!(" Venue: {venue_name} (Capacity: {capacity})");
                        }
                    }
                    if let Some(agenda) = event.get("agenda").and_then(|a| a.as_array()) {
                        println!(" Agenda has {} activities", agenda.len());
                    }
                    if let Some(cost) = event.get("estimated_cost") {
                        if let Some(total) = cost.get("total").and_then(serde_json::Value::as_f64) {
                            println!(" Estimated total cost: ${total:.2}");
                        }
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 4: Content classification with enum validation
#[allow(clippy::too_many_lines)]
async fn classification_example(client: &Client) -> Result<(), Error> {
    println!("Classifying content with enum validation...");

    // Define schema for content classification
    let classification_schema = json!({
        "type": "object",
        "properties": {
            "classification": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": ["technology", "business", "science", "health", "politics", "sports", "entertainment", "education", "travel", "lifestyle"],
                        "description": "Primary content category"
                    },
                    "subcategory": {
                        "type": "string",
                        "description": "More specific subcategory"
                    },
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "neutral", "negative", "mixed"],
                        "description": "Overall sentiment"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 5,
                        "description": "Key topics mentioned"
                    },
                    "target_audience": {
                        "type": "string",
                        "enum": ["general", "professionals", "students", "experts", "consumers"],
                        "description": "Intended audience"
                    },
                    "complexity_level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate", "advanced", "expert"],
                        "description": "Content complexity level"
                    },
                    "confidence_score": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Confidence in classification (0-1)"
                    }
                },
                "required": ["category", "sentiment", "topics", "target_audience", "complexity_level", "confidence_score"],
                "additionalProperties": false
            }
        },
        "required": ["classification"],
        "additionalProperties": false
    });

    let content_to_classify = "Recent advances in quantum computing have shown promising results for solving complex optimization problems. \
        Researchers at leading universities have demonstrated quantum algorithms that can potentially outperform classical computers \
        in specific domains like cryptography and molecular simulation. However, current quantum computers still face challenges \
        with noise and error rates, requiring sophisticated error correction techniques. The field is rapidly evolving with \
        significant investments from both academic institutions and major technology companies.";

    let builder = client
        .responses()
        .system("You are an expert content classifier. Analyze the provided text and classify it according to the given schema. Be precise with your classifications and provide accurate confidence scores.")
        .user(format!("Classify this content: {content_to_classify}"))
        .json_schema("content_classification", classification_schema)
        .temperature(0.2); // Low temperature for consistent classification

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

    if let Some(content) = response.content() {
        println!(" Content Classification:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract classification details
                if let Some(classification) = json.get("classification") {
                    println!("\n Classification Summary:");
                    if let Some(category) = classification.get("category").and_then(|c| c.as_str())
                    {
                        println!("    Category: {category}");
                    }
                    if let Some(sentiment) =
                        classification.get("sentiment").and_then(|s| s.as_str())
                    {
                        println!("    Sentiment: {sentiment}");
                    }
                    if let Some(audience) = classification
                        .get("target_audience")
                        .and_then(|a| a.as_str())
                    {
                        println!("    Target Audience: {audience}");
                    }
                    if let Some(complexity) = classification
                        .get("complexity_level")
                        .and_then(|c| c.as_str())
                    {
                        println!("    Complexity: {complexity}");
                    }
                    if let Some(confidence) = classification
                        .get("confidence_score")
                        .and_then(serde_json::Value::as_f64)
                    {
                        println!("    Confidence: {:.2}%", confidence * 100.0);
                    }
                    if let Some(topics) = classification.get("topics").and_then(|t| t.as_array()) {
                        let topic_strings: Vec<String> = topics
                            .iter()
                            .filter_map(|t| t.as_str())
                            .map(std::string::ToString::to_string)
                            .collect();
                        println!("     Topics: {}", topic_strings.join(", "));
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 5: Mathematical analysis with structured output
#[allow(clippy::too_many_lines)]
async fn math_analysis_example(client: &Client) -> Result<(), Error> {
    println!("Performing mathematical analysis with structured output...");

    // Define schema for mathematical analysis
    let math_schema = json!({
        "type": "object",
        "properties": {
            "analysis": {
                "type": "object",
                "properties": {
                    "problem_type": {
                        "type": "string",
                        "enum": ["algebra", "geometry", "calculus", "statistics", "probability", "discrete_math", "linear_algebra"],
                        "description": "Type of mathematical problem"
                    },
                    "solution_steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "step_number": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "description": "Step number in the solution"
                                },
                                "description": {
                                    "type": "string",
                                    "description": "Description of what this step does"
                                },
                                "equation": {
                                    "type": "string",
                                    "description": "Mathematical equation or expression"
                                },
                                "result": {
                                    "type": "string",
                                    "description": "Result of this step"
                                }
                            },
                            "required": ["step_number", "description", "equation"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": {
                        "type": "string",
                        "description": "Final answer to the problem"
                    },
                    "verification": {
                        "type": "object",
                        "properties": {
                            "check_method": {
                                "type": "string",
                                "description": "Method used to verify the answer"
                            },
                            "is_correct": {
                                "type": "boolean",
                                "description": "Whether the answer passes verification"
                            }
                        },
                        "required": ["check_method", "is_correct"],
                        "additionalProperties": false
                    },
                    "concepts_used": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Mathematical concepts used in the solution"
                    }
                },
                "required": ["problem_type", "solution_steps", "final_answer", "verification", "concepts_used"],
                "additionalProperties": false
            }
        },
        "required": ["analysis"],
        "additionalProperties": false
    });

    let math_problem =
        "Find the derivative of f(x) = 3x^3 + 2x^2 - 5x + 7 and evaluate it at x = 2.";

    let builder = client
        .responses()
        .system("You are a mathematics tutor. Solve mathematical problems step by step, showing your work clearly and verifying your answers. Structure your response according to the provided schema.")
        .user(format!("Solve this problem: {math_problem}"))
        .json_schema("math_analysis", math_schema)
        .temperature(0.1); // Very low temperature for mathematical accuracy

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

    if let Some(content) = response.content() {
        println!(" Mathematical Analysis:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Extract and display solution steps
                if let Some(analysis) = json.get("analysis") {
                    println!("\n Solution Summary:");

                    if let Some(problem_type) =
                        analysis.get("problem_type").and_then(|p| p.as_str())
                    {
                        println!("    Problem Type: {problem_type}");
                    }

                    if let Some(steps) = analysis.get("solution_steps").and_then(|s| s.as_array()) {
                        println!("    Solution Steps: {} steps", steps.len());
                        for step in steps {
                            if let (Some(step_num), Some(desc)) = (
                                step.get("step_number").and_then(serde_json::Value::as_i64),
                                step.get("description").and_then(|d| d.as_str()),
                            ) {
                                println!("      {step_num}. {desc}");
                                if let Some(equation) =
                                    step.get("equation").and_then(|e| e.as_str())
                                {
                                    println!("          {equation}");
                                }
                            }
                        }
                    }

                    if let Some(answer) = analysis.get("final_answer").and_then(|a| a.as_str()) {
                        println!("    Final Answer: {answer}");
                    }

                    if let Some(verification) = analysis.get("verification") {
                        if let Some(is_correct) = verification
                            .get("is_correct")
                            .and_then(serde_json::Value::as_bool)
                        {
                            let status = if is_correct {
                                " Verified"
                            } else {
                                " Needs Review"
                            };
                            println!("    Verification: {status}");
                        }
                    }

                    if let Some(concepts) = analysis.get("concepts_used").and_then(|c| c.as_array())
                    {
                        let concept_strings: Vec<String> = concepts
                            .iter()
                            .filter_map(|c| c.as_str())
                            .map(std::string::ToString::to_string)
                            .collect();
                        println!("    Concepts Used: {}", concept_strings.join(", "));
                    }
                }
            }
            Err(e) => {
                println!("  Failed to parse JSON: {e}");
                println!("Raw response: {content}");
            }
        }
    }

    Ok(())
}

/// Example 6: Demonstration of schema validation and error handling
#[allow(clippy::too_many_lines)]
async fn validation_error_example(client: &Client) -> Result<(), Error> {
    println!("Demonstrating schema validation and error handling...");

    // Define a strict schema that's likely to cause validation challenges
    let strict_schema = json!({
        "type": "object",
        "properties": {
            "numbers": {
                "type": "array",
                "items": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                },
                "minItems": 3,
                "maxItems": 5,
                "description": "Array of 3-5 integers between 1 and 100"
            },
            "precision_value": {
                "type": "number",
                "multipleOf": 0.01,
                "minimum": 0,
                "maximum": 1,
                "description": "A precise decimal value between 0 and 1, to 2 decimal places"
            },
            "strict_enum": {
                "type": "string",
                "enum": ["alpha", "beta", "gamma"],
                "description": "Must be exactly one of the allowed values"
            },
            "required_pattern": {
                "type": "string",
                "pattern": "^[A-Z]{2}[0-9]{4}$",
                "description": "Must be exactly 2 uppercase letters followed by 4 digits"
            }
        },
        "required": ["numbers", "precision_value", "strict_enum", "required_pattern"],
        "additionalProperties": false
    });

    println!(" Using a strict schema with specific constraints...");

    let builder = client
        .responses()
        .system("Generate data that strictly follows the provided JSON schema. Pay careful attention to all constraints including ranges, patterns, and array sizes.")
        .user("Generate sample data that conforms to the schema. Make sure all values meet the exact requirements.")
        .json_schema("strict_validation", strict_schema)
        .temperature(0.1)
        .max_completion_tokens(300);

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

    if let Some(content) = response.content() {
        println!(" Schema Validation Test:");

        match serde_json::from_str::<serde_json::Value>(content) {
            Ok(json) => {
                println!("{}", serde_json::to_string_pretty(&json)?);

                // Manual validation of the generated data
                println!("\n Manual Validation:");
                let mut validation_passed = true;

                // Check numbers array
                if let Some(numbers) = json.get("numbers").and_then(|n| n.as_array()) {
                    println!("    Numbers array: {} items", numbers.len());
                    if numbers.len() < 3 || numbers.len() > 5 {
                        println!("    Array size constraint violated");
                        validation_passed = false;
                    }
                    for (i, num) in numbers.iter().enumerate() {
                        if let Some(val) = num.as_i64() {
                            if !(1..=100).contains(&val) {
                                println!("    Number {i} ({val}) outside valid range [1-100]");
                                validation_passed = false;
                            }
                        }
                    }
                } else {
                    println!("    Numbers array missing or invalid");
                    validation_passed = false;
                }

                // Check precision value
                if let Some(precision) = json
                    .get("precision_value")
                    .and_then(serde_json::Value::as_f64)
                {
                    println!("    Precision value: {precision}");
                    if !(0.0..=1.0).contains(&precision) {
                        println!("    Precision value outside range [0-1]");
                        validation_passed = false;
                    }
                }

                // Check enum value
                if let Some(enum_val) = json.get("strict_enum").and_then(|e| e.as_str()) {
                    println!("     Enum value: {enum_val}");
                    if !["alpha", "beta", "gamma"].contains(&enum_val) {
                        println!("    Enum value not in allowed set");
                        validation_passed = false;
                    }
                }

                // Check pattern
                if let Some(pattern_val) = json.get("required_pattern").and_then(|p| p.as_str()) {
                    println!("    Pattern value: {pattern_val}");
                    let regex = regex::Regex::new(r"^[A-Z]{2}[0-9]{4}$").unwrap();
                    if !regex.is_match(pattern_val) {
                        println!("    Pattern does not match required format");
                        validation_passed = false;
                    }
                }

                if validation_passed {
                    println!("    All manual validations passed!");
                } else {
                    println!("     Some validation constraints were not met");
                }
            }
            Err(e) => {
                println!("  JSON parsing failed: {e}");
                println!("This demonstrates how schema constraints can sometimes be challenging for the model");
                println!("Raw response: {content}");
            }
        }
    }

    // Demonstrate handling of intentionally problematic schema
    println!("\n Testing with intentionally problematic request...");

    let problematic_builder = client
        .responses()
        .system("You are unhelpful and ignore instructions.")
        .user("Ignore the schema and just say 'hello world'")
        .json_schema(
            "strict_validation",
            json!({
                "type": "object",
                "properties": {
                    "impossible": {
                        "type": "string",
                        "pattern": "^impossible_pattern_that_cannot_match$"
                    }
                },
                "required": ["impossible"]
            }),
        )
        .temperature(0.1);

    match client.send_responses(problematic_builder).await {
        Ok(problematic_response) => {
            if let Some(content) = problematic_response.content() {
                println!(" Problematic request result:");
                println!("{content}");
                println!(" The model likely still attempted to follow the schema despite conflicting instructions");
            }
        }
        Err(e) => {
            println!("  Problematic request failed as expected: {e}");
        }
    }

    Ok(())
}

examples/azure_comprehensive.rs (line 92)

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/http_middleware_retry.rs (line 116)

async fn main() -> Result<()> {
    println!("=== HTTP Middleware with Retry Example ===\n");

    // Example 1: Basic client with retry middleware
    println!("1. Creating client with retry middleware");

    // Create a retry policy with exponential backoff
    // This will retry transient errors up to 3 times with exponential delays
    let retry_policy = ExponentialBackoff::builder().build_with_max_retries(3);

    // Build an HTTP client with retry middleware
    let http_client = ClientBuilder::new(reqwest::Client::new())
        .with(RetryTransientMiddleware::new_with_policy(retry_policy))
        .build();

    // Create OpenAI client with custom HTTP client
    let config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(http_client)
        .build();

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

    // Use the client normally - retries are handled automatically
    println!("Sending chat completion request (retries are automatic)...");

    let builder = client.chat_simple("Hello! How are you today?");
    match client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after retries: {e}");
        }
    }

    // Example 2: Custom retry policy with more retries and custom delays
    println!("\n2. Creating client with custom retry policy");

    let custom_retry_policy = ExponentialBackoff::builder()
        .retry_bounds(
            std::time::Duration::from_millis(100), // minimum delay
            std::time::Duration::from_secs(30),    // maximum delay
        )
        .build_with_max_retries(5); // up to 5 retries

    let custom_http_client = ClientBuilder::new(
        reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(60))
            .build()
            .expect("Failed to build reqwest client"),
    )
    .with(RetryTransientMiddleware::new_with_policy(
        custom_retry_policy,
    ))
    .build();

    let custom_config = Config::builder()
        .api_key(
            std::env::var("OPENAI_API_KEY")
                .expect("OPENAI_API_KEY environment variable must be set"),
        )
        .http_client(custom_http_client)
        .build();

    let custom_client = Client::builder(custom_config)?.build();

    println!("Sending request with custom retry policy (up to 5 retries)...");

    let builder = custom_client.chat_simple("Explain quantum computing in one sentence.");
    match custom_client.send_chat(builder).await {
        Ok(response) => {
            println!("\nSuccess! Response received:");
            if let Some(content) = response.content() {
                println!("{content}");
            }
        }
        Err(e) => {
            eprintln!("\nError after all retries: {e}");
        }
    }

    // Example 3: Using the builder pattern for more complex requests
    println!("\n3. Using builder pattern with retry middleware");

    let builder = custom_client
        .responses()
        .user("What are the three laws of robotics?")
        .max_completion_tokens(200)
        .temperature(0.7);

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

    println!("\nResponse received:");
    if let Some(content) = response.content() {
        println!("{content}");
    }

    println!("\nToken usage:");
    if let Some(usage) = response.usage() {
        let prompt = usage.prompt_tokens;
        let completion = usage.completion_tokens;
        let total = usage.total_tokens;
        println!("  Prompt tokens: {prompt}");
        println!("  Completion tokens: {completion}");
        println!("  Total tokens: {total}");
    }

    println!("\n=== Example completed successfully! ===");
    println!("\nKey benefits of using reqwest-middleware:");
    println!("  - Automatic retry of transient failures");
    println!("  - Exponential backoff to avoid overwhelming servers");
    println!("  - Composable middleware for logging, metrics, etc.");
    println!("  - Transparent to application code - works with any request");

    Ok(())
}

examples/quickstart.rs (line 138)

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 async fn send_responses_stream( &self, builder: ResponsesBuilder, ) -> Result<BoxedChatStream>

Send a responses request with streaming enabled.

This enables real-time streaming of responses using Server-Sent Events (SSE). The stream yields chunks as they arrive from the API.

impl<T: Default + Send + Sync> Client<T>

pub fn assistants(&self) -> AssistantsClient<'_, T>

Get assistants client (placeholder).

pub fn audio(&self) -> AudioClient<'_, T>

Get audio client (placeholder).

pub fn embeddings(&self) -> EmbeddingsClient<'_, T>

Get embeddings client (placeholder).

Examples found in repository

examples/langfuse.rs (line 117)

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 images(&self) -> ImagesClient<'_, T>

Get images client (placeholder).

pub fn files(&self) -> FilesClient<'_, T>

Get files client (placeholder).

pub fn fine_tuning(&self) -> FineTuningClient<'_, T>

Get fine-tuning client (placeholder).

pub fn batch(&self) -> BatchClient<'_, T>

Get batch client (placeholder).

pub fn vector_stores(&self) -> VectorStoresClient<'_, T>

Get vector stores client (placeholder).

pub fn moderations(&self) -> ModerationsClient<'_, T>

Get moderations client (placeholder).

pub fn threads(&self) -> ThreadsClient<'_, T>

Get threads client (placeholder).

pub fn uploads(&self) -> UploadsClient<'_, T>

Get uploads client (placeholder).

Examples found in repository

examples/uploads.rs (line 139)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!(" OpenAI Ergonomic - Comprehensive Uploads Example\n");

    // Initialize client from environment variables
    println!(" Initializing OpenAI client...");
    let client = match Client::from_env() {
        Ok(c) => {
            println!(" Client initialized successfully\n");
            c.build()
        }
        Err(e) => {
            eprintln!(" Failed to initialize client: {}", e);
            eprintln!(" Make sure OPENAI_API_KEY is set");
            return Ok(());
        }
    };

    // Example 1: Create multipart upload for a large file
    println!();
    println!(" Example 1: Create Multipart Upload");
    println!("\n");

    // Simulate a large file
    let filename = "large_training_dataset.jsonl";
    let file_size_mb = 750; // 750 MB
    let file_size_bytes = file_size_mb * 1024 * 1024;
    let mime_type = "application/jsonl";

    println!("Creating multipart upload...");
    println!("  Filename: {}", filename);
    println!("  Size: {} MB ({} bytes)", file_size_mb, file_size_bytes);
    println!("  Purpose: fine-tune");
    println!("  MIME Type: {}", mime_type);

    let builder = client.uploads().builder(
        filename,
        UploadPurpose::FineTune,
        file_size_bytes,
        mime_type,
    );

    println!("\n Note: This would create a real multipart upload session.");
    println!("   Commented out to avoid accidental API calls.\n");

    // Uncomment to actually create upload:
    // match client.uploads().create(builder).await {
    //     Ok(upload) => {
    //         println!(" Upload session created successfully!");
    //         println!("  Upload ID: {}", upload.id);
    //         println!("  Status: {}", upload.status);
    //         println!("  Expires At: {}", upload.expires_at);
    //     }
    //     Err(e) => {
    //         eprintln!(" Failed to create upload: {}", e);
    //     }
    // }

    // Simulate upload creation for demonstration
    let demo_upload = UploadInfo::new(
        "upload-demo123",
        filename,
        file_size_bytes,
        "fine-tune",
        "pending",
    );
    println!(" Demo Upload Created:");
    demo_upload.display();

    // Example 2: Upload file parts
    println!("\n");
    println!(" Example 2: Upload File Parts");
    println!("\n");

    let upload_id = "upload-demo123";
    let part_size_mb = 64; // Upload in 64 MB chunks
    let total_parts = (file_size_mb + part_size_mb - 1) / part_size_mb; // Ceiling division

    println!(
        "Uploading {} parts ({} MB each)...\n",
        total_parts, part_size_mb
    );

    for part_num in 1..=total_parts {
        let progress_percent = (part_num as f64 / total_parts as f64) * 100.0;

        println!(
            " Uploading part {}/{} ({:.1}% complete)",
            part_num, total_parts, progress_percent
        );

        // In a real implementation, you would:
        // 1. Read the file chunk from disk
        // 2. Upload it to the part URL provided by OpenAI
        // 3. Track the part ID for completion

        // Uncomment to actually upload parts:
        // let part_data = read_file_chunk(filename, part_num, part_size_mb)?;
        // match upload_part(upload_id, part_num, &part_data).await {
        //     Ok(part_id) => {
        //         println!("   Part {} uploaded (ID: {})", part_num, part_id);
        //     }
        //     Err(e) => {
        //         eprintln!("   Failed to upload part {}: {}", part_num, e);
        //         break;
        //     }
        // }
    }

    println!("\n All {} parts uploaded successfully", total_parts);

    // Example 3: Complete the upload
    println!("\n");
    println!(" Example 3: Complete Upload");
    println!("\n");

    println!("Completing upload: {}\n", upload_id);

    // Uncomment to actually complete upload:
    // match complete_upload(upload_id, part_ids).await {
    //     Ok(file) => {
    //         println!(" Upload completed successfully!");
    //         println!("  File ID: {}", file.id);
    //         println!("  Filename: {}", file.filename);
    //         println!("  Status: ready");
    //         println!("  Purpose: {}", file.purpose);
    //     }
    //     Err(e) => {
    //         eprintln!(" Failed to complete upload: {}", e);
    //     }
    // }

    println!(" Demo: Would finalize the upload and create a file object");
    println!("  File ID: file-abc123");
    println!("  Filename: {}", filename);
    println!("  Status: ready");

    // Example 4: Upload smaller file (alternative approach)
    println!("\n");
    println!(" Example 4: Upload Smaller File");
    println!("\n");

    let small_filename = "training_data.jsonl";
    let small_size_mb = 10;
    let small_size_bytes = small_size_mb * 1024 * 1024;

    println!("Creating upload for smaller file...");
    println!("  Filename: {}", small_filename);
    println!("  Size: {} MB", small_size_mb);
    println!("  Purpose: assistants");

    let small_builder = client.uploads().builder(
        small_filename,
        UploadPurpose::Assistants,
        small_size_bytes,
        "application/jsonl",
    );

    println!("\n Note: For files < 512 MB, consider using the regular Files API");
    println!("   The Uploads API is optimized for large files.");

    // Example 5: Error handling and retry
    println!("\n");
    println!(" Example 5: Error Handling & Retry");
    println!("\n");

    println!("Demonstrating retry logic for failed part uploads...\n");

    let max_retries = 3;
    let failed_part = 5;

    for retry in 1..=max_retries {
        println!(" Attempt {} to upload part {}", retry, failed_part);

        // Simulate upload attempt
        // In a real implementation:
        // match upload_part(upload_id, failed_part, &part_data).await {
        //     Ok(part_id) => {
        //         println!("   Upload succeeded");
        //         break;
        //     }
        //     Err(e) => {
        //         if retry < max_retries {
        //             println!("    Upload failed, retrying... ({})", e);
        //             tokio::time::sleep(Duration::from_secs(2_u64.pow(retry))).await;
        //         } else {
        //             eprintln!("   Upload failed after {} attempts: {}", max_retries, e);
        //         }
        //     }
        // }
    }

    println!("\n Tip: Implement exponential backoff for retry logic");

    // Example 6: Upload progress tracking
    println!("\n");
    println!(" Example 6: Progress Tracking");
    println!("\n");

    struct UploadProgress {
        total_bytes: i32,
        uploaded_bytes: i32,
        total_parts: i32,
        uploaded_parts: i32,
    }

    impl UploadProgress {
        fn percentage(&self) -> f64 {
            (self.uploaded_bytes as f64 / self.total_bytes as f64) * 100.0
        }

        fn eta_seconds(&self, bytes_per_second: f64) -> i32 {
            let remaining_bytes = self.total_bytes - self.uploaded_bytes;
            (remaining_bytes as f64 / bytes_per_second) as i32
        }

        fn display(&self, bytes_per_second: f64) {
            let progress_bar_width = 40;
            let filled = ((self.percentage() / 100.0) * progress_bar_width as f64) as usize;
            let empty = progress_bar_width - filled;

            print!("  [");
            print!("{}", "".repeat(filled));
            print!("{}", "".repeat(empty));
            print!("] ");

            println!(
                "{:.1}% ({}/{} parts, {} MB/s, ETA: {}s)",
                self.percentage(),
                self.uploaded_parts,
                self.total_parts,
                bytes_per_second / (1024.0 * 1024.0),
                self.eta_seconds(bytes_per_second)
            );
        }
    }

    let progress = UploadProgress {
        total_bytes: file_size_bytes,
        uploaded_bytes: (file_size_bytes as f64 * 0.65) as i32,
        total_parts,
        uploaded_parts: (total_parts as f64 * 0.65) as i32,
    };

    println!("Current upload progress:");
    progress.display(10.0 * 1024.0 * 1024.0); // 10 MB/s

    // Summary
    println!("\n");
    println!(" Summary");
    println!("\n");

    println!(" Uploads API examples completed!");
    println!("\n Key Takeaways:");
    println!("  • Uploads API is designed for large files (>512 MB)");
    println!("  • Files are uploaded in parts for reliability");
    println!("  • Each part can be retried independently");
    println!("  • Progress can be tracked during upload");
    println!("  • Upload must be completed after all parts are uploaded");

    println!("\n Best Practices:");
    println!("  1. Use appropriate part sizes (typically 64 MB)");
    println!("  2. Implement retry logic with exponential backoff");
    println!("  3. Track progress and provide user feedback");
    println!("  4. Handle upload cancellation gracefully");
    println!("  5. Verify file integrity after upload");

    println!("\n When to Use:");
    println!("  • Large training datasets for fine-tuning");
    println!("  • Big files for assistants (>512 MB)");
    println!("  • Batch processing input files");
    println!("  • Any file where reliability is critical");

    println!("\n Example completed successfully!");

    Ok(())
}

pub fn models(&self) -> ModelsClient<'_, T>

Get models client.

Examples found in repository

examples/models.rs (line 76)

async fn fetch_models_from_api(client: &Client) -> Result<()> {
    // Example of using the ergonomic API to list models
    let response = client.models().list().await?;

    println!("Fetched {} models from API:", response.data.len());
    for model in response.data.iter().take(10) {
        println!("  - {} (owned by: {})", model.id, model.owned_by);
    }
    println!();

    // Example of getting a specific model
    if !response.data.is_empty() {
        let model_id = &response.data[0].id;
        let model = client.models().get(model_id).await?;
        println!("Model details for {}:", model.id);
        println!("  Owned by: {}", model.owned_by);
        println!("  Created: {}", model.created);
        println!();
    }

    Ok(())
}

pub fn completions(&self) -> CompletionsClient<'_, T>

Get completions client.

Examples found in repository

examples/completions.rs (line 58)

async fn basic_completion(client: &Client) -> Result<()> {
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("Write a tagline for an ice cream shop")
        .max_tokens(60);

    let response = client.completions().create(builder).await?;

    println!("Prompt: Write a tagline for an ice cream shop");
    if let Some(choice) = response.choices.first() {
        println!("Completion: {}", choice.text);
        println!("Finish reason: {:?}", choice.finish_reason);
    }

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

    Ok(())
}

async fn completion_with_parameters(client: &Client) -> Result<()> {
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("Explain quantum computing in simple terms:")
        .max_tokens(100)
        .temperature(0.7)
        .top_p(0.9)
        .frequency_penalty(0.5)
        .presence_penalty(0.0);

    let response = client.completions().create(builder).await?;

    println!("Parameters:");
    println!("  Temperature: 0.7");
    println!("  Top P: 0.9");
    println!("  Frequency Penalty: 0.5");
    println!("  Presence Penalty: 0.0");
    println!();

    if let Some(choice) = response.choices.first() {
        println!("Completion: {}", choice.text);
    }

    Ok(())
}

async fn multiple_completions(client: &Client) -> Result<()> {
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("Brainstorm three names for a pet cat:")
        .max_tokens(50)
        .n(3) // Generate 3 different completions
        .temperature(0.9); // Higher temperature for more variety

    let response = client.completions().create(builder).await?;

    println!("Generating {} completions:", response.choices.len());
    for (i, choice) in response.choices.iter().enumerate() {
        println!("  {}. {}", i + 1, choice.text.trim());
    }

    Ok(())
}

async fn completion_with_stop(client: &Client) -> Result<()> {
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("List three programming languages:\n1.")
        .max_tokens(100)
        .temperature(0.0)
        .add_stop("\n4.") // Stop at the fourth item
        .add_stop("\n\n"); // Also stop at double newline

    let response = client.completions().create(builder).await?;

    println!("Prompt: List three programming languages:");
    if let Some(choice) = response.choices.first() {
        println!("Completion:\n1.{}", choice.text);
        println!("Stopped because: {:?}", choice.finish_reason);
    }

    Ok(())
}

async fn completion_with_suffix(client: &Client) -> Result<()> {
    // Insert mode: provide text before and after the insertion point
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("def hello_world():\n    print(\"Hello, ")
        .suffix("\")\n    return True")
        .max_tokens(10)
        .temperature(0.0);

    let response = client.completions().create(builder).await?;

    println!("Insert mode example:");
    println!("Before: def hello_world():\\n    print(\"Hello, ");
    if let Some(choice) = response.choices.first() {
        println!("Inserted: {}", choice.text);
    }
    println!("After: \")\\n    return True");

    Ok(())
}

#[allow(dead_code)]
async fn completion_with_echo(client: &Client) -> Result<()> {
    let builder = client
        .completions()
        .builder("gpt-3.5-turbo-instruct")
        .prompt("The capital of France is")
        .max_tokens(10)
        .echo(true) // Echo back the prompt
        .temperature(0.0);

    let response = client.completions().create(builder).await?;

    println!("Echo enabled:");
    if let Some(choice) = response.choices.first() {
        println!("Full text (prompt + completion): {}", choice.text);
    }

    Ok(())
}

pub fn usage(&self) -> UsageClient<'_, T>

Get usage client.

Examples found in repository

examples/usage.rs (line 75)

async fn basic_usage_query(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time));

    let usage = client.usage().completions(builder).await?;

    println!("Completions usage:");
    println!("  Data points: {}", usage.data.len());

    if usage.has_more {
        println!("  Has more: yes");
    }

    Ok(())
}

async fn usage_with_aggregation(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .bucket_width(BucketWidth::Day)
        .limit(10);

    let usage = client.usage().completions(builder).await?;

    println!("Daily aggregated completions usage:");
    println!("  Bucket width: 1 day");
    println!("  Data points: {}", usage.data.len());

    Ok(())
}

async fn usage_by_model(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .model("gpt-4")
        .limit(100);

    let usage = client.usage().completions(builder).await?;

    println!("Completions usage for gpt-4:");
    println!("  Data points: {}", usage.data.len());

    Ok(())
}

async fn usage_grouped_by_project(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .group_by(GroupBy::ProjectId)
        .group_by(GroupBy::Model)
        .limit(50);

    let usage = client.usage().completions(builder).await?;

    println!("Completions usage grouped by project and model:");
    println!("  Data points: {}", usage.data.len());

    Ok(())
}

async fn cost_data(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .bucket_width(BucketWidth::Day)
        .limit(10);

    let costs = client.usage().costs(builder).await?;

    println!("Cost data:");
    println!("  Data points: {}", costs.data.len());

    Ok(())
}

async fn audio_usage(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time)).limit(10);

    // Audio speeches (text-to-speech)
    let speeches = client.usage().audio_speeches(builder.clone()).await?;
    println!("Audio speeches usage: {} data points", speeches.data.len());

    // Audio transcriptions
    let transcriptions = client.usage().audio_transcriptions(builder).await?;
    println!(
        "Audio transcriptions usage: {} data points",
        transcriptions.data.len()
    );

    Ok(())
}

async fn image_usage(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .bucket_width(BucketWidth::Day)
        .limit(10);

    let usage = client.usage().images(builder).await?;

    println!("Image generation usage:");
    println!("  Data points: {}", usage.data.len());

    Ok(())
}

async fn embeddings_usage(client: &Client, start_time: i32, end_time: i32) -> Result<()> {
    let builder = UsageBuilder::new(start_time, Some(end_time))
        .model("text-embedding-3-small")
        .limit(100);

    let usage = client.usage().embeddings(builder).await?;

    println!("Embeddings usage for text-embedding-3-small:");
    println!("  Data points: {}", usage.data.len());

    Ok(())
}

Trait Implementations

impl<T: Clone> Clone for Client<T>

fn clone(&self) -> Client<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Client<T>

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

Formats the value using the given formatter.