Struct Gemini 

pub struct Gemini { /* private fields */ }

The main client for interacting with the Gemini API.

Use Gemini::new or Gemini::new_with_timeout to create an instance. You can configure various aspects of the request like model, system instructions, generation config, safety settings, and tools using the provided builder-like methods.

Implementations

impl Gemini

pub fn new( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, ) -> Self

Creates a new Gemini client.

Arguments

• api_key - Your Gemini API key. Get one from Google AI studio.
• model - The model variation to use (e.g., “gemini-2.5-flash”). See model variations.
• sys_prompt - Optional system instructions. See system instructions.

Examples found in repository

examples/multimodal.rs (line 11)

async fn raw_multimodal() {
    let mut session = Session::new(6);
    let api_key = std::env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    session.ask("Where is there in this pdf");
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let response = ai.ask(&mut session).await.unwrap();
    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}
#[tokio::main]
async fn main() {
    let mut session = Session::new(6);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Multimodal (Images/Files) Example ---");

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)";
    println!("Processing: {}", content);

    let parts = MarkdownToParts::new(content, |_| mime::IMAGE_PNG)
        .await
        .process();

    let response = ai.ask(session.ask_parts(parts)).await.unwrap();

    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}

examples/structured_output.rs (line 27)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", response.get_chat().get_text_no_think(""));
    }
}

examples/thinking.rs (line 12)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // Note: Thinking mode requires a supported model like gemini-2.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

examples/basic_chat.rs (line 13)

async fn main() {
    // 1. Initialize the session with a history limit (e.g., 6 messages)
    let mut session = Session::new(6);

    // 2. Create the Gemini client
    // Get your API key from https://aistudio.google.com/app/apikey
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Basic Chat Example ---");

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // 4. Print the reply
    // get_text_no_think("") extracts text and ignores "thought" parts (if any)
    let reply = response.get_chat().get_text_no_think("");
    println!("\nGemini: {}", reply);

    // 5. The session now contains the interaction
    println!("\nMessages in history: {}", session.get_history_length());
}

examples/streaming.rs (line 11)

async fn main() {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Streaming Example ---");
    let prompt = "Write a short poem about crab-like robots on Mars.";
    println!("User: {}\n", prompt);
    print!("Gemini: ");
    stdout().flush().unwrap();

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session.ask(prompt).clone()).await.unwrap();

    while let Some(chunk_result) = response_stream.next().await {
        match chunk_result {
            Ok(response) => {
                // Get the text from the current chunk
                let text = response.get_chat().get_text_no_think("");
                print!("{}", text);
                stdout().flush().unwrap();
            }
            Err(e) => {
                eprintln!("\nError receiving chunk: {:?}", e);
                break;
            }
        }
    }

    println!("\n\n--- Stream Complete ---");
    // Note: The session passed to ask_as_stream is updated as you exhaust the stream.
}

examples/function_calling.rs (line 35)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // 1. Initialize Gemini and register tools
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None)
        .set_tools(vec![Tool::FunctionDeclarations(vec![
            add_numbers::gemini_schema(),
            get_temperature::gemini_schema(),
        ])]);

    println!("--- Function Calling Example ---");
    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");
            
            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);
            
            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

Additional examples can be found in:

• examples/context_caching.rs

pub fn new_with_timeout( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, api_timeout: Duration, ) -> Self

Creates a new Gemini client with a custom API timeout.

Arguments

• api_key - Your Gemini API key.
• model - The model variation to use.
• sys_prompt - Optional system instructions.
• api_timeout - Custom duration for request timeouts.

pub fn set_generation_config(&mut self) -> &mut Value

Returns a mutable reference to the generation configuration. If not already set, initializes it to an empty object.

See Gemini docs for schema details.

pub fn set_tool_config(self, config: ToolConfig) -> Self

pub fn set_thinking_config(self, config: ThinkingConfig) -> Self

Examples found in repository

examples/thinking.rs (line 13)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // Note: Thinking mode requires a supported model like gemini-2.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

pub fn set_model(self, model: impl Into<String>) -> Self

pub fn set_sys_prompt(self, sys_prompt: Option<SystemInstruction>) -> Self

pub fn set_safety_settings(self, settings: Option<Vec<SafetySetting>>) -> Self

pub fn set_api_key(self, api_key: impl Into<String>) -> Self

pub fn set_json_mode(self, schema: Value) -> Self

Sets the response format to JSON mode with a specific schema.

To use a Rust struct as a schema, decorate it with #[gemini_schema] and pass StructName::gemini_schema().

Arguments

• schema - The JSON schema for the response. See Gemini Schema docs.

Examples found in repository

examples/structured_output.rs (line 32)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", response.get_chat().get_text_no_think(""));
    }
}

pub fn remove_json_mode(self) -> Self

pub fn set_tools(self, tools: Vec<Tool>) -> Self

Sets the tools (functions) available to the model.

Examples found in repository

examples/function_calling.rs (lines 36-39)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // 1. Initialize Gemini and register tools
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None)
        .set_tools(vec![Tool::FunctionDeclarations(vec![
            add_numbers::gemini_schema(),
            get_temperature::gemini_schema(),
        ])]);

    println!("--- Function Calling Example ---");
    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");
            
            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);
            
            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

pub fn remove_tools(self) -> Self

Removes all tools.

pub fn set_cached_content(self, name: impl Into<String>) -> Self

Examples found in repository

examples/context_caching.rs (line 42)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    session.ask("What is there in this pdf".repeat(200)); //Faking big context for example
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(
            session
                .get_history()
                .into_iter()
                .map(|e| e.to_owned())
                .collect(),
        )
        .ttl(Duration::from_secs(300))
        .build().unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub fn remove_cached_content(self) -> Self

pub async fn create_cache( &self, cached_content: &CachedContent, ) -> Result<CachedContent, GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 30)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    session.ask("What is there in this pdf".repeat(200)); //Faking big context for example
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(
            session
                .get_history()
                .into_iter()
                .map(|e| e.to_owned())
                .collect(),
        )
        .ttl(Duration::from_secs(300))
        .build().unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn list_caches( &self, ) -> Result<CachedContentList, GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 53)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    session.ask("What is there in this pdf".repeat(200)); //Faking big context for example
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(
            session
                .get_history()
                .into_iter()
                .map(|e| e.to_owned())
                .collect(),
        )
        .ttl(Duration::from_secs(300))
        .build().unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn get_cache( &self, name: &str, ) -> Result<CachedContent, GeminiResponseError>

pub async fn update_cache( &self, name: &str, update: &CachedContentUpdate, ) -> Result<CachedContent, GeminiResponseError>

pub async fn delete_cache(&self, name: &str) -> Result<(), GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 68)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    session.ask("What is there in this pdf".repeat(200)); //Faking big context for example
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(
            session
                .get_history()
                .into_iter()
                .map(|e| e.to_owned())
                .collect(),
        )
        .ttl(Duration::from_secs(300))
        .build().unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn ask( &self, session: &mut Session, ) -> Result<GeminiResponse, GeminiResponseError>

Sends a prompt to the model and waits for the full response.

Updates the session history with the model’s reply.

Errors

Returns GeminiResponseError::NothingToRespond if the last message in history is from the model.

Examples found in repository

examples/multimodal.rs (line 16)

async fn raw_multimodal() {
    let mut session = Session::new(6);
    let api_key = std::env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    session.ask("Where is there in this pdf");
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let response = ai.ask(&mut session).await.unwrap();
    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}
#[tokio::main]
async fn main() {
    let mut session = Session::new(6);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Multimodal (Images/Files) Example ---");

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)";
    println!("Processing: {}", content);

    let parts = MarkdownToParts::new(content, |_| mime::IMAGE_PNG)
        .await
        .process();

    let response = ai.ask(session.ask_parts(parts)).await.unwrap();

    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}

examples/structured_output.rs (line 37)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", response.get_chat().get_text_no_think(""));
    }
}

examples/thinking.rs (line 19)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // Note: Thinking mode requires a supported model like gemini-2.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

examples/basic_chat.rs (line 21)

async fn main() {
    // 1. Initialize the session with a history limit (e.g., 6 messages)
    let mut session = Session::new(6);

    // 2. Create the Gemini client
    // Get your API key from https://aistudio.google.com/app/apikey
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Basic Chat Example ---");

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // 4. Print the reply
    // get_text_no_think("") extracts text and ignores "thought" parts (if any)
    let reply = response.get_chat().get_text_no_think("");
    println!("\nGemini: {}", reply);

    // 5. The session now contains the interaction
    println!("\nMessages in history: {}", session.get_history_length());
}

examples/function_calling.rs (line 46)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    
    // 1. Initialize Gemini and register tools
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None)
        .set_tools(vec![Tool::FunctionDeclarations(vec![
            add_numbers::gemini_schema(),
            get_temperature::gemini_schema(),
        ])]);

    println!("--- Function Calling Example ---");
    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");
            
            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);
            
            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

examples/context_caching.rs (line 44)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    session.ask("What is there in this pdf".repeat(200)); //Faking big context for example
    session.ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(
            session
                .get_history()
                .into_iter()
                .map(|e| e.to_owned())
                .collect(),
        )
        .ttl(Duration::from_secs(300))
        .build().unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn ask_as_stream_with_extractor<F, StreamType>( &self, session: Session, data_extractor: F, ) -> Result<ResponseStream<F, StreamType>, (Session, GeminiResponseError)>

where F: FnMut(&Session, GeminiResponse) -> StreamType,

Warning

You must read the response stream to get reply stored context in session. data_extractor is used to extract data that you get as a stream of futures.

Example

use futures::StreamExt
let mut response_stream = gemini.ask_as_stream_with_extractor(session,
     |session, _gemini_response| session.get_last_chat().unwrap().get_text_no_think("\n"))
    .await.unwrap(); // Use _gemini_response.get_text("") to just get the text received in every chunk
while let Some(response) = response_stream.next().await {
    println!("{}", response.unwrap());
}

pub async fn ask_as_stream( &self, session: Session, ) -> Result<GeminiResponseStream, (Session, GeminiResponseError)>

Sends a prompt to the model and returns a stream of responses.

Warning

You must exhaust the response stream to ensure the session history is correctly updated.

Example

use futures::StreamExt;
let mut response_stream = gemini.ask_as_stream(session).await.unwrap();

while let Some(response) = response_stream.next().await {
    if let Ok(response) = response {
        println!("{}", response.get_chat().get_text_no_think("\n"));
    }
}

Examples found in repository

examples/streaming.rs (line 20)

async fn main() {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Streaming Example ---");
    let prompt = "Write a short poem about crab-like robots on Mars.";
    println!("User: {}\n", prompt);
    print!("Gemini: ");
    stdout().flush().unwrap();

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session.ask(prompt).clone()).await.unwrap();

    while let Some(chunk_result) = response_stream.next().await {
        match chunk_result {
            Ok(response) => {
                // Get the text from the current chunk
                let text = response.get_chat().get_text_no_think("");
                print!("{}", text);
                stdout().flush().unwrap();
            }
            Err(e) => {
                eprintln!("\nError receiving chunk: {:?}", e);
                break;
            }
        }
    }

    println!("\n\n--- Stream Complete ---");
    // Note: The session passed to ask_as_stream is updated as you exhaust the stream.
}

Trait Implementations

impl Clone for Gemini

fn clone(&self) -> Gemini

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Gemini

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

Formats the value using the given formatter.

impl Default for Gemini

fn default() -> Gemini

Returns the “default value” for a type.