genai-rs

A Rust client library for Google's Generative AI (Gemini) API using the Interactions API.

Quick Start

use genai_rs::Client;

#[tokio::main]
async fn main() -> Result<(), genai_rs::GenaiError> {
    let client = Client::new(std::env::var("GEMINI_API_KEY").unwrap());

    let response = client
        .interaction()
        .with_model("gemini-3-flash-preview")
        .with_text("Explain Rust's ownership model in one sentence.")
        .create()
        .await?;

    println!("{}", response.as_text().unwrap_or_default());
    Ok(())
}

Features

Core Capabilities

Built-in Tools

Multimodal I/O

Installation

[dependencies]
genai-rs = "0.7"
tokio = { version = "1.0", features = ["full"] }

# Optional
genai-rs-macros = "0.7"  # For #[tool] macro
futures-util = "0.3"     # For streaming

Requirements: Rust 1.88+ (edition 2024), Gemini API key

Examples

Runnable examples covering all features:

export GEMINI_API_KEY=your-key
cargo run --example simple_interaction

Quick Reference:

See Examples Index for the complete categorized list.

Usage Highlights

Streaming

use futures_util::StreamExt;
use genai_rs::StreamChunk;

let mut stream = client.interaction()
    .with_text("Write a haiku about Rust.")
    .create_stream();

while let Some(Ok(event)) = stream.next().await {
    if let StreamChunk::Delta(delta) = &event.chunk {
        if let Some(text) = delta.as_text() {
            print!("{}", text);
        }
    }
}

Function Calling with #[tool]

use genai_rs_macros::tool;

#[tool(location(description = "City name, e.g. Tokyo"))]
fn get_weather(location: String) -> String {
    format!(r#"{{"temp": 72, "conditions": "sunny"}}"#)
}

let result = client.interaction()
    .with_text("What's the weather in Tokyo?")
    .add_function(GetWeatherCallable.declaration())
    .create_with_auto_functions()
    .await?;

Stateful Conversations

// First turn (enable storage for multi-turn)
let r1 = client.interaction()
    .with_system_instruction("You are a helpful assistant.")
    .with_text("My name is Alice.")
    .with_store_enabled()
    .create().await?;

// Continue conversation (r1.id is Option<String>)
let r2 = client.interaction()
    .with_previous_interaction(r1.id.as_ref().expect("stored interactions have IDs"))
    .with_text("What's my name?")  // Remembers: Alice
    .create().await?;

Thinking Mode

use genai_rs::ThinkingLevel;

let response = client.interaction()
    .with_thinking_level(ThinkingLevel::High)
    .with_text("What's 15% of 847?")
    .create().await?;

// Check if model used reasoning (thoughts contain cryptographic signatures)
if response.has_thoughts() {
    println!("Model used {} thought blocks", response.thought_signatures().count());
}

Build & Execute (for Retries)

use genai_rs::InteractionRequest;

// Build request without executing (Clone + Serialize)
let request: InteractionRequest = client.interaction()
    .with_model("gemini-3-flash-preview")
    .with_text("Hello!")
    .build()?;

// Execute separately - enables retry loops
let response = client.execute(request.clone()).await?;

// On error, check if retryable: error.is_retryable()

See retry_with_backoff for a complete retry example using the backon crate.

Documentation

Guides

Reference

External Resources

Debugging

# Wire-level request/response logging
LOUD_WIRE=1 cargo run --example simple_interaction

# Library debug logs
RUST_LOG=genai_rs=debug cargo run --example simple_interaction

See Logging Strategy for details.

Forward Compatibility

This library follows the Evergreen philosophy: unknown API types deserialize into Unknown variants instead of failing. Always include wildcard arms:

match content {
    Content::Text { text } => println!("{}", text.unwrap_or_default()),
    _ => {}  // Handles future variants gracefully
}

Testing

make test      # Unit tests (uses cargo-nextest)
make test-all  # Full integration suite (requires GEMINI_API_KEY)

Project Structure

genai-rs/           # Main crate: Client, InteractionBuilder, types
genai-rs-macros/    # Procedural macro for #[tool]
docs/               # Comprehensive guides
examples/           # Runnable examples

Contributing

Contributions welcome! Please read:

• CLAUDE.md - Development guidelines and architecture
• CHANGELOG.md - Version history and migration guides
• SECURITY.md - Security policy and reporting

Troubleshooting

Common issues and solutions are documented in TROUBLESHOOTING.md.

Quick fixes:

• "API key not valid" - Check GEMINI_API_KEY is set
• "Model not found" - Use gemini-3-flash-preview
• Functions not executing - Use create_with_auto_functions()

License

MIT