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/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/hello_groq.rs (line 17)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 检查环境变量
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        println!("   Or set it in .env file");
        return Ok(());
    }
    
    println!("🔧 Creating Groq client using new Provider classification system...");
    
    // Create Groq client - using new provider classification system
    let client = AiClient::new(Provider::Groq)?;
    
    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama-3.1-8b-instant".to_string(), // Available Groq model
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please respond with a simple greeting.".to_string()),
            function_call: None,
        }],
    );
    
    println!("🚀 Sending request to Groq...");
    println!("📝 Request: Hello! Please respond with a simple greeting.");
    println!();
    
    // 发送请求并获取响应
    let response = client.chat_completion(request).await?;
    
    println!("✅ Groq Response:");
    match &response.choices[0].message.content {
        Content::Text(text) => println!("{}", text),
        Content::Json(json) => println!("JSON: {:?}", json),
        Content::Image { url, mime, name } => println!("Image: url={:?}, mime={:?}, name={:?}", url, mime, name),
        Content::Audio { url, mime } => println!("Audio: url={:?}, mime={:?}", url, mime),
    }
    
    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/proxy_example.rs (line 23)

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

Additional examples can be found in:

• examples/function_call_openai.rs
• examples/model_override_demo.rs
• examples/architecture_progress.rs
• examples/test_streaming.rs
• examples/quickstart.rs
• examples/batch_processing.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/model_override_demo.rs (line 49)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

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/hello_groq.rs (line 34)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 检查环境变量
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        println!("   Or set it in .env file");
        return Ok(());
    }
    
    println!("🔧 Creating Groq client using new Provider classification system...");
    
    // Create Groq client - using new provider classification system
    let client = AiClient::new(Provider::Groq)?;
    
    // Create chat request
    let request = ChatCompletionRequest::new(
        "llama-3.1-8b-instant".to_string(), // Available Groq model
        vec![Message {
            role: Role::User,
            content: Content::Text("Hello! Please respond with a simple greeting.".to_string()),
            function_call: None,
        }],
    );
    
    println!("🚀 Sending request to Groq...");
    println!("📝 Request: Hello! Please respond with a simple greeting.");
    println!();
    
    // 发送请求并获取响应
    let response = client.chat_completion(request).await?;
    
    println!("✅ Groq Response:");
    match &response.choices[0].message.content {
        Content::Text(text) => println!("{}", text),
        Content::Json(json) => println!("JSON: {:?}", json),
        Content::Image { url, mime, name } => println!("Image: url={:?}, mime={:?}, name={:?}", url, mime, name),
        Content::Audio { url, mime } => println!("Audio: url={:?}, mime={:?}", url, mime),
    }
    
    Ok(())
}

examples/function_call_openai.rs (line 40)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔧 OpenAI Function Calling example (ai-lib)");

    // Ensure OPENAI_API_KEY is set in env before running
    let client = AiClient::new(Provider::OpenAI)?;

    // Build a simple user message
    let user_msg = Message {
        role: Role::User,
        content: Content::Text("Please call the ascii_horse tool with size=3".to_string()),
        function_call: None,
    };

    // Define a Tool (JSON Schema for parameters)
    let ascii_horse_tool = Tool {
        name: "ascii_horse".to_string(),
        description: Some("Draws an ASCII horse of given size".to_string()),
        parameters: Some(json!({
            "type": "object",
            "properties": {
                "size": { "type": "integer", "description": "Size of the horse" }
            },
            "required": ["size"]
        })),
    };

    let mut req = ChatCompletionRequest::new("gpt-4o-mini".to_string(), vec![user_msg]);
    req.functions = Some(vec![ascii_horse_tool]);
    req.function_call = Some(FunctionCallPolicy::Auto("auto".to_string()));
    req = req.with_max_tokens(200).with_temperature(0.0);

    println!("📤 Sending request to OpenAI (model={})", req.model);

    let resp = client.chat_completion(req).await?;

    // Handle a possible function call from the model: execute locally and send the result back
    for choice in resp.choices {
        let msg = choice.message;
        if let Some(fc) = msg.function_call {
            println!("🛠️  Model invoked function: {}", fc.name);
            let args = fc.arguments.unwrap_or(serde_json::json!(null));
            println!("   arguments: {}", args);

            // Simple local tool: ascii_horse
            if fc.name == "ascii_horse" {
                // Parse size param
                let size = args.get("size").and_then(|v| v.as_i64()).unwrap_or(3) as usize;
                let horse = generate_ascii_horse(size);
                println!("⚙️ Executed ascii_horse locally, output:\n{}", horse);

                // Send follow-up message with tool result as assistant message
                let tool_msg = Message {
                    role: Role::Assistant,
                    content: Content::Text(horse.clone()),
                    function_call: None,
                };

                let mut followup =
                    ChatCompletionRequest::new("gpt-4o-mini".to_string(), vec![tool_msg]);
                followup = followup.with_max_tokens(200).with_temperature(0.0);
                let follow_resp = client.chat_completion(followup).await?;
                for fc_choice in follow_resp.choices {
                    println!(
                        "🗨️ Final model response: {}",
                        fc_choice.message.content.as_text()
                    );
                }
            }
        } else {
            println!("💬 Model message: {}", msg.content.as_text());
        }
    }

    Ok(())
}

examples/model_override_demo.rs (line 41)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

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

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

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

pub fn build_simple_request<S: Into<String>>( &self, prompt: S, ) -> ChatCompletionRequest

Convenience helper: construct a request with the provider’s default chat model. This does NOT send the request. Uses custom default model if set via AiClientBuilder, otherwise uses provider default.

Examples found in repository

examples/model_override_demo.rs (line 38)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

pub fn build_simple_request_with_model<S: Into<String>>( &self, prompt: S, model: S, ) -> ChatCompletionRequest

Convenience helper: construct a request with an explicitly specified chat model. This does NOT send the request.

Examples found in repository

examples/model_override_demo.rs (line 68)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

pub fn build_multimodal_request<S: Into<String>>( &self, prompt: S, ) -> Result<ChatCompletionRequest, AiLibError>

Convenience helper: construct a request with the provider’s default multimodal model. This does NOT send the request. Uses custom default model if set via AiClientBuilder, otherwise uses provider default.

pub fn build_multimodal_request_with_model<S: Into<String>>( &self, prompt: S, model: S, ) -> ChatCompletionRequest

Convenience helper: construct a request with an explicitly specified multimodal model. This does NOT send the request.

pub async fn quick_chat_text<P: Into<String>>( provider: Provider, prompt: P, ) -> Result<String, AiLibError>

One-shot helper: create a client for provider, send a single user prompt using the default chat model, and return plain text content (first choice).

Examples found in repository

examples/model_override_demo.rs (line 21)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

pub async fn quick_chat_text_with_model<P: Into<String>, M: Into<String>>( provider: Provider, prompt: P, model: M, ) -> Result<String, AiLibError>

One-shot helper: create a client for provider, send a single user prompt using an explicitly specified chat model, and return plain text content (first choice).

Examples found in repository

examples/model_override_demo.rs (lines 27-31)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check environment variables
    if std::env::var("GROQ_API_KEY").is_err() {
        println!("❌ Please set GROQ_API_KEY environment variable");
        println!("   Example: export GROQ_API_KEY=your_api_key_here");
        return Ok(());
    }
    
    println!("🚀 Model Override Feature Demo");
    println!("==============================");
    println!();
    
    // 1. Basic usage - maintain original simplicity
    println!("📋 1. Basic Usage - Using Default Model");
    let reply = AiClient::quick_chat_text(Provider::Groq, "Hello!").await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 2. Explicitly specify model
    println!("📋 2. Explicitly Specify Model");
    let reply = AiClient::quick_chat_text_with_model(
        Provider::Groq, 
        "Hello!", 
        "llama-3.1-8b-instant"
    ).await?;
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 3. Using ModelOptions
    println!("📋 3. Using ModelOptions");
    let client = AiClient::new(Provider::Groq)?;
    let mut request = client.build_simple_request("Hello!");
    request.model = "llama-3.1-70b-versatile".to_string();
    
    let response = client.chat_completion(request).await?;
    
    let reply = response.choices[0].message.content.as_text();
    println!("   ✅ Response: {}", reply);
    println!();
    
    // 4. AiClientBuilder custom default model
    println!("📋 4. AiClientBuilder Custom Default Model");
    let client = AiClient::builder(Provider::Groq)
        .with_default_chat_model("llama-3.1-8b-instant")
        .build()?;
    
    let request = client.build_simple_request("Hello!");
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    // 5. Explicitly specify model in build_simple_request
    println!("📋 5. Explicitly Specify Model in build_simple_request");
    let client = AiClient::new(Provider::Groq)?;
    let request = client.build_simple_request_with_model("Hello!", "llama-3.1-70b-versatile");
    
    println!("   Using model: {}", request.model);
    
    let response = client.chat_completion(request).await?;
    match &response.choices[0].message.content {
        Content::Text(text) => {
            println!("   ✅ Response: {}", text);
        }
        _ => println!("   ✅ Response: {:?}", response.choices[0].message.content),
    }
    println!();
    
    println!("🎉 Demo completed!");
    println!("==================");
    println!("✅ All model override features are working correctly");
    println!("✅ Backward compatibility is guaranteed");
    println!("✅ Flexible model specification methods are provided");
    
    Ok(())
}

pub async fn quick_multimodal_text<P: Into<String>>( provider: Provider, prompt: P, ) -> Result<String, AiLibError>

One-shot helper: create a client for provider, send a single user prompt using the default multimodal model, and return plain text content (first choice).

pub async fn quick_multimodal_text_with_model<P: Into<String>, M: Into<String>>( provider: Provider, prompt: P, model: M, ) -> Result<String, AiLibError>

One-shot helper: create a client for provider, send a single user prompt using an explicitly specified multimodal model, and return plain text content (first choice).

pub async fn quick_chat_text_with_options<P: Into<String>>( provider: Provider, prompt: P, options: ModelOptions, ) -> Result<String, AiLibError>

One-shot helper with model options: create a client for provider, send a single user prompt using specified model options, and return plain text content (first choice).