mixvideo-v2/cargos/gemini-sdk/README.md

# Gemini SDK

A simple and powerful Rust SDK for Google Gemini AI services.

## Features

- **Simple Interface**: Send text + attachments to Gemini AI
- **Agent System**: Create specialized AI agents with custom system prompts and configurations
- **Type Safety**: Strong typing with compile-time error checking
- **Easy Integration**: Minimal external dependencies

## Quick Start

Add this to your `Cargo.toml`:

```toml
[dependencies]
gemini-sdk = { path = "../gemini-sdk" }
tokio = { version = "1.0", features = ["full"] }
```

### Basic Usage

```rust
use gemini_sdk::{GeminiSDK, MessageRequest, Agent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize SDK
    let mut sdk = GeminiSDK::new()?;

    // Simple text message
    let request = MessageRequest::text_only("Hello, how are you?");
    let response = sdk.send_message(request).await?;
    println!("Response: {}", response.content);

    Ok(())
}
```

### Using Agents

```rust
use gemini_sdk::{GeminiSDK, MessageRequest, Agent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut sdk = GeminiSDK::new()?;

    // Create a specialized agent
    let agent = Agent::new(
        "code_reviewer",
        "Code Reviewer",
        "You are an expert code reviewer. Analyze code for bugs, suggest improvements, and provide constructive feedback."
    ).with_temperature(0.3)  // Lower temperature for more focused responses
     .with_max_tokens(4096);

    sdk.add_agent(agent);

    // Use the agent
    let request = MessageRequest::with_agent(
        "Please review this Python code: def fibonacci(n): return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)",
        "code_reviewer"
    );

    let response = sdk.send_message(request).await?;
    println!("Code review: {}", response.content);

    Ok(())
}
```

### With Image Attachments

```rust
use gemini_sdk::{GeminiSDK, MessageRequest, Attachment};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut sdk = GeminiSDK::new()?;

    let request = MessageRequest::with_attachments(
        "What do you see in this image?",
        vec![Attachment::new("./image.jpg")]
    );

    let response = sdk.send_message(request).await?;
    println!("Image analysis: {}", response.content);

    Ok(())
}
```

## Configuration

The SDK uses environment variables for configuration, with sensible defaults:

- `GEMINI_BASE_URL`: API base URL (default: Bowong AI endpoint)
- `GEMINI_BEARER_TOKEN`: Bearer token for authentication (default: "bowong7777")
- `GEMINI_MODEL_NAME`: Model to use (default: "gemini-2.5-flash")
- `GEMINI_TEMPERATURE`: Default temperature (default: 0.7)
- `GEMINI_MAX_TOKENS`: Default max tokens (default: 64000)

You can also create a custom configuration:

```rust
use gemini_sdk::{GeminiSDK, GeminiConfig};

let config = GeminiConfig {
    base_url: "https://your-api-endpoint.com".to_string(),
    bearer_token: "your-token".to_string(),
    model_name: "gemini-2.5-flash".to_string(),
    temperature: 0.8,
    max_tokens: 32000,
    ..Default::default()
};

let mut sdk = GeminiSDK::with_config(config)?;
```

## Agent System

Agents are specialized AI assistants with their own system prompts and configurations:

```rust
// Create an agent
let agent = Agent::new("agent_id", "Agent Name", "System prompt here")
    .with_temperature(0.5)    // 0.0 = focused, 2.0 = creative
    .with_max_tokens(8192);   // Maximum response length

// Add to SDK
sdk.add_agent(agent);

// Use the agent
let request = MessageRequest::with_agent("Your message", "agent_id");
let response = sdk.send_message(request).await?;
```

### Agent Management

```rust
// List all agents
let agents = sdk.list_agents();
for agent in agents {
    println!("Agent: {} ({})", agent.name, agent.id);
}

// Get specific agent
if let Some(agent) = sdk.get_agent("agent_id") {
    println!("Found agent: {}", agent.name);
}

// Remove agent
sdk.remove_agent("agent_id");
```

## Supported File Types

- **Images**: JPEG, PNG, GIF, WebP, BMP
- **Videos**: MP4, AVI, MOV, WebM (uploaded to cloud storage)
- **Text**: Plain text, Markdown, HTML, JSON

## Error Handling

The SDK provides detailed error types:

```rust
use gemini_sdk::SDKError;

match sdk.send_message(request).await {
    Ok(response) => println!("Success: {}", response.content),
    Err(SDKError::AgentNotFound(id)) => println!("Agent {} not found", id),
    Err(SDKError::Attachment(msg)) => println!("Attachment error: {}", msg),
    Err(SDKError::Api { status, message }) => println!("API error {}: {}", status, message),
    Err(e) => println!("Other error: {}", e),
}
```

## Examples

Run the examples to see the SDK in action:

```bash
cargo run --example basic_usage
```

## License

MIT License