Struct ResponsesBuilder 

pub struct ResponsesBuilder { /* private fields */ }

Builder for Responses API requests.

The Responses API is the modern unified interface for OpenAI completions, supporting streaming, tools, and structured outputs.

Implementations

impl ResponsesBuilder

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

Create a new responses builder with the specified model.

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

Add a system message to the conversation.

Examples found in repository

examples/responses_comprehensive.rs (line 124)

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

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/quickstart.rs (lines 283-285)

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

Add a user message to the conversation.

Examples found in repository

examples/responses_comprehensive.rs (line 125)

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

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

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

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

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

Add an assistant message to the conversation.

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

Set the temperature for the completion.

Examples found in repository

examples/responses_comprehensive.rs (line 126)

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

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

examples/structured_outputs.rs (line 140)

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

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

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 max_tokens(self, max_tokens: i32) -> Self

Set the maximum number of tokens to generate.

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

Set the maximum completion tokens (for newer models).

Examples found in repository

examples/responses_comprehensive.rs (line 127)

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

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

examples/structured_outputs.rs (line 141)

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

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

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

Enable streaming for the response.

Examples found in repository

examples/responses_streaming.rs (line 235)

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/quickstart.rs (line 135)

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 tools(self, tools: Vec<ChatCompletionTool>) -> Self

Add tools that the model can use.

pub fn tool(self, tool: ChatCompletionTool) -> Self

Add a single tool.

Examples found in repository

examples/responses_streaming.rs (line 400)

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

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

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

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

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

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

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

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

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

    Ok(())
}

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

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

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

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

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

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

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

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

    Ok(())
}

examples/quickstart.rs (line 192)

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 tool_choice(self, tool_choice: ChatCompletionToolChoiceOption) -> Self

Set the tool choice option.

Examples found in repository

examples/responses_comprehensive.rs (line 208)

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

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

Set the response format.

pub fn json_mode(self) -> Self

Enable JSON mode.

Examples found in repository

examples/structured_outputs.rs (line 139)

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

examples/responses_comprehensive.rs (line 374)

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

pub fn json_schema(self, name: impl Into<String>, schema: Value) -> Self

Set a JSON schema for structured output.

Examples found in repository

examples/responses_comprehensive.rs (line 349)

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

examples/structured_outputs.rs (line 231)

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

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

Set the number of completions to generate.

Examples found in repository

examples/responses_comprehensive.rs (line 397)

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

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

Set stop sequences.

Examples found in repository

examples/responses_comprehensive.rs (line 401)

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

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

Set the presence penalty.

Examples found in repository

examples/responses_comprehensive.rs (line 400)

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

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

Set the frequency penalty.

Examples found in repository

examples/responses_comprehensive.rs (line 399)

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

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

Set the top-p value.

Examples found in repository

examples/responses_comprehensive.rs (line 398)

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

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

Set the user identifier.

Examples found in repository

examples/responses_comprehensive.rs (line 403)

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

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

Set the random seed for deterministic outputs.

Examples found in repository

examples/responses_comprehensive.rs (line 402)

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

pub fn reasoning_effort(self, effort: impl Into<String>) -> Self

Set the reasoning effort (for o3 models).

Examples found in repository

examples/responses_comprehensive.rs (line 418)

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

Trait Implementations

impl Builder<CreateChatCompletionRequest> for ResponsesBuilder

fn build(self) -> Result<CreateChatCompletionRequest>

Build the final request type.

impl Clone for ResponsesBuilder

fn clone(&self) -> ResponsesBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ResponsesBuilder

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

Formats the value using the given formatter.