Struct ClientBuilder 

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

Builder for creating a Client with interceptors.

The builder pattern allows you to configure interceptors before the client is created. Once built, the interceptors are immutable, eliminating the need for runtime locking.

Example

let client = Client::from_env()?
    .with_interceptor(Box::new(my_interceptor))
    .build();

Implementations

impl ClientBuilder

pub fn new(config: Config) -> Result<Self>

Create a new client builder with the given configuration.

pub fn from_env() -> Result<Self>

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

impl<T> ClientBuilder<T>

pub fn with_interceptor<U>( self, interceptor: Box<dyn Interceptor<U>>, ) -> ClientBuilder<U>

Add an interceptor to the builder.

Creates a new builder with the interceptor’s state type. The interceptor provides hooks into the request/response lifecycle for observability, logging, and custom processing.

Note: This method transforms the builder’s type, so it can only be called once. For multiple interceptors with the same state type, use a composite interceptor or call this method multiple times (each will replace the previous chain).

Examples

Simple interceptor (no state):

use openai_ergonomic::{Client, Interceptor, BeforeRequestContext};

struct LoggingInterceptor;

#[async_trait::async_trait]
impl Interceptor for LoggingInterceptor {
    async fn before_request(&self, ctx: &mut BeforeRequestContext<'_>) -> Result<()> {
        println!("Calling {}", ctx.operation);
        Ok(())
    }
}

let client = Client::from_env()?
    .with_interceptor(Box::new(LoggingInterceptor))
    .build();

Interceptor with custom state:

use openai_ergonomic::{Client, LangfuseInterceptor, LangfuseState};

let interceptor = LangfuseInterceptor::new(tracer, config);
let client: Client<LangfuseState<_>> = Client::from_env()?
    .with_interceptor(Box::new(interceptor))
    .build();

Examples found in repository

examples/langfuse_simple.rs (line 54)

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_streaming.rs (line 59)

async fn main() -> std::result::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 streaming 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!("📊 Streaming traces will be sent to Langfuse for monitoring\n");

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

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

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

    println!("\n✅ Done! Check your Langfuse dashboard to see the streaming traces.");
    println!("   - Look for traces with operation names 'chat' or 'responses'");
    println!("   - Each trace includes:");
    println!("     • before_request: Initial request details");
    println!("     • on_stream_chunk: Each chunk as it arrives (real-time)");
    println!("     • on_stream_end: Final token usage and duration");

    // Give spawned interceptor tasks time to complete
    tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;

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

    Ok(())
}

examples/langfuse.rs (line 59)

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 add_interceptor(self, interceptor: Box<dyn Interceptor<T>>) -> Self

Add an interceptor that uses the same state type.

This allows chaining multiple interceptors with the same state type without type transformation.

Example

let client = Client::from_env()?
    .add_interceptor(Box::new(logger))
    .add_interceptor(Box::new(metrics))
    .build();

pub fn build(self) -> Client<T>

Build the client with the configured interceptors.

After building, the interceptors are immutable, eliminating runtime locking overhead.

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/error_handling.rs (line 59)

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

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

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

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

Additional examples can be found in:

• examples/tool_calling.rs
• 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/http_middleware_retry.rs
• examples/langfuse.rs
• examples/batch_processing.rs
• examples/threads.rs
• examples/fine_tuning.rs
• examples/caching_strategies.rs
• examples/uploads.rs
• examples/token_counting.rs
• examples/quickstart.rs