Enum Content 

pub enum Content {
    Text(String),
    Json(Value),
    Image {
        url: Option<String>,
        mime: Option<String>,
        name: Option<String>,
    },
    Audio {
        url: Option<String>,
        mime: Option<String>,
    },
}

Message content — moved to an enum to support multimodal and structured content

Variants

Text(String)

Json(Value)

Generic JSON content for structured payloads (e.g. function call args)

Image

Reference to an image (url) or metadata; adapters may upload or inline as needed

Fields

url: Option<String>

mime: Option<String>

name: Option<String>

Audio

Reference to audio content

Fields

url: Option<String>

mime: Option<String>

Implementations

impl Content

pub fn as_text(&self) -> String

Return a best-effort textual representation for legacy code paths

Examples found in repository

examples/multimodal_example.rs (line 25)

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/basic_usage.rs (line 43)

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/ascii_horse.rs (line 87)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example: Function Calling with a local tool 'ascii_horse'");

    // Define the tool
    let tool = Tool {
        name: "ascii_horse".to_string(),
        description: Some("Return an ASCII art horse. Accepts size: 'small'|'large'.".to_string()),
        parameters: Some(json!({
            "type": "object",
            "properties": {
                "size": { "type": "string", "enum": ["small", "large"] }
            },
            "required": ["size"]
        })),
    };

    // Build a request that offers the tool to the model
    let mut request = ChatCompletionRequest::new(
        "example-model".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::new_text("Please draw an ASCII horse for me."),
            function_call: None,
        }],
    );
    request.functions = Some(vec![tool.clone()]);
    request.function_call = Some(FunctionCallPolicy::Auto("ascii_horse".to_string()));

    println!(
        "Prepared request with functions: {}",
        serde_json::to_string_pretty(&request.functions).unwrap()
    );

    // Simulate model returning a function call (in a real run this would come from the provider)
    let simulated_call = FunctionCall {
        name: "ascii_horse".to_string(),
        arguments: Some(json!({ "size": "small" })),
    };
    println!(
        "Model requested function call: {}",
        serde_json::to_string_pretty(&simulated_call).unwrap()
    );

    // Execute the local tool
    let size_arg = simulated_call
        .arguments
        .as_ref()
        .and_then(|v| v.get("size"))
        .and_then(|s| s.as_str())
        .unwrap_or("small");

    let tool_output = ascii_horse(size_arg);

    // Convert tool output to a Message and append to conversation
    let tool_message = Message {
        role: Role::Assistant,
        content: Content::new_text(tool_output.clone()),
        function_call: None,
    };

    // In a normal flow you'd send the updated messages back to the model to continue the conversation.
    println!(
        "Tool output (appended as assistant message):\n\n{}\n",
        tool_message.content.as_text()
    );

    Ok(())
}

examples/proxy_example.rs (line 41)

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/function_call_openai.rs (line 71)

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

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

Additional examples can be found in:

• examples/test_streaming.rs
• examples/batch_processing.rs

pub fn new_text<S: Into<String>>(s: S) -> Self

Convenience constructor for text content

Examples found in repository

examples/ascii_horse.rs (line 45)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Example: Function Calling with a local tool 'ascii_horse'");

    // Define the tool
    let tool = Tool {
        name: "ascii_horse".to_string(),
        description: Some("Return an ASCII art horse. Accepts size: 'small'|'large'.".to_string()),
        parameters: Some(json!({
            "type": "object",
            "properties": {
                "size": { "type": "string", "enum": ["small", "large"] }
            },
            "required": ["size"]
        })),
    };

    // Build a request that offers the tool to the model
    let mut request = ChatCompletionRequest::new(
        "example-model".to_string(),
        vec![Message {
            role: Role::User,
            content: Content::new_text("Please draw an ASCII horse for me."),
            function_call: None,
        }],
    );
    request.functions = Some(vec![tool.clone()]);
    request.function_call = Some(FunctionCallPolicy::Auto("ascii_horse".to_string()));

    println!(
        "Prepared request with functions: {}",
        serde_json::to_string_pretty(&request.functions).unwrap()
    );

    // Simulate model returning a function call (in a real run this would come from the provider)
    let simulated_call = FunctionCall {
        name: "ascii_horse".to_string(),
        arguments: Some(json!({ "size": "small" })),
    };
    println!(
        "Model requested function call: {}",
        serde_json::to_string_pretty(&simulated_call).unwrap()
    );

    // Execute the local tool
    let size_arg = simulated_call
        .arguments
        .as_ref()
        .and_then(|v| v.get("size"))
        .and_then(|s| s.as_str())
        .unwrap_or("small");

    let tool_output = ascii_horse(size_arg);

    // Convert tool output to a Message and append to conversation
    let tool_message = Message {
        role: Role::Assistant,
        content: Content::new_text(tool_output.clone()),
        function_call: None,
    };

    // In a normal flow you'd send the updated messages back to the model to continue the conversation.
    println!(
        "Tool output (appended as assistant message):\n\n{}\n",
        tool_message.content.as_text()
    );

    Ok(())
}

pub fn new_json(v: JsonValue) -> Self

Convenience constructor for JSON content

pub fn new_image( url: Option<String>, mime: Option<String>, name: Option<String>, ) -> Self

Convenience constructor for image content

Examples found in repository

examples/multimodal_example.rs (lines 14-18)

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

pub fn new_audio(url: Option<String>, mime: Option<String>) -> Self

Convenience constructor for audio content

Trait Implementations

impl Clone for Content

fn clone(&self) -> Content

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Content

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Content

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Content

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.