Struct AiClient 

pub struct AiClient { /* private fields */ }

Unified AI client

Usage example:

use ai_lib::{AiClient, Provider, ChatCompletionRequest, Message, Role};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Switch model provider by changing Provider value
    let client = AiClient::new(Provider::Groq)?;
     
    let request = ChatCompletionRequest::new(
        "test-model".to_string(),
        vec![Message {
            role: Role::User,
            content: ai_lib::types::common::Content::Text("Hello".to_string()),
            function_call: None,
        }],
    );
     
    // Note: Set GROQ_API_KEY environment variable for actual API calls
    // Optional: Set AI_PROXY_URL environment variable to use proxy server
    // let response = client.chat_completion(request).await?;
     
    println!("Client created successfully with provider: {:?}", client.current_provider());
    println!("Request prepared for model: {}", request.model);
     
    Ok(())
}

Proxy Configuration

Configure proxy server by setting the AI_PROXY_URL environment variable:

export AI_PROXY_URL=http://proxy.example.com:8080

Supported proxy formats:

• HTTP proxy: http://proxy.example.com:8080
• HTTPS proxy: https://proxy.example.com:8080
• With authentication: http://user:pass@proxy.example.com:8080

Implementations

impl AiClient

pub fn new(provider: Provider) -> Result<Self, AiLibError>

Create a new AI client

Arguments

• provider - The AI model provider to use

Returns

• Result<Self, AiLibError> - Client instance on success, error on failure

Example

use ai_lib::{AiClient, Provider};

let client = AiClient::new(Provider::Groq)?;

Examples found in repository

examples/multimodal_example.rs (line 8)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Multimodal example: image + audio content in a message");

    let _client = AiClient::new(Provider::Groq)?;

    let request = ChatCompletionRequest::new(
        "multimodal-model".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::new_image(
                Some("https://example.com/dog.jpg".into()),
                Some("image/jpeg".into()),
                Some("dog.jpg".into()),
            ),
            function_call: None,
        }],
    );

    println!(
        "Prepared multimodal request; image URL: {}",
        request.messages[0].content.as_text()
    );

    // Note: this example demonstrates the type usage only and does not call the API.
    Ok(())
}

examples/list_models_smoke.rs (line 24)

async fn main() {
    let providers = vec![
        Provider::Groq,
        Provider::XaiGrok,
        Provider::Ollama,
        Provider::DeepSeek,
        Provider::Anthropic,
        Provider::AzureOpenAI,
        Provider::HuggingFace,
        Provider::TogetherAI,
        Provider::Qwen,
        Provider::OpenAI,
        Provider::Gemini,
        Provider::Mistral,
        Provider::Cohere,
        // Provider::Bedrock, // Removed: Bedrock deferred implementation/not in public API
    ];

    for p in providers {
        println!("--- Provider: {:?} ---", p);
        match AiClient::new(p) {
            Ok(client) => match client.list_models().await {
                Ok(models) => {
                    println!("Found {} models (showing up to 5):", models.len());
                    for m in models.into_iter().take(5) {
                        println!(" - {}", m);
                    }
                }
                Err(e) => println!("list_models error: {:?}", e),
            },
            Err(e) => println!("client init error: {:?}", e),
        }
    }
}

examples/cohere_stream.rs (line 8)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Ensure COHERE_API_KEY env var is set if making real requests
    let client = AiClient::new(Provider::Cohere)?;

    let request = ChatCompletionRequest::new(
        "command-xlarge-nightly".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Write a haiku about rust programming".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(60);

    // List models
    match client.list_models().await {
        Ok(models) => println!("Models: {:?}", models),
        Err(e) => eprintln!("Failed to list models: {}", e),
    }

    // Streaming
    let mut stream = client.chat_completion_stream(request).await?;
    while let Some(chunk) = stream.next().await {
        match chunk {
            Ok(c) => {
                for choice in c.choices {
                    if let Some(delta) = choice.delta.content {
                        print!("{}", delta);
                    }
                }
            }
            Err(e) => {
                eprintln!("Stream error: {}", e);
                break;
            }
        }
    }

    Ok(())
}

examples/basic_usage.rs (line 11)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Basic Usage Example");
    println!("================================");

    // Switch model provider by changing Provider value
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Get list of supported models
    let models = client.list_models().await?;
    println!("📋 Available models: {:?}", models);

    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please introduce yourself briefly.".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(100);

    println!("📤 Sending request to model: {}", request.model);

    // Send request
    let response = client.chat_completion(request).await?;

    println!("📥 Received response:");
    println!("   ID: {}", response.id);
    println!("   Model: {}", response.model);
    println!(
        "   Content: {}",
        response.choices[0].message.content.as_text()
    );
    println!("   Usage: {} tokens", response.usage.total_tokens);

    Ok(())
}

examples/config_driven_example.rs (line 21)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 Config-driven AI-lib Example");
    println!("================================");

    // Demonstrate the advantages of config-driven approach: easy provider switching
    let providers = vec![
        (Provider::Groq, "Groq"),
        (Provider::OpenAI, "OpenAI"),
        (Provider::DeepSeek, "DeepSeek"),
    ];

    for (provider, name) in providers {
        println!("\n📡 Testing Provider: {}", name);

        // Create client - just change the enum value
        let client = AiClient::new(provider)?;
        println!(
            "✅ Client created successfully: {:?}",
            client.current_provider()
        );

        // Get model list
        match client.list_models().await {
            Ok(models) => println!("📋 Available models: {:?}", models),
            Err(e) => println!("⚠️  Failed to get model list: {}", e),
        }

        // Create test request
        let request = ChatCompletionRequest::new(
            "test-model".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Hello from ai-lib!".to_string()),
                function_call: None,
            }],
        );

        println!("📤 Request prepared, model: {}", request.model);
        println!("   (Need to set corresponding API_KEY environment variable for actual calls)");
    }

    println!("\n🎯 Core advantages of config-driven approach:");
    println!("   • Zero-code switching: just change Provider enum value");
    println!("   • Unified interface: all providers use the same API");
    println!("   • Rapid expansion: add new compatible providers with just configuration");

    Ok(())
}

examples/debug_request.rs (line 33)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔍 Debug Request Format");
    println!("======================");

    // Create test request
    let request = ChatCompletionRequest::new(
        "gpt-3.5-turbo".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello!".to_string()),
            function_call: None,
        }],
    )
    .with_max_tokens(10);

    println!("📤 Original Request:");
    println!("   Model: {}", request.model);
    println!("   Message count: {}", request.messages.len());
    println!(
        "   Message[0]: {:?} - {}",
        request.messages[0].role,
        request.messages[0].content.as_text()
    );
    println!("   max_tokens: {:?}", request.max_tokens);

    // Test OpenAI
    println!("\n🤖 Testing OpenAI...");
    match AiClient::new(Provider::OpenAI) {
        Ok(client) => {
            match client.chat_completion(request.clone()).await {
                Ok(response) => {
                    println!("✅ Success!");
                    println!(
                        "   Response: {}",
                        response.choices[0].message.content.as_text()
                    );
                }
                Err(e) => {
                    println!("❌ Failed: {}", e);

                    // If it's a 400 error, it indicates request format issues
                    if e.to_string().contains("400") {
                        println!("   This usually indicates incorrect request format");
                        println!("   Let's check if the request contains necessary fields...");
                    }
                }
            }
        }
        Err(e) => println!("❌ Client creation failed: {}", e),
    }

    Ok(())
}

Additional examples can be found in:

• examples/test_without_proxy.rs
• examples/compare_requests.rs
• examples/network_diagnosis.rs
• examples/proxy_example.rs
• examples/openai_test.rs
• examples/test_all_providers.rs
• examples/check_config.rs
• examples/function_call_openai.rs
• examples/test_https_proxy.rs
• examples/test_anthropic.rs
• examples/architecture_progress.rs
• examples/test_streaming.rs
• examples/test_openai_specific.rs
• examples/quickstart.rs
• examples/test_gemini.rs
• examples/test_groq_generic.rs
• examples/test_streaming_clean.rs
• examples/test_proxy_working.rs
• examples/test_retry_mechanism.rs
• examples/test_streaming_improved.rs
• examples/batch_processing.rs
• examples/test_all_config_driven.rs
• examples/test_hybrid_architecture.rs

pub fn with_options( provider: Provider, opts: ConnectionOptions, ) -> Result<Self, AiLibError>

Create client with minimal explicit options (base_url/proxy/timeout). Not all providers support overrides; unsupported providers ignore unspecified fields gracefully.

Examples found in repository

examples/explicit_config.rs (line 16)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Explicit configuration example");
    let opts = ConnectionOptions {
        base_url: None,                                      // fallback to provider default
        proxy: Some("http://proxy.example.com:8080".into()), // or None to use AI_PROXY_URL
        api_key: None,                                       // rely on environment for now
        timeout: Some(std::time::Duration::from_secs(40)),
        disable_proxy: false,
    };

    let client = AiClient::with_options(Provider::Groq, opts)?;

    let req = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Ping from explicit config".into()),
            function_call: None,
        }],
    );

    // This may fail if GROQ_API_KEY not set; we only show structure.
    match client.chat_completion(req).await {
        Ok(resp) => println!("Response model: {}", resp.model),
        Err(e) => println!(
            "Request failed (expected in example without API key): {}",
            e
        ),
    }
    Ok(())
}

pub fn connection_options(&self) -> Option<&ConnectionOptions>

pub fn builder(provider: Provider) -> AiClientBuilder

Create a new AI client builder

The builder pattern allows more flexible client configuration:

• Automatic environment variable detection
• Support for custom base_url and proxy
• Support for custom timeout and connection pool configuration

Arguments

• provider - The AI model provider to use

Returns

• AiClientBuilder - Builder instance

Example

use ai_lib::{AiClient, Provider};

// Simplest usage - automatic environment variable detection
let client = AiClient::builder(Provider::Groq).build()?;

// Custom base_url and proxy
let client = AiClient::builder(Provider::Groq)
    .with_base_url("https://custom.groq.com")
    .with_proxy(Some("http://proxy.example.com:8080"))
    .build()?;

Examples found in repository

examples/builder_pattern.rs (line 56)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI Client Builder Pattern Example");
    println!("===================================");

    // Example 1: Simplest usage - automatic environment variable detection
    println!("\n📋 Example 1: Simplest usage");
    println!("   Automatically detect GROQ_BASE_URL and AI_PROXY_URL from environment variables");

    let client = AiClientBuilder::new(Provider::Groq).build()?;
    println!(
        "✅ Client created successfully, provider: {:?}",
        client.current_provider()
    );

    // Example 2: Custom base_url
    println!("\n📋 Example 2: Custom base_url");
    println!("   Use custom Groq server address");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .build()?;
    println!("✅ Client created successfully with custom base_url");

    // Example 3: Custom base_url and proxy
    println!("\n📋 Example 3: Custom base_url and proxy");
    println!("   Use custom server and proxy");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ Client created successfully with custom base_url and proxy");

    // Example 4: Full custom configuration
    println!("\n📋 Example 4: Full custom configuration");
    println!("   Custom timeout, connection pool and other advanced configurations");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .with_timeout(Duration::from_secs(60))
        .with_pool_config(32, Duration::from_secs(90))
        .build()?;
    println!("✅ Client created successfully with full custom configuration");

    // Example 5: Use convenient builder method
    println!("\n📋 Example 5: Use convenient builder method");
    println!("   Create builder through AiClient::builder()");

    let client = AiClient::builder(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ Client created successfully using convenient builder method");

    // Example 6: Environment variable priority demonstration
    println!("\n📋 Example 6: Environment variable priority demonstration");
    println!("   Set environment variables, then use builder");

    // Set environment variables
    std::env::set_var("GROQ_BASE_URL", "https://env.groq.com");
    std::env::set_var("AI_PROXY_URL", "http://env.proxy.com:8080");

    // Don't set any custom configuration, should use environment variables
    let client = AiClientBuilder::new(Provider::Groq).build()?;
    println!("✅ Client created successfully using environment variable configuration");

    // Explicit settings override environment variables
    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://explicit.groq.com")
        .with_proxy(Some("http://explicit.proxy.com:8080"))
        .build()?;
    println!(
        "✅ Client created successfully, explicit configuration overrides environment variables"
    );

    // Example 7: Different provider configurations
    println!("\n📋 Example 7: Different provider configurations");

    // Groq
    let groq_client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .build()?;
    println!("✅ Groq client created successfully");

    // DeepSeek
    let deepseek_client = AiClientBuilder::new(Provider::DeepSeek)
        .with_base_url("https://custom.deepseek.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ DeepSeek client created successfully");

    // Ollama (local deployment)
    let ollama_client = AiClientBuilder::new(Provider::Ollama)
        .with_base_url("http://localhost:11434")
        .build()?;
    println!("✅ Ollama client created successfully");

    // Example 8: Error handling
    println!("\n📋 Example 8: Error handling");
    println!("   Try to set custom configuration for unsupported provider");

    match AiClientBuilder::new(Provider::OpenAI)
        .with_base_url("https://custom.openai.com")
        .build()
    {
        Ok(_) => println!("❌ This should not succeed"),
        Err(e) => println!("✅ Correctly caught error: {}", e),
    }

    println!("\n🎉 All examples completed!");
    println!("\n💡 Advantages of builder pattern:");
    println!("   1. Automatic environment variable detection, reducing configuration code");
    println!("   2. Support for progressive custom configuration");
    println!("   3. Method chaining for cleaner code");
    println!("   4. Backward compatible, existing code requires no changes");
    println!("   5. Support for advanced configuration (timeout, connection pool, etc.)");

    Ok(())
}

pub fn new_with_metrics( provider: Provider, metrics: Arc<dyn Metrics>, ) -> Result<Self, AiLibError>

Create AiClient with injected metrics implementation

pub fn with_metrics(self, metrics: Arc<dyn Metrics>) -> Self

Set metrics implementation on client

pub async fn chat_completion( &self, request: ChatCompletionRequest, ) -> Result<ChatCompletionResponse, AiLibError>

Send chat completion request

Arguments

• request - Chat completion request

Returns

• Result<ChatCompletionResponse, AiLibError> - Response on success, error on failure

Examples found in repository

examples/explicit_config.rs (line 28)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Explicit configuration example");
    let opts = ConnectionOptions {
        base_url: None,                                      // fallback to provider default
        proxy: Some("http://proxy.example.com:8080".into()), // or None to use AI_PROXY_URL
        api_key: None,                                       // rely on environment for now
        timeout: Some(std::time::Duration::from_secs(40)),
        disable_proxy: false,
    };

    let client = AiClient::with_options(Provider::Groq, opts)?;

    let req = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Ping from explicit config".into()),
            function_call: None,
        }],
    );

    // This may fail if GROQ_API_KEY not set; we only show structure.
    match client.chat_completion(req).await {
        Ok(resp) => println!("Response model: {}", resp.model),
        Err(e) => println!(
            "Request failed (expected in example without API key): {}",
            e
        ),
    }
    Ok(())
}

examples/basic_usage.rs (line 36)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Basic Usage Example");
    println!("================================");

    // Switch model provider by changing Provider value
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Get list of supported models
    let models = client.list_models().await?;
    println!("📋 Available models: {:?}", models);

    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please introduce yourself briefly.".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(100);

    println!("📤 Sending request to model: {}", request.model);

    // Send request
    let response = client.chat_completion(request).await?;

    println!("📥 Received response:");
    println!("   ID: {}", response.id);
    println!("   Model: {}", response.model);
    println!(
        "   Content: {}",
        response.choices[0].message.content.as_text()
    );
    println!("   Usage: {} tokens", response.usage.total_tokens);

    Ok(())
}

examples/debug_request.rs (line 35)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔍 Debug Request Format");
    println!("======================");

    // Create test request
    let request = ChatCompletionRequest::new(
        "gpt-3.5-turbo".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello!".to_string()),
            function_call: None,
        }],
    )
    .with_max_tokens(10);

    println!("📤 Original Request:");
    println!("   Model: {}", request.model);
    println!("   Message count: {}", request.messages.len());
    println!(
        "   Message[0]: {:?} - {}",
        request.messages[0].role,
        request.messages[0].content.as_text()
    );
    println!("   max_tokens: {:?}", request.max_tokens);

    // Test OpenAI
    println!("\n🤖 Testing OpenAI...");
    match AiClient::new(Provider::OpenAI) {
        Ok(client) => {
            match client.chat_completion(request.clone()).await {
                Ok(response) => {
                    println!("✅ Success!");
                    println!(
                        "   Response: {}",
                        response.choices[0].message.content.as_text()
                    );
                }
                Err(e) => {
                    println!("❌ Failed: {}", e);

                    // If it's a 400 error, it indicates request format issues
                    if e.to_string().contains("400") {
                        println!("   This usually indicates incorrect request format");
                        println!("   Let's check if the request contains necessary fields...");
                    }
                }
            }
        }
        Err(e) => println!("❌ Client creation failed: {}", e),
    }

    Ok(())
}

examples/test_without_proxy.rs (line 30)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌐 测试不使用代理的连接");
    println!("======================");

    // 临时移除代理设置
    std::env::remove_var("AI_PROXY_URL");

    println!("ℹ️  已临时移除AI_PROXY_URL设置");

    // 测试DeepSeek（国内可直连）
    println!("\n🔍 测试DeepSeek (直连):");
    match AiClient::new(Provider::DeepSeek) {
        Ok(client) => {
            let request = ChatCompletionRequest::new(
                "deepseek-chat".to_string(),
                vec![Message {
                    role: Role::User,
                    content: Content::Text(
                        "Hello! Please respond with just 'Hi' to test.".to_string(),
                    ),
                    function_call: None,
                }],
            )
            .with_max_tokens(5);

            match client.chat_completion(request).await {
                Ok(response) => {
                    println!("✅ DeepSeek 直连成功!");
                    println!("   响应: {}", response.choices[0].message.content.as_text());
                    println!("   Token使用: {}", response.usage.total_tokens);
                }
                Err(e) => {
                    println!("❌ DeepSeek 请求失败: {}", e);
                    if e.to_string().contains("402") {
                        println!("   (这是余额不足错误，说明连接正常)");
                    }
                }
            }
        }
        Err(e) => println!("❌ DeepSeek 客户端创建失败: {}", e),
    }

    println!("\n💡 结论:");
    println!("   • DeepSeek可以直连，不需要代理");
    println!("   • OpenAI和Groq需要通过代理访问");
    println!("   • 代理可能会修改请求内容，导致格式错误");
    println!("   • 建议检查代理服务器的配置");

    Ok(())
}

examples/openai_test.rs (line 53)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🤖 OpenAI Provider Test");
    println!("======================");

    // Check API key
    match std::env::var("OPENAI_API_KEY") {
        Ok(_) => println!("✅ OPENAI_API_KEY detected"),
        Err(_) => {
            println!("❌ OPENAI_API_KEY environment variable not set");
            println!("   Please set: export OPENAI_API_KEY=your_api_key");
            return Ok(());
        }
    }

    // Create OpenAI client
    let client = AiClient::new(Provider::OpenAI)?;
    println!("✅ OpenAI client created successfully");

    // Get model list
    println!("\n📋 Getting OpenAI model list...");
    match client.list_models().await {
        Ok(models) => {
            println!("✅ Successfully got {} models", models.len());
            println!("   Common models:");
            for model in models.iter().filter(|m| m.contains("gpt")) {
                println!("   • {}", model);
            }
        }
        Err(e) => println!("❌ Failed to get model list: {}", e),
    }

    // Test chat completion
    println!("\n💬 Testing chat completion...");
    let request = ChatCompletionRequest::new(
        "gpt-3.5-turbo".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text(
                "Hello! Please respond with 'Hello from OpenAI!' to confirm the connection."
                    .to_string(),
            ),
            function_call: None,
        }],
    )
    .with_max_tokens(20)
    .with_temperature(0.7);

    match client.chat_completion(request).await {
        Ok(response) => {
            println!("✅ Chat completion successful!");
            println!("   Model: {}", response.model);
            println!(
                "   Response: {}",
                response.choices[0].message.content.as_text()
            );
            println!(
                "   Token usage: {} (prompt: {}, completion: {})",
                response.usage.total_tokens,
                response.usage.prompt_tokens,
                response.usage.completion_tokens
            );
        }
        Err(e) => println!("❌ Chat completion failed: {}", e),
    }

    println!("\n🎯 OpenAI config-driven test completed!");
    println!("   This demonstrates the power of config-driven architecture:");
    println!("   • No need to write OpenAI-specific code");
    println!("   • Just add configuration in ProviderConfigs");
    println!("   • Automatically supports all OpenAI-compatible features");

    Ok(())
}

examples/test_all_providers.rs (line 54)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧪 Test All AI Providers");
    println!("=======================");

    // Check proxy configuration
    if let Ok(proxy_url) = std::env::var("AI_PROXY_URL") {
        println!("🌐 Using proxy: {}", proxy_url);
    }

    let providers = vec![
        (Provider::Groq, "Groq", "llama3-8b-8192"),
        (Provider::OpenAI, "OpenAI", "gpt-3.5-turbo"),
        (Provider::DeepSeek, "DeepSeek", "deepseek-chat"),
    ];

    for (provider, name, model) in providers {
        println!("\n🔍 Testing Provider: {}", name);
        println!("{}", "─".repeat(30));

        match AiClient::new(provider) {
            Ok(client) => {
                println!("✅ Client created successfully");

                // Test model list
                match client.list_models().await {
                    Ok(models) => {
                        println!("📋 Available models count: {}", models.len());
                        if !models.is_empty() {
                            println!("   First 3 models: {:?}", &models[..models.len().min(3)]);
                        }
                    }
                    Err(e) => println!("⚠️  Failed to get model list: {}", e),
                }

                // Test chat completion
                let request = ChatCompletionRequest::new(
                    model.to_string(),
                    vec![Message {
                        role: Role::User,
                        content: Content::Text(
                            "Hello! Please respond with just 'Hi' to test the API.".to_string(),
                        ),
                        function_call: None,
                    }],
                )
                .with_max_tokens(10);

                println!("📤 Sending test request to model: {}", model);
                match client.chat_completion(request).await {
                    Ok(response) => {
                        println!("✅ Request successful!");
                        println!("   Response ID: {}", response.id);
                        println!(
                            "   Content: {}",
                            response.choices[0].message.content.as_text()
                        );
                        println!("   Tokens used: {}", response.usage.total_tokens);
                    }
                    Err(e) => println!("❌ Request failed: {}", e),
                }
            }
            Err(e) => {
                println!("❌ Client creation failed: {}", e);
            }
        }
    }

    println!("\n💡 Tips:");
    println!("   • Make sure to set corresponding API key environment variables");
    println!("   • GROQ_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY");
    println!("   • Optionally set AI_PROXY_URL to use proxy server");

    Ok(())
}

Additional examples can be found in:

• examples/function_call_openai.rs
• examples/test_https_proxy.rs
• examples/test_anthropic.rs
• examples/test_openai_specific.rs
• examples/test_gemini.rs
• examples/test_groq_generic.rs
• examples/test_proxy_working.rs
• examples/test_retry_mechanism.rs
• examples/test_all_config_driven.rs
• examples/test_hybrid_architecture.rs

pub async fn chat_completion_stream( &self, request: ChatCompletionRequest, ) -> Result<Box<dyn Stream<Item = Result<ChatCompletionChunk, AiLibError>> + Send + Unpin>, AiLibError>

Streaming chat completion request

Arguments

• request - Chat completion request

Returns

• Result<impl Stream<Item = Result<ChatCompletionChunk, AiLibError>>, AiLibError> - Stream response on success

Examples found in repository

examples/cohere_stream.rs (line 28)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Ensure COHERE_API_KEY env var is set if making real requests
    let client = AiClient::new(Provider::Cohere)?;

    let request = ChatCompletionRequest::new(
        "command-xlarge-nightly".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Write a haiku about rust programming".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(60);

    // List models
    match client.list_models().await {
        Ok(models) => println!("Models: {:?}", models),
        Err(e) => eprintln!("Failed to list models: {}", e),
    }

    // Streaming
    let mut stream = client.chat_completion_stream(request).await?;
    while let Some(chunk) = stream.next().await {
        match chunk {
            Ok(c) => {
                for choice in c.choices {
                    if let Some(delta) = choice.delta.content {
                        print!("{}", delta);
                    }
                }
            }
            Err(e) => {
                eprintln!("Stream error: {}", e);
                break;
            }
        }
    }

    Ok(())
}

examples/test_streaming.rs (line 39)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌊 流式响应测试");
    println!("================");

    // 检查Groq API密钥
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ 未设置GROQ_API_KEY");
        return Ok(());
    }

    // 创建Groq客户端
    let client = AiClient::new(Provider::Groq)?;
    println!("✅ Groq客户端创建成功");

    // 创建流式请求
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text(
                "Please write a short poem about AI in exactly 4 lines.".to_string(),
            ),
            function_call: None,
        }],
    )
    .with_max_tokens(100)
    .with_temperature(0.7);

    println!("\n📤 发送流式请求...");
    println!("   模型: {}", request.model);
    println!("   消息: {}", request.messages[0].content.as_text());

    // 获取流式响应
    match client.chat_completion_stream(request).await {
        Ok(mut stream) => {
            println!("\n🌊 开始接收流式响应:");
            println!("{}", "─".repeat(50));

            let mut full_content = String::new();
            let mut chunk_count = 0;

            while let Some(result) = stream.next().await {
                match result {
                    Ok(chunk) => {
                        chunk_count += 1;

                        if let Some(choice) = chunk.choices.first() {
                            if let Some(content) = &choice.delta.content {
                                print!("{}", content);
                                full_content.push_str(content);

                                // 刷新输出
                                use std::io::{self, Write};
                                io::stdout().flush().unwrap();
                            }

                            // 检查是否完成
                            if choice.finish_reason.is_some() {
                                println!("\n{}", "─".repeat(50));
                                println!("✅ 流式响应完成!");
                                println!("   完成原因: {:?}", choice.finish_reason);
                                break;
                            }
                        }
                    }
                    Err(e) => {
                        println!("\n❌ 流式响应错误: {}", e);
                        break;
                    }
                }
            }

            println!("\n📊 流式响应统计:");
            println!("   数据块数量: {}", chunk_count);
            println!("   总内容长度: {} 字符", full_content.len());
            println!("   完整内容: \"{}\"", full_content.trim());
        }
        Err(e) => {
            println!("❌ 流式请求失败: {}", e);
        }
    }

    println!("\n💡 流式响应的优势:");
    println!("   • 实时显示生成内容");
    println!("   • 更好的用户体验");
    println!("   • 可以提前停止生成");
    println!("   • 适合长文本生成");

    Ok(())
}

examples/test_groq_generic.rs (line 48)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔄 测试配置驱动的Groq");
    println!("====================");

    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ 未设置GROQ_API_KEY");
        return Ok(());
    }

    let client = AiClient::new(Provider::Groq)?;
    println!("✅ Groq客户端创建成功 (使用GenericAdapter)");

    // 测试普通聊天
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text(
                "Say 'Hello from Generic Groq!' in exactly those words.".to_string(),
            ),
            function_call: None,
        }],
    )
    .with_max_tokens(20);

    println!("\n💬 测试普通聊天...");
    match client.chat_completion(request.clone()).await {
        Ok(response) => {
            println!("✅ 普通聊天成功!");
            println!(
                "   响应: '{}'",
                response.choices[0].message.content.as_text()
            );
            println!("   Token使用: {}", response.usage.total_tokens);
        }
        Err(e) => {
            println!("❌ 普通聊天失败: {}", e);
        }
    }

    // 测试流式聊天
    println!("\n🌊 测试流式聊天...");
    match client.chat_completion_stream(request).await {
        Ok(mut stream) => {
            print!("   流式响应: ");
            let mut content = String::new();

            while let Some(result) = stream.next().await {
                match result {
                    Ok(chunk) => {
                        if let Some(choice) = chunk.choices.first() {
                            if let Some(text) = &choice.delta.content {
                                print!("{}", text);
                                content.push_str(text);
                                use std::io::{self, Write};
                                io::stdout().flush().unwrap();
                            }
                            if choice.finish_reason.is_some() {
                                println!();
                                break;
                            }
                        }
                    }
                    Err(e) => {
                        println!("\n❌ 流式错误: {}", e);
                        break;
                    }
                }
            }

            if !content.is_empty() {
                println!("✅ 流式聊天成功!");
                println!("   完整内容: '{}'", content.trim());
            }
        }
        Err(e) => {
            println!("❌ 流式聊天失败: {}", e);
        }
    }

    // 测试模型列表
    println!("\n📋 测试模型列表...");
    match client.list_models().await {
        Ok(models) => {
            println!("✅ 模型列表获取成功!");
            println!("   可用模型: {:?}", models);
        }
        Err(e) => {
            println!("❌ 模型列表获取失败: {}", e);
        }
    }

    println!("\n🎯 配置驱动Groq测试结果:");
    println!("   • 使用GenericAdapter而不是GroqAdapter");
    println!("   • 代码量从250行减少到10行配置");
    println!("   • 功能完全相同：普通聊天、流式聊天、模型列表");
    println!("   • 证明了OpenAI兼容性和通用适配器的有效性");

    Ok(())
}

examples/test_streaming_clean.rs (line 34)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌊 清洁版流式响应测试");
    println!("======================");

    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ 未设置GROQ_API_KEY");
        return Ok(());
    }

    let client = AiClient::new(Provider::Groq)?;
    println!("✅ Groq客户端创建成功");

    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Write a haiku about programming.".to_string()),
            function_call: None,
        }],
    )
    .with_max_tokens(50)
    .with_temperature(0.8);

    println!(
        "\n📤 发送流式请求: {}",
        request.messages[0].content.as_text()
    );

    match client.chat_completion_stream(request).await {
        Ok(mut stream) => {
            println!("\n🎭 AI回复:");
            print!("   ");

            let mut content_parts: Vec<String> = Vec::new();

            while let Some(result) = stream.next().await {
                match result {
                    Ok(chunk) => {
                        if let Some(choice) = chunk.choices.first() {
                            if let Some(content) = &choice.delta.content {
                                // try to parse JSON-shaped content first
                                if content.contains("\"content\":") {
                                    if let Ok(json) =
                                        serde_json::from_str::<serde_json::Value>(content)
                                    {
                                        if let Some(text) = json["content"].as_str() {
                                            if !text.is_empty() {
                                                print!("{}", text);
                                                content_parts.push(text.to_string());
                                                use std::io::{self, Write};
                                                io::stdout().flush().unwrap();
                                            }
                                        }
                                    }
                                } else if !content.trim().is_empty() && !content.contains("data:") {
                                    // direct plain text
                                    print!("{}", content);
                                    content_parts.push(content.clone());
                                    use std::io::{self, Write};
                                    io::stdout().flush().unwrap();
                                }
                            }

                            if choice.finish_reason.is_some() {
                                println!("\n");
                                break;
                            }
                        }
                    }
                    Err(e) => {
                        println!("\n❌ 流式响应错误: {}", e);
                        break;
                    }
                }
            }

            let full_content = content_parts.join("");
            if !full_content.is_empty() {
                println!("✅ 流式响应完成!");
                println!("📝 完整内容: \"{}\"", full_content.trim());
            } else {
                println!("⚠️  未提取到有效内容，可能需要改进SSE解析");
            }
        }
        Err(e) => {
            println!("❌ 流式请求失败: {}", e);
        }
    }

    Ok(())
}

examples/test_streaming_improved.rs (line 34)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌊 改进的流式响应测试");
    println!("======================");

    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ 未设置GROQ_API_KEY");
        return Ok(());
    }

    let client = AiClient::new(Provider::Groq)?;
    println!("✅ Groq客户端创建成功");

    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text(
                "Write a creative story about a robot learning to paint. Keep it under 100 words."
                    .to_string(),
            ),
            function_call: None,
        }],
    )
    .with_max_tokens(150)
    .with_temperature(0.8);

    println!("\n📤 发送流式请求...");

    match client.chat_completion_stream(request).await {
        Ok(mut stream) => {
            println!("🎨 AI创作中:");
            print!("   ");

            let mut content = String::new();
            let mut chunk_count = 0;

            while let Some(result) = stream.next().await {
                match result {
                    Ok(chunk) => {
                        chunk_count += 1;

                        if let Some(choice) = chunk.choices.first() {
                            if let Some(text) = &choice.delta.content {
                                if !text.is_empty() {
                                    print!("{}", text);
                                    content.push_str(text);

                                    use std::io::{self, Write};
                                    io::stdout().flush().unwrap();
                                }
                            }

                            if choice.finish_reason.is_some() {
                                println!("\n");
                                println!("✅ 创作完成! (原因: {:?})", choice.finish_reason);
                                break;
                            }
                        }
                    }
                    Err(e) => {
                        println!("\n❌ 流式错误: {}", e);
                        break;
                    }
                }
            }

            println!("\n📊 统计信息:");
            println!("   数据块: {}", chunk_count);
            println!("   字符数: {}", content.len());
            println!("   单词数: {}", content.split_whitespace().count());
        }
        Err(e) => {
            println!("❌ 流式请求失败: {}", e);
        }
    }

    // 测试DeepSeek流式响应
    if std::env::var("DEEPSEEK_API_KEY").is_ok() {
        println!("\n{}", "=".repeat(50));
        println!("🧠 测试DeepSeek流式响应");

        let deepseek_client = AiClient::new(Provider::DeepSeek)?;
        let request = ChatCompletionRequest::new(
            "deepseek-chat".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Explain quantum computing in one sentence.".to_string()),
                function_call: None,
            }],
        )
        .with_max_tokens(50);

        match deepseek_client.chat_completion_stream(request).await {
            Ok(mut stream) => {
                println!("🔬 DeepSeek回复:");
                print!("   ");

                while let Some(result) = stream.next().await {
                    match result {
                        Ok(chunk) => {
                            if let Some(choice) = chunk.choices.first() {
                                if let Some(text) = &choice.delta.content {
                                    print!("{}", text);
                                    use std::io::{self, Write};
                                    io::stdout().flush().unwrap();
                                }
                                if choice.finish_reason.is_some() {
                                    println!("\n✅ DeepSeek流式响应成功!");
                                    break;
                                }
                            }
                        }
                        Err(e) => {
                            println!("\n❌ DeepSeek流式错误: {}", e);
                            break;
                        }
                    }
                }
            }
            Err(e) => {
                println!("❌ DeepSeek流式请求失败: {}", e);
            }
        }
    }

    Ok(())
}

pub async fn chat_completion_stream_with_cancel( &self, request: ChatCompletionRequest, ) -> Result<(Box<dyn Stream<Item = Result<ChatCompletionChunk, AiLibError>> + Send + Unpin>, CancelHandle), AiLibError>

Streaming chat completion request with cancel control

Arguments

• request - Chat completion request

Returns

• Result<(impl Stream<Item = Result<ChatCompletionChunk, AiLibError>> + Send + Unpin, CancelHandle), AiLibError> - Returns streaming response and cancel handle on success

pub async fn chat_completion_batch( &self, requests: Vec<ChatCompletionRequest>, concurrency_limit: Option<usize>, ) -> Result<Vec<Result<ChatCompletionResponse, AiLibError>>, AiLibError>

Batch chat completion requests

Arguments

• requests - List of chat completion requests
• concurrency_limit - Maximum concurrent request count (None means unlimited)

Returns

• Result<Vec<Result<ChatCompletionResponse, AiLibError>>, AiLibError> - Returns response results for all requests

Example

use ai_lib::{AiClient, Provider, ChatCompletionRequest, Message, Role};
use ai_lib::types::common::Content;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AiClient::new(Provider::Groq)?;
     
    let requests = vec![
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Hello".to_string()),
                function_call: None,
            }],
        ),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("How are you?".to_string()),
                function_call: None,
            }],
        ),
    ];
     
    // Limit concurrency to 5
    let responses = client.chat_completion_batch(requests, Some(5)).await?;
     
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => println!("Request {}: {}", i, resp.choices[0].message.content.as_text()),
            Err(e) => println!("Request {} failed: {}", i, e),
        }
    }
     
    Ok(())
}

Examples found in repository

examples/batch_processing.rs (line 73)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Batch Processing Example");
    println!("==================================");

    // Create client
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Prepare multiple requests
    let requests = vec![
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is the capital of France?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.7)
        .with_max_tokens(50),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is 2 + 2?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.1)
        .with_max_tokens(20),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Tell me a short joke.".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.9)
        .with_max_tokens(100),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text(
                    "What is the largest planet in our solar system?".to_string(),
                ),
                function_call: None,
            }],
        )
        .with_temperature(0.5)
        .with_max_tokens(60),
    ];

    println!(
        "📤 Prepared {} requests for batch processing",
        requests.len()
    );

    // Method 1: Batch processing with concurrency limit
    println!("\n🔄 Method 1: Batch processing with concurrency limit (2)");
    let start_time = std::time::Instant::now();

    let responses = client
        .chat_completion_batch(requests.clone(), Some(2))
        .await?;

    let duration = start_time.elapsed();
    println!("⏱️  Batch processing completed in {:?}", duration);

    // Process responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    // Method 2: Smart batch processing (auto-select strategy)
    println!("\n🧠 Method 2: Smart batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch_smart(requests.clone()).await?;

    let duration = start_time.elapsed();
    println!("⏱️  Smart batch processing completed in {:?}", duration);

    // Count successes and failures
    let successful: Vec<_> = responses.iter().filter_map(|r| r.as_ref().ok()).collect();
    let failed: Vec<_> = responses
        .iter()
        .enumerate()
        .filter_map(|(i, r)| r.as_ref().err().map(|e| (i, e)))
        .collect();

    println!("📊 Results:");
    println!("   ✅ Successful: {}/{}", successful.len(), responses.len());
    println!("   ❌ Failed: {}/{}", failed.len(), responses.len());
    println!(
        "   📈 Success rate: {:.1}%",
        (successful.len() as f64 / responses.len() as f64) * 100.0
    );

    // Method 3: Unlimited concurrent batch processing
    println!("\n🚀 Method 3: Unlimited concurrent batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch(requests, None).await?;

    let duration = start_time.elapsed();
    println!(
        "⏱️  Unlimited concurrent processing completed in {:?}",
        duration
    );

    // Display all responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    println!("\n🎉 Batch processing example completed successfully!");
    Ok(())
}

pub async fn chat_completion_batch_smart( &self, requests: Vec<ChatCompletionRequest>, ) -> Result<Vec<Result<ChatCompletionResponse, AiLibError>>, AiLibError>

Smart batch processing: automatically choose processing strategy based on request count

Arguments

• requests - List of chat completion requests

Returns

• Result<Vec<Result<ChatCompletionResponse, AiLibError>>, AiLibError> - Returns response results for all requests

Examples found in repository

examples/batch_processing.rs (line 99)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Batch Processing Example");
    println!("==================================");

    // Create client
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Prepare multiple requests
    let requests = vec![
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is the capital of France?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.7)
        .with_max_tokens(50),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is 2 + 2?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.1)
        .with_max_tokens(20),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Tell me a short joke.".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.9)
        .with_max_tokens(100),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text(
                    "What is the largest planet in our solar system?".to_string(),
                ),
                function_call: None,
            }],
        )
        .with_temperature(0.5)
        .with_max_tokens(60),
    ];

    println!(
        "📤 Prepared {} requests for batch processing",
        requests.len()
    );

    // Method 1: Batch processing with concurrency limit
    println!("\n🔄 Method 1: Batch processing with concurrency limit (2)");
    let start_time = std::time::Instant::now();

    let responses = client
        .chat_completion_batch(requests.clone(), Some(2))
        .await?;

    let duration = start_time.elapsed();
    println!("⏱️  Batch processing completed in {:?}", duration);

    // Process responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    // Method 2: Smart batch processing (auto-select strategy)
    println!("\n🧠 Method 2: Smart batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch_smart(requests.clone()).await?;

    let duration = start_time.elapsed();
    println!("⏱️  Smart batch processing completed in {:?}", duration);

    // Count successes and failures
    let successful: Vec<_> = responses.iter().filter_map(|r| r.as_ref().ok()).collect();
    let failed: Vec<_> = responses
        .iter()
        .enumerate()
        .filter_map(|(i, r)| r.as_ref().err().map(|e| (i, e)))
        .collect();

    println!("📊 Results:");
    println!("   ✅ Successful: {}/{}", successful.len(), responses.len());
    println!("   ❌ Failed: {}/{}", failed.len(), responses.len());
    println!(
        "   📈 Success rate: {:.1}%",
        (successful.len() as f64 / responses.len() as f64) * 100.0
    );

    // Method 3: Unlimited concurrent batch processing
    println!("\n🚀 Method 3: Unlimited concurrent batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch(requests, None).await?;

    let duration = start_time.elapsed();
    println!(
        "⏱️  Unlimited concurrent processing completed in {:?}",
        duration
    );

    // Display all responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    println!("\n🎉 Batch processing example completed successfully!");
    Ok(())
}

pub async fn list_models(&self) -> Result<Vec<String>, AiLibError>

Batch chat completion requests

Arguments

• requests - List of chat completion requests
• concurrency_limit - Maximum concurrent request count (None means unlimited)

Returns

• Result<Vec<Result<ChatCompletionResponse, AiLibError>>, AiLibError> - Returns response results for all requests

Example

use ai_lib::{AiClient, Provider, ChatCompletionRequest, Message, Role};
use ai_lib::types::common::Content;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AiClient::new(Provider::Groq)?;
     
    let requests = vec![
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Hello".to_string()),
                function_call: None,
            }],
        ),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("How are you?".to_string()),
                function_call: None,
            }],
        ),
    ];
     
    // Limit concurrency to 5
    let responses = client.chat_completion_batch(requests, Some(5)).await?;
     
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => println!("Request {}: {}", i, resp.choices[0].message.content.as_text()),
            Err(e) => println!("Request {} failed: {}", i, e),
        }
    }
     
    Ok(())
}

Get list of supported models

Returns

• Result<Vec<String>, AiLibError> - Returns model list on success, error on failure

Examples found in repository

examples/list_models_smoke.rs (line 25)

async fn main() {
    let providers = vec![
        Provider::Groq,
        Provider::XaiGrok,
        Provider::Ollama,
        Provider::DeepSeek,
        Provider::Anthropic,
        Provider::AzureOpenAI,
        Provider::HuggingFace,
        Provider::TogetherAI,
        Provider::Qwen,
        Provider::OpenAI,
        Provider::Gemini,
        Provider::Mistral,
        Provider::Cohere,
        // Provider::Bedrock, // Removed: Bedrock deferred implementation/not in public API
    ];

    for p in providers {
        println!("--- Provider: {:?} ---", p);
        match AiClient::new(p) {
            Ok(client) => match client.list_models().await {
                Ok(models) => {
                    println!("Found {} models (showing up to 5):", models.len());
                    for m in models.into_iter().take(5) {
                        println!(" - {}", m);
                    }
                }
                Err(e) => println!("list_models error: {:?}", e),
            },
            Err(e) => println!("client init error: {:?}", e),
        }
    }
}

examples/cohere_stream.rs (line 22)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Ensure COHERE_API_KEY env var is set if making real requests
    let client = AiClient::new(Provider::Cohere)?;

    let request = ChatCompletionRequest::new(
        "command-xlarge-nightly".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Write a haiku about rust programming".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(60);

    // List models
    match client.list_models().await {
        Ok(models) => println!("Models: {:?}", models),
        Err(e) => eprintln!("Failed to list models: {}", e),
    }

    // Streaming
    let mut stream = client.chat_completion_stream(request).await?;
    while let Some(chunk) = stream.next().await {
        match chunk {
            Ok(c) => {
                for choice in c.choices {
                    if let Some(delta) = choice.delta.content {
                        print!("{}", delta);
                    }
                }
            }
            Err(e) => {
                eprintln!("Stream error: {}", e);
                break;
            }
        }
    }

    Ok(())
}

examples/basic_usage.rs (line 18)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Basic Usage Example");
    println!("================================");

    // Switch model provider by changing Provider value
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Get list of supported models
    let models = client.list_models().await?;
    println!("📋 Available models: {:?}", models);

    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please introduce yourself briefly.".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(100);

    println!("📤 Sending request to model: {}", request.model);

    // Send request
    let response = client.chat_completion(request).await?;

    println!("📥 Received response:");
    println!("   ID: {}", response.id);
    println!("   Model: {}", response.model);
    println!(
        "   Content: {}",
        response.choices[0].message.content.as_text()
    );
    println!("   Usage: {} tokens", response.usage.total_tokens);

    Ok(())
}

examples/config_driven_example.rs (line 28)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 Config-driven AI-lib Example");
    println!("================================");

    // Demonstrate the advantages of config-driven approach: easy provider switching
    let providers = vec![
        (Provider::Groq, "Groq"),
        (Provider::OpenAI, "OpenAI"),
        (Provider::DeepSeek, "DeepSeek"),
    ];

    for (provider, name) in providers {
        println!("\n📡 Testing Provider: {}", name);

        // Create client - just change the enum value
        let client = AiClient::new(provider)?;
        println!(
            "✅ Client created successfully: {:?}",
            client.current_provider()
        );

        // Get model list
        match client.list_models().await {
            Ok(models) => println!("📋 Available models: {:?}", models),
            Err(e) => println!("⚠️  Failed to get model list: {}", e),
        }

        // Create test request
        let request = ChatCompletionRequest::new(
            "test-model".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Hello from ai-lib!".to_string()),
                function_call: None,
            }],
        );

        println!("📤 Request prepared, model: {}", request.model);
        println!("   (Need to set corresponding API_KEY environment variable for actual calls)");
    }

    println!("\n🎯 Core advantages of config-driven approach:");
    println!("   • Zero-code switching: just change Provider enum value");
    println!("   • Unified interface: all providers use the same API");
    println!("   • Rapid expansion: add new compatible providers with just configuration");

    Ok(())
}

examples/proxy_example.rs (line 44)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌐 AI-lib Proxy Server Support Example");
    println!("=====================================");

    // Check proxy configuration
    match std::env::var("AI_PROXY_URL") {
        Ok(proxy_url) => {
            println!("✅ Proxy configuration detected: {}", proxy_url);
            println!("   All HTTP requests will go through this proxy server");
        }
        Err(_) => {
            println!("ℹ️  AI_PROXY_URL environment variable not set");
            println!("   To use proxy, set: export AI_PROXY_URL=http://proxy.example.com:8080");
        }
    }

    println!("\n🚀 Creating AI client...");
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Client created successfully, provider: {:?}",
        client.current_provider()
    );

    // Create test request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! This request may go through a proxy.".to_string()),
            function_call: None,
        }],
    );

    println!("\n📤 Preparing to send request...");
    println!("   Model: {}", request.model);
    println!("   Message: {}", request.messages[0].content.as_text());

    // Get model list (this request will also go through proxy)
    match client.list_models().await {
        Ok(models) => {
            println!("\n📋 Model list obtained through proxy:");
            for model in models {
                println!("   • {}", model);
            }
        }
        Err(e) => {
            println!("\n⚠️  Failed to get model list: {}", e);
            println!("   This may be due to:");
            println!("   • GROQ_API_KEY environment variable not set");
            println!("   • Proxy server configuration error");
            println!("   • Network connection issue");
        }
    }

    println!("\n💡 Proxy Configuration Instructions:");
    println!("   • Set environment variable: AI_PROXY_URL=http://your-proxy:port");
    println!("   • Supports HTTP and HTTPS proxies");
    println!("   • Supports authenticated proxies: http://user:pass@proxy:port");
    println!("   • All AI providers will automatically use this proxy configuration");

    Ok(())
}

examples/openai_test.rs (line 26)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🤖 OpenAI Provider Test");
    println!("======================");

    // Check API key
    match std::env::var("OPENAI_API_KEY") {
        Ok(_) => println!("✅ OPENAI_API_KEY detected"),
        Err(_) => {
            println!("❌ OPENAI_API_KEY environment variable not set");
            println!("   Please set: export OPENAI_API_KEY=your_api_key");
            return Ok(());
        }
    }

    // Create OpenAI client
    let client = AiClient::new(Provider::OpenAI)?;
    println!("✅ OpenAI client created successfully");

    // Get model list
    println!("\n📋 Getting OpenAI model list...");
    match client.list_models().await {
        Ok(models) => {
            println!("✅ Successfully got {} models", models.len());
            println!("   Common models:");
            for model in models.iter().filter(|m| m.contains("gpt")) {
                println!("   • {}", model);
            }
        }
        Err(e) => println!("❌ Failed to get model list: {}", e),
    }

    // Test chat completion
    println!("\n💬 Testing chat completion...");
    let request = ChatCompletionRequest::new(
        "gpt-3.5-turbo".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text(
                "Hello! Please respond with 'Hello from OpenAI!' to confirm the connection."
                    .to_string(),
            ),
            function_call: None,
        }],
    )
    .with_max_tokens(20)
    .with_temperature(0.7);

    match client.chat_completion(request).await {
        Ok(response) => {
            println!("✅ Chat completion successful!");
            println!("   Model: {}", response.model);
            println!(
                "   Response: {}",
                response.choices[0].message.content.as_text()
            );
            println!(
                "   Token usage: {} (prompt: {}, completion: {})",
                response.usage.total_tokens,
                response.usage.prompt_tokens,
                response.usage.completion_tokens
            );
        }
        Err(e) => println!("❌ Chat completion failed: {}", e),
    }

    println!("\n🎯 OpenAI config-driven test completed!");
    println!("   This demonstrates the power of config-driven architecture:");
    println!("   • No need to write OpenAI-specific code");
    println!("   • Just add configuration in ProviderConfigs");
    println!("   • Automatically supports all OpenAI-compatible features");

    Ok(())
}

Additional examples can be found in:

• examples/test_all_providers.rs
• examples/test_anthropic.rs
• examples/test_openai_specific.rs
• examples/test_gemini.rs
• examples/test_groq_generic.rs
• examples/test_proxy_working.rs
• examples/test_all_config_driven.rs

pub fn switch_provider(&mut self, provider: Provider) -> Result<(), AiLibError>

Switch AI model provider

Arguments

• provider - New provider

Returns

• Result<(), AiLibError> - Returns () on success, error on failure

Example

use ai_lib::{AiClient, Provider};

let mut client = AiClient::new(Provider::Groq)?;
// Switch from Groq to Groq (demonstrating switch functionality)
client.switch_provider(Provider::Groq)?;

pub fn current_provider(&self) -> Provider

Get current provider

Examples found in repository

examples/basic_usage.rs (line 14)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Basic Usage Example");
    println!("================================");

    // Switch model provider by changing Provider value
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Get list of supported models
    let models = client.list_models().await?;
    println!("📋 Available models: {:?}", models);

    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please introduce yourself briefly.".to_string()),
            function_call: None,
        }],
    )
    .with_temperature(0.7)
    .with_max_tokens(100);

    println!("📤 Sending request to model: {}", request.model);

    // Send request
    let response = client.chat_completion(request).await?;

    println!("📥 Received response:");
    println!("   ID: {}", response.id);
    println!("   Model: {}", response.model);
    println!(
        "   Content: {}",
        response.choices[0].message.content.as_text()
    );
    println!("   Usage: {} tokens", response.usage.total_tokens);

    Ok(())
}

examples/config_driven_example.rs (line 24)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 Config-driven AI-lib Example");
    println!("================================");

    // Demonstrate the advantages of config-driven approach: easy provider switching
    let providers = vec![
        (Provider::Groq, "Groq"),
        (Provider::OpenAI, "OpenAI"),
        (Provider::DeepSeek, "DeepSeek"),
    ];

    for (provider, name) in providers {
        println!("\n📡 Testing Provider: {}", name);

        // Create client - just change the enum value
        let client = AiClient::new(provider)?;
        println!(
            "✅ Client created successfully: {:?}",
            client.current_provider()
        );

        // Get model list
        match client.list_models().await {
            Ok(models) => println!("📋 Available models: {:?}", models),
            Err(e) => println!("⚠️  Failed to get model list: {}", e),
        }

        // Create test request
        let request = ChatCompletionRequest::new(
            "test-model".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Hello from ai-lib!".to_string()),
                function_call: None,
            }],
        );

        println!("📤 Request prepared, model: {}", request.model);
        println!("   (Need to set corresponding API_KEY environment variable for actual calls)");
    }

    println!("\n🎯 Core advantages of config-driven approach:");
    println!("   • Zero-code switching: just change Provider enum value");
    println!("   • Unified interface: all providers use the same API");
    println!("   • Rapid expansion: add new compatible providers with just configuration");

    Ok(())
}

examples/proxy_example.rs (line 26)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🌐 AI-lib Proxy Server Support Example");
    println!("=====================================");

    // Check proxy configuration
    match std::env::var("AI_PROXY_URL") {
        Ok(proxy_url) => {
            println!("✅ Proxy configuration detected: {}", proxy_url);
            println!("   All HTTP requests will go through this proxy server");
        }
        Err(_) => {
            println!("ℹ️  AI_PROXY_URL environment variable not set");
            println!("   To use proxy, set: export AI_PROXY_URL=http://proxy.example.com:8080");
        }
    }

    println!("\n🚀 Creating AI client...");
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Client created successfully, provider: {:?}",
        client.current_provider()
    );

    // Create test request
    let request = ChatCompletionRequest::new(
        "llama3-8b-8192".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! This request may go through a proxy.".to_string()),
            function_call: None,
        }],
    );

    println!("\n📤 Preparing to send request...");
    println!("   Model: {}", request.model);
    println!("   Message: {}", request.messages[0].content.as_text());

    // Get model list (this request will also go through proxy)
    match client.list_models().await {
        Ok(models) => {
            println!("\n📋 Model list obtained through proxy:");
            for model in models {
                println!("   • {}", model);
            }
        }
        Err(e) => {
            println!("\n⚠️  Failed to get model list: {}", e);
            println!("   This may be due to:");
            println!("   • GROQ_API_KEY environment variable not set");
            println!("   • Proxy server configuration error");
            println!("   • Network connection issue");
        }
    }

    println!("\n💡 Proxy Configuration Instructions:");
    println!("   • Set environment variable: AI_PROXY_URL=http://your-proxy:port");
    println!("   • Supports HTTP and HTTPS proxies");
    println!("   • Supports authenticated proxies: http://user:pass@proxy:port");
    println!("   • All AI providers will automatically use this proxy configuration");

    Ok(())
}

examples/batch_processing.rs (line 14)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI-lib Batch Processing Example");
    println!("==================================");

    // Create client
    let client = AiClient::new(Provider::Groq)?;
    println!(
        "✅ Created client with provider: {:?}",
        client.current_provider()
    );

    // Prepare multiple requests
    let requests = vec![
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is the capital of France?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.7)
        .with_max_tokens(50),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("What is 2 + 2?".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.1)
        .with_max_tokens(20),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text("Tell me a short joke.".to_string()),
                function_call: None,
            }],
        )
        .with_temperature(0.9)
        .with_max_tokens(100),
        ChatCompletionRequest::new(
            "llama3-8b-8192".to_string(),
            vec![Message {
                role: Role::User,
                content: Content::Text(
                    "What is the largest planet in our solar system?".to_string(),
                ),
                function_call: None,
            }],
        )
        .with_temperature(0.5)
        .with_max_tokens(60),
    ];

    println!(
        "📤 Prepared {} requests for batch processing",
        requests.len()
    );

    // Method 1: Batch processing with concurrency limit
    println!("\n🔄 Method 1: Batch processing with concurrency limit (2)");
    let start_time = std::time::Instant::now();

    let responses = client
        .chat_completion_batch(requests.clone(), Some(2))
        .await?;

    let duration = start_time.elapsed();
    println!("⏱️  Batch processing completed in {:?}", duration);

    // Process responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    // Method 2: Smart batch processing (auto-select strategy)
    println!("\n🧠 Method 2: Smart batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch_smart(requests.clone()).await?;

    let duration = start_time.elapsed();
    println!("⏱️  Smart batch processing completed in {:?}", duration);

    // Count successes and failures
    let successful: Vec<_> = responses.iter().filter_map(|r| r.as_ref().ok()).collect();
    let failed: Vec<_> = responses
        .iter()
        .enumerate()
        .filter_map(|(i, r)| r.as_ref().err().map(|e| (i, e)))
        .collect();

    println!("📊 Results:");
    println!("   ✅ Successful: {}/{}", successful.len(), responses.len());
    println!("   ❌ Failed: {}/{}", failed.len(), responses.len());
    println!(
        "   📈 Success rate: {:.1}%",
        (successful.len() as f64 / responses.len() as f64) * 100.0
    );

    // Method 3: Unlimited concurrent batch processing
    println!("\n🚀 Method 3: Unlimited concurrent batch processing");
    let start_time = std::time::Instant::now();

    let responses = client.chat_completion_batch(requests, None).await?;

    let duration = start_time.elapsed();
    println!(
        "⏱️  Unlimited concurrent processing completed in {:?}",
        duration
    );

    // Display all responses
    for (i, response) in responses.iter().enumerate() {
        match response {
            Ok(resp) => {
                println!(
                    "✅ Request {}: {}",
                    i + 1,
                    resp.choices[0].message.content.as_text()
                );
            }
            Err(e) => {
                println!("❌ Request {} failed: {}", i + 1, e);
            }
        }
    }

    println!("\n🎉 Batch processing example completed successfully!");
    Ok(())
}

examples/builder_pattern.rs (line 18)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🚀 AI Client Builder Pattern Example");
    println!("===================================");

    // Example 1: Simplest usage - automatic environment variable detection
    println!("\n📋 Example 1: Simplest usage");
    println!("   Automatically detect GROQ_BASE_URL and AI_PROXY_URL from environment variables");

    let client = AiClientBuilder::new(Provider::Groq).build()?;
    println!(
        "✅ Client created successfully, provider: {:?}",
        client.current_provider()
    );

    // Example 2: Custom base_url
    println!("\n📋 Example 2: Custom base_url");
    println!("   Use custom Groq server address");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .build()?;
    println!("✅ Client created successfully with custom base_url");

    // Example 3: Custom base_url and proxy
    println!("\n📋 Example 3: Custom base_url and proxy");
    println!("   Use custom server and proxy");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ Client created successfully with custom base_url and proxy");

    // Example 4: Full custom configuration
    println!("\n📋 Example 4: Full custom configuration");
    println!("   Custom timeout, connection pool and other advanced configurations");

    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .with_timeout(Duration::from_secs(60))
        .with_pool_config(32, Duration::from_secs(90))
        .build()?;
    println!("✅ Client created successfully with full custom configuration");

    // Example 5: Use convenient builder method
    println!("\n📋 Example 5: Use convenient builder method");
    println!("   Create builder through AiClient::builder()");

    let client = AiClient::builder(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ Client created successfully using convenient builder method");

    // Example 6: Environment variable priority demonstration
    println!("\n📋 Example 6: Environment variable priority demonstration");
    println!("   Set environment variables, then use builder");

    // Set environment variables
    std::env::set_var("GROQ_BASE_URL", "https://env.groq.com");
    std::env::set_var("AI_PROXY_URL", "http://env.proxy.com:8080");

    // Don't set any custom configuration, should use environment variables
    let client = AiClientBuilder::new(Provider::Groq).build()?;
    println!("✅ Client created successfully using environment variable configuration");

    // Explicit settings override environment variables
    let client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://explicit.groq.com")
        .with_proxy(Some("http://explicit.proxy.com:8080"))
        .build()?;
    println!(
        "✅ Client created successfully, explicit configuration overrides environment variables"
    );

    // Example 7: Different provider configurations
    println!("\n📋 Example 7: Different provider configurations");

    // Groq
    let groq_client = AiClientBuilder::new(Provider::Groq)
        .with_base_url("https://custom.groq.com")
        .build()?;
    println!("✅ Groq client created successfully");

    // DeepSeek
    let deepseek_client = AiClientBuilder::new(Provider::DeepSeek)
        .with_base_url("https://custom.deepseek.com")
        .with_proxy(Some("http://proxy.example.com:8080"))
        .build()?;
    println!("✅ DeepSeek client created successfully");

    // Ollama (local deployment)
    let ollama_client = AiClientBuilder::new(Provider::Ollama)
        .with_base_url("http://localhost:11434")
        .build()?;
    println!("✅ Ollama client created successfully");

    // Example 8: Error handling
    println!("\n📋 Example 8: Error handling");
    println!("   Try to set custom configuration for unsupported provider");

    match AiClientBuilder::new(Provider::OpenAI)
        .with_base_url("https://custom.openai.com")
        .build()
    {
        Ok(_) => println!("❌ This should not succeed"),
        Err(e) => println!("✅ Correctly caught error: {}", e),
    }

    println!("\n🎉 All examples completed!");
    println!("\n💡 Advantages of builder pattern:");
    println!("   1. Automatic environment variable detection, reducing configuration code");
    println!("   2. Support for progressive custom configuration");
    println!("   3. Method chaining for cleaner code");
    println!("   4. Backward compatible, existing code requires no changes");
    println!("   5. Support for advanced configuration (timeout, connection pool, etc.)");

    Ok(())
}