images_comprehensive/

images_comprehensive.rs

//! Comprehensive images example.
//!
//! This example demonstrates all image-related operations including:
//! - Image generation with different models (DALL-E 2, DALL-E 3, GPT-Image-1)
//! - Different sizes, qualities, and formats
//! - Image editing with masks and backgrounds
//! - Creating variations of existing images
//! - Proper file handling for inputs and outputs
//! - Streaming image generation (for supported models)
//! - Error handling patterns
//!
//! Run with: `cargo run --example images_comprehensive`
//!
//! Note: This example demonstrates the intended API design. The actual images API
//! implementation is still in development. Many of these features will be available
//! once the builders and response types are implemented.

#![allow(clippy::uninlined_format_args)]
#![allow(clippy::no_effect_underscore_binding)]
#![allow(clippy::cast_sign_loss)]
#![allow(clippy::unused_async)]

use openai_ergonomic::Client;
use std::fs;
use std::io::{self, Write};
use std::path::PathBuf;

/// Manages image outputs and file operations.
#[derive(Debug)]
struct ImageManager {
    output_dir: PathBuf,
    generated_images: Vec<PathBuf>,
}

impl ImageManager {
    /// Create a new image manager with an output directory.
    fn new(output_dir: impl Into<PathBuf>) -> Result<Self, Box<dyn std::error::Error>> {
        let output_dir = output_dir.into();

        // Create output directory if it doesn't exist
        if !output_dir.exists() {
            fs::create_dir_all(&output_dir)?;
            println!(" Created output directory: {}", output_dir.display());
        }

        Ok(Self {
            output_dir,
            generated_images: Vec::new(),
        })
    }

    /// Save an image to the output directory.
    fn save_image(
        &mut self,
        image_data: &[u8],
        filename: &str,
    ) -> Result<PathBuf, Box<dyn std::error::Error>> {
        let image_path = self.output_dir.join(filename);
        fs::write(&image_path, image_data)?;
        self.generated_images.push(image_path.clone());
        println!(" Saved image: {}", image_path.display());
        Ok(image_path)
    }

    /// Get the path to a generated image by index.
    #[allow(dead_code)]
    fn get_image_path(&self, index: usize) -> Option<&PathBuf> {
        self.generated_images.get(index)
    }

    /// List all generated images.
    fn list_images(&self) {
        println!("\n Generated Images:");
        for (i, path) in self.generated_images.iter().enumerate() {
            println!("  {}. {}", i + 1, path.display());
        }
    }

    /// Clean up generated images.
    fn cleanup(&self) -> Result<(), Box<dyn std::error::Error>> {
        println!("\n Cleaning up generated images...");
        for path in &self.generated_images {
            if path.exists() {
                fs::remove_file(path)?;
                println!("  Removed: {}", path.display());
            }
        }
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("OpenAI Ergonomic - Comprehensive Images Example");
    println!("==============================================");
    println!();

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

    // Initialize image manager
    let mut image_manager = ImageManager::new("./generated_images")?;

    // Demonstrate various image operations
    demonstrate_basic_generation(&client, &mut image_manager).await?;
    demonstrate_advanced_generation(&client, &mut image_manager).await?;
    demonstrate_image_editing(&client, &mut image_manager).await?;
    demonstrate_image_variations(&client, &mut image_manager).await?;
    demonstrate_streaming_generation(&client, &mut image_manager).await?;
    demonstrate_error_handling(&client).await?;

    // Summary and cleanup
    image_manager.list_images();

    println!("\n Images comprehensive example completed!");
    println!("This example demonstrated:");
    println!("  • Image generation with multiple models");
    println!("  • Different sizes, qualities, and formats");
    println!("  • Image editing with masks and backgrounds");
    println!("  • Creating variations of existing images");
    println!("  • File handling for inputs and outputs");
    println!("  • Streaming image generation");
    println!("  • Comprehensive error handling");

    // Ask user if they want to keep the generated images
    print!("\nKeep generated images? (y/N): ");
    io::stdout().flush()?;
    let mut input = String::new();
    io::stdin().read_line(&mut input)?;

    if !input.trim().to_lowercase().starts_with('y') {
        image_manager.cleanup()?;
    }

    Ok(())
}

/// Demonstrate basic image generation with different models.
async fn demonstrate_basic_generation(
    _client: &Client,
    image_manager: &mut ImageManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!(" Example 1: Basic Image Generation");
    println!("----------------------------------");

    // DALL-E 3 generation (high quality, single image)
    println!("\n1.1: DALL-E 3 Generation");
    let _dalle3_prompt = "A serene mountain landscape at sunset with a crystal clear lake reflecting the orange and pink sky";

    // Note: This demonstrates the intended API once images builders are implemented
    println!(" DALL-E 3 generation would be implemented like this:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .generate()");
    println!("    .model(\"dall-e-3\")");
    println!("    .prompt(\"A serene mountain landscape at sunset...\")");
    println!("    .size(\"1024x1024\")");
    println!("    .quality(\"hd\")");
    println!("    .response_format(\"b64_json\")");
    println!("    .await?;");
    println!("```");

    // Simulate saving the image
    let simulated_image_data = b"simulated_dalle3_image_data";
    image_manager.save_image(simulated_image_data, "dalle3_landscape.png")?;

    // DALL-E 2 generation (multiple images, standard quality)
    println!("\n1.2: DALL-E 2 Generation (Multiple Images)");
    let _dalle2_prompt = "A cute robot reading a book in a cozy library";

    println!(" DALL-E 2 multiple image generation would be:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .generate()");
    println!("    .model(\"dall-e-2\")");
    println!("    .prompt(\"A cute robot reading a book...\")");
    println!("    .n(3)  // Generate 3 images");
    println!("    .size(\"512x512\")");
    println!("    .await?;");
    println!("```");

    // Simulate multiple images
    for i in 1..=3 {
        let simulated_data = format!("simulated_dalle2_image_{}", i).into_bytes();
        image_manager.save_image(&simulated_data, &format!("dalle2_robot_{}.png", i))?;
    }

    // GPT-Image-1 generation (newest model with streaming support)
    println!("\n1.3: GPT-Image-1 Generation");
    let _gpt_image_prompt = "A futuristic cityscape with flying cars and neon lights";

    println!(" GPT-Image-1 generation would be:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .generate()");
    println!("    .model(\"gpt-image-1\")");
    println!("    .prompt(\"A futuristic cityscape with flying cars...\")");
    println!("    .size(\"1536x1024\")  // Landscape");
    println!("    .quality(\"high\")");
    println!("    .output_format(\"webp\")");
    println!("    .output_compression(85)");
    println!("    .await?;");
    println!("```");

    let simulated_gpt_data = b"simulated_gpt_image_data";
    image_manager.save_image(simulated_gpt_data, "gpt_image_cityscape.webp")?;

    println!("\n Basic generation examples completed");
    Ok(())
}

/// Demonstrate advanced generation options.
async fn demonstrate_advanced_generation(
    _client: &Client,
    image_manager: &mut ImageManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("\n Example 2: Advanced Generation Options");
    println!("---------------------------------------");

    // Different sizes and aspect ratios
    println!("\n2.1: Different Sizes and Aspect Ratios");

    let sizes_demo = vec![
        ("1024x1024", "Square format - perfect for social media"),
        ("1792x1024", "Landscape format - great for wallpapers"),
        ("1024x1792", "Portrait format - ideal for phone backgrounds"),
    ];

    for (size, description) in sizes_demo {
        println!("  • {} - {}", size, description);
        println!("     Implementation: .size(\"{}\")", size);

        let simulated_data = format!("simulated_{}_{}", size.replace('x', "_"), "art").into_bytes();
        let filename = format!("size_demo_{}.png", size.replace('x', "_"));
        image_manager.save_image(&simulated_data, &filename)?;
    }

    // Quality options
    println!("\n2.2: Quality Options");
    let quality_demo = vec![
        ("low", "Faster generation, lower detail"),
        ("medium", "Balanced speed and quality"),
        ("high", "Slower generation, maximum detail"),
        ("hd", "DALL-E 3 high definition mode"),
    ];

    for (quality, description) in quality_demo {
        println!("  • {} - {}", quality, description);
        println!("     Implementation: .quality(\"{}\")", quality);
    }

    // Output formats (GPT-Image-1)
    println!("\n2.3: Output Formats (GPT-Image-1)");
    let format_demo = vec![
        ("png", "Best quality, larger file size"),
        ("jpeg", "Good quality, medium file size"),
        ("webp", "Modern format, smallest file size"),
    ];

    for (format, description) in format_demo {
        println!("  • {} - {}", format, description);
        println!("     Implementation: .output_format(\"{}\")", format);

        let simulated_data = format!("simulated_format_demo_{}", format).into_bytes();
        let filename = format!("format_demo.{}", format);
        image_manager.save_image(&simulated_data, &filename)?;
    }

    // Content moderation levels
    println!("\n2.4: Content Moderation (GPT-Image-1)");
    println!("  • auto - Default moderation level");
    println!("  • low - Less restrictive filtering");
    println!("     Implementation: .content_filter(\"low\")");

    println!("\n Advanced generation options demonstrated");
    Ok(())
}

/// Demonstrate image editing capabilities.
async fn demonstrate_image_editing(
    _client: &Client,
    image_manager: &mut ImageManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("\n  Example 3: Image Editing");
    println!("---------------------------");

    // Create a sample image file for editing demonstrations
    println!("\n3.1: Creating Sample Image for Editing");
    let sample_image_data = b"simulated_original_image_for_editing";
    let original_path = image_manager.save_image(sample_image_data, "original_for_editing.png")?;

    // Basic image editing
    println!("\n3.2: Basic Image Editing");
    println!("Original image: {}", original_path.display());
    println!("Edit prompt: Add a rainbow in the sky");

    println!(" Image editing would be implemented like this:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .edit()");
    println!("    .image(PathBuf::from(\"{}\"))", original_path.display());
    println!("    .prompt(\"Add a rainbow in the sky\")");
    println!("    .model(\"dall-e-2\")  // Only DALL-E 2 supports editing");
    println!("    .size(\"1024x1024\")");
    println!("    .await?;");
    println!("```");

    let edited_data = b"simulated_edited_image_with_rainbow";
    image_manager.save_image(edited_data, "edited_with_rainbow.png")?;

    // Editing with mask
    println!("\n3.3: Editing with Mask");
    let mask_data = b"simulated_mask_data";
    let mask_path = image_manager.save_image(mask_data, "edit_mask.png")?;

    println!("Original: {}", original_path.display());
    println!("Mask: {}", mask_path.display());
    println!("Edit prompt: Replace the masked area with a beautiful garden");

    println!(" Masked editing would be:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .edit()");
    println!("    .image(PathBuf::from(\"{}\"))", original_path.display());
    println!("    .mask(PathBuf::from(\"{}\"))", mask_path.display());
    println!("    .prompt(\"Replace the masked area with a beautiful garden\")");
    println!("    .n(2)  // Generate 2 variations");
    println!("    .await?;");
    println!("```");

    for i in 1..=2 {
        let masked_edit_data = format!("simulated_masked_edit_{}", i).into_bytes();
        image_manager.save_image(&masked_edit_data, &format!("masked_edit_{}.png", i))?;
    }

    // Background replacement (GPT-Image-1)
    println!("\n3.4: Background Replacement (GPT-Image-1)");
    println!(" Background replacement would be:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .edit()");
    println!("    .image(PathBuf::from(\"{}\"))", original_path.display());
    println!("    .background(\"transparent\")");
    println!("    .prompt(\"Professional headshot with clean background\")");
    println!("    .model(\"gpt-image-1\")");
    println!("    .await?;");
    println!("```");

    let background_edit_data = b"simulated_background_replaced";
    image_manager.save_image(background_edit_data, "background_replaced.png")?;

    println!("\n Image editing examples completed");
    Ok(())
}

/// Demonstrate creating variations of existing images.
async fn demonstrate_image_variations(
    _client: &Client,
    image_manager: &mut ImageManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("\n Example 4: Image Variations");
    println!("-----------------------------");

    // Use an existing image for variations
    let base_image_data = b"simulated_base_image_for_variations";
    let base_path = image_manager.save_image(base_image_data, "base_for_variations.png")?;

    println!("\n4.1: Creating Variations");
    println!("Base image: {}", base_path.display());

    println!(" Image variations would be implemented like this:");
    println!("```rust");
    println!("let response = client.images()");
    println!("    .variations()");
    println!("    .image(PathBuf::from(\"{}\"))", base_path.display());
    println!("    .model(\"dall-e-2\")  // Only DALL-E 2 supports variations");
    println!("    .n(4)  // Generate 4 variations");
    println!("    .size(\"512x512\")");
    println!("    .response_format(\"url\")");
    println!("    .await?;");
    println!("```");

    // Simulate generating variations
    for i in 1..=4 {
        let variation_data = format!("simulated_variation_{}", i).into_bytes();
        image_manager.save_image(&variation_data, &format!("variation_{}.png", i))?;
        println!("   Generated variation {}", i);
    }

    println!("\n4.2: Variations with Different Sizes");
    let sizes = ["256x256", "512x512", "1024x1024"];

    for size in sizes {
        println!("Creating variation with size: {}", size);
        println!(" Implementation: .size(\"{}\")", size);

        let size_variation_data =
            format!("simulated_variation_{}", size.replace('x', "_")).into_bytes();
        let filename = format!("variation_{}.png", size.replace('x', "_"));
        image_manager.save_image(&size_variation_data, &filename)?;
    }

    println!("\n Image variations examples completed");
    Ok(())
}

/// Demonstrate streaming image generation.
async fn demonstrate_streaming_generation(
    _client: &Client,
    image_manager: &mut ImageManager,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("\n Example 5: Streaming Image Generation");
    println!("--------------------------------------");

    println!("\n5.1: Streaming with Partial Images (GPT-Image-1)");
    println!("Prompt: A detailed architectural drawing of a modern house");

    println!(" Streaming image generation would be:");
    println!("```rust");
    println!("let mut stream = client.images()");
    println!("    .generate()");
    println!("    .model(\"gpt-image-1\")");
    println!("    .prompt(\"A detailed architectural drawing of a modern house\")");
    println!("    .stream(true)");
    println!("    .partial_images(2)  // Receive 2 partial images during generation");
    println!("    .stream()");
    println!("    .await?;");
    println!();
    println!("while let Some(chunk) = stream.next().await {{");
    println!("    match chunk? {{");
    println!("        ImageChunk::Partial {{ data, progress }} => {{");
    println!("            println!(\"Partial image received: {{}}% complete\", progress);");
    println!("            // Save partial image if desired");
    println!("        }}");
    println!("        ImageChunk::Final {{ data }} => {{");
    println!("            println!(\"Final image received!\");");
    println!("            // Save final image");
    println!("            break;");
    println!("        }}");
    println!("    }}");
    println!("}}");
    println!("```");

    // Simulate streaming with partial images
    println!("\n Simulating streaming progress:");
    let progress_steps = [25, 50, 75, 100];

    for progress in &progress_steps {
        tokio::time::sleep(tokio::time::Duration::from_millis(800)).await;

        if *progress < 100 {
            println!(" Partial image received: {}% complete", progress);
            let partial_data = format!("simulated_partial_image_{}", progress).into_bytes();
            let filename = format!("streaming_partial_{}.png", progress);
            image_manager.save_image(&partial_data, &filename)?;
        } else {
            println!(" Final image received: 100% complete");
            let final_data = b"simulated_final_streaming_image";
            image_manager.save_image(final_data, "streaming_final.png")?;
        }

        // Show progress bar
        let filled = (*progress as usize) / 4;
        let empty = 25 - filled;
        println!(
            "   [{}{}] {}%",
            "".repeat(filled),
            "".repeat(empty),
            progress
        );
    }

    println!("\n5.2: Streaming Benefits");
    println!("• Real-time feedback during image generation");
    println!("• Ability to cancel long-running generations");
    println!("• Progressive image refinement visibility");
    println!("• Better user experience for complex prompts");

    println!("\n Streaming image generation demonstrated");
    Ok(())
}

/// Demonstrate error handling patterns for images API.
async fn demonstrate_error_handling(_client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    println!("\n  Example 6: Error Handling Patterns");
    println!("------------------------------------");

    println!("\n6.1: Common Error Scenarios");

    // Test 1: Invalid model
    println!("\nTest 1: Invalid model name");
    println!(" Error handling would look like:");
    println!("```rust");
    println!("match client.images().generate()");
    println!("    .model(\"invalid-model\")");
    println!("    .prompt(\"Test image\")");
    println!("    .await");
    println!("{{");
    println!("    Ok(_) => println!(\"Success\"),");
    println!("    Err(Error::Api {{ status, message, .. }}) => {{");
    println!("        match status {{");
    println!("            400 => println!(\"Bad request: {{}}\", message),");
    println!("            404 => println!(\"Model not found: {{}}\", message),");
    println!("            _ => println!(\"API error {{}}: {{}}\", status, message),");
    println!("        }}");
    println!("    }}");
    println!("    Err(e) => println!(\"Other error: {{}}\", e),");
    println!("}}");
    println!("```");

    // Test 2: Invalid image file
    println!("\nTest 2: Invalid image file for editing/variations");
    println!(" File validation would be:");
    println!("```rust");
    println!("let image_path = PathBuf::from(\"nonexistent.png\");");
    println!("match client.images().edit()");
    println!("    .image(image_path)");
    println!("    .prompt(\"Edit this\")");
    println!("    .await");
    println!("{{");
    println!("    Ok(_) => println!(\"Success\"),");
    println!("    Err(Error::InvalidRequest(msg)) => {{");
    println!("        println!(\"Invalid request: {{}}\", msg);");
    println!("    }}");
    println!("    Err(Error::Io(e)) => {{");
    println!("        println!(\"File error: {{}}\", e);");
    println!("    }}");
    println!("    Err(e) => println!(\"Other error: {{}}\", e),");
    println!("}}");
    println!("```");

    // Test 3: Rate limiting
    println!("\nTest 3: Rate limiting");
    println!(" Rate limit handling would be:");
    println!("```rust");
    println!("match client.images().generate()");
    println!("    .prompt(\"High-resolution detailed artwork\")");
    println!("    .await");
    println!("{{");
    println!("    Err(Error::RateLimit {{ retry_after, .. }}) => {{");
    println!("        println!(\"Rate limited. Retry after {{}} seconds\", retry_after);");
    println!("        tokio::time::sleep(Duration::from_secs(retry_after)).await;");
    println!("        // Retry the request");
    println!("    }}");
    println!("    Ok(response) => println!(\"Image generated successfully\"),");
    println!("    Err(e) => println!(\"Error: {{}}\", e),");
    println!("}}");
    println!("```");

    // Test 4: Content policy violations
    println!("\nTest 4: Content policy violations");
    println!(" Content policy error handling:");
    println!("```rust");
    println!("match client.images().generate()");
    println!("    .prompt(\"inappropriate content\")");
    println!("    .await");
    println!("{{");
    println!("    Err(Error::Api {{ status: 400, message, .. }}) ");
    println!("        if message.contains(\"content_policy\") => {{");
    println!("        println!(\"Content policy violation: {{}}\", message);");
    println!(
        "        println!(\"Please revise your prompt to comply with OpenAI's usage policies\");"
    );
    println!("    }}");
    println!("    Ok(response) => println!(\"Image generated\"),");
    println!("    Err(e) => println!(\"Error: {{}}\", e),");
    println!("}}");
    println!("```");

    println!("\n6.2: Error Recovery Strategies");
    println!("• Automatic retry with exponential backoff for transient errors");
    println!("• Prompt modification suggestions for content policy violations");
    println!("• Fallback to different models when one is unavailable");
    println!("• Graceful degradation of quality/size when limits are exceeded");

    println!("\n6.3: Best Practices");
    println!("• Always validate input files before sending requests");
    println!("• Implement proper timeout handling for long-running generations");
    println!("• Cache successful responses to avoid redundant API calls");
    println!("• Monitor API usage to stay within rate limits");

    println!("\n Error handling patterns demonstrated");
    Ok(())
}