Module handle 

The Batch module for managing batch operations.

This module provides the BatchHandle struct, which is a handle to a long-running batch operation on the Gemini API. It allows for checking the status, canceling, and deleting the operation.

The status of a batch operation is represented by the BatchStatus enum, which can be retrieved using the BatchHandle::status() method. When a batch completes successfully, it transitions to the BatchStatus::Succeeded state, which contains a vector of BatchGenerationResponseItem.

Batch Results

The BatchGenerationResponseItem enum represents the outcome of a single request within the batch:

• Success: Contains the generated GenerationResponse and the original request key.
• Error: Contains an IndividualRequestError and the original request key.

Results can be delivered in two ways, depending on the size of the batch job:

1. Inlined Responses: For smaller jobs, the results are included directly in the batch operation’s metadata.
2. Response File: For larger jobs (typically >20MB), the results are written to a file, and the batch metadata will contain a reference to this file. The SDK handles the downloading and parsing of this file automatically when you call status() on a completed batch.

The results are automatically sorted by their original request key (as a number) to ensure a consistent and predictable order.

For more information, see the official Google AI documentation:

• Batch Mode Guide
• Batch API Reference

Design Note: Resource Management in Batch Operations

The Batch API methods that consume the BatchHandle struct (cancel, delete) return std::result::Result<T, (Self, crate::Error)> instead of the crate’s Result<T>. This design follows patterns used in channel libraries (e.g., std::sync::mpsc::Receiver) and provides two key benefits:

1. Resource Safety: Once a BatchHandle is consumed by an operation, it cannot be used again, preventing invalid operations on deleted or canceled batches.

2. Error Recovery: If an operation fails due to transient network issues, both the BatchHandle and error information are returned, allowing callers to retry the operation.

Example usage:

use gemini_rust::{Gemini, Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;
    let request = client.generate_content().with_user_message("Why is the sky blue?").build();
    let batch = client.batch_generate_content().with_request(request).execute().await?;

    match batch.delete().await {
        Ok(()) => println!("Batch deleted successfully!"),
        Err((batch, error)) => {
            println!("Failed to delete batch: {}", error);
            // Can retry: batch.delete().await
        }
    }
    Ok(())
}

Structs

BatchGenerationResponseItem

BatchHandle

Represents a long-running batch operation, providing methods to manage its lifecycle.

Enums

BatchStatus

Represents the overall status of a batch operation.

Error