genai_rs/lib.rs
1//! # genai-rs
2//!
3//! A Rust client library for Google's Generative AI (Gemini) API using the Interactions API.
4//!
5//! ## Quick Start
6//!
7//! ```no_run
8//! use genai_rs::Client;
9//!
10//! #[tokio::main]
11//! async fn main() -> Result<(), genai_rs::GenaiError> {
12//! let client = Client::new(
13//! std::env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY not set")
14//! );
15//!
16//! let response = client
17//! .interaction()
18//! .with_model("gemini-3-flash-preview")
19//! .with_text("Hello, Gemini!")
20//! .create()
21//! .await?;
22//!
23//! println!("{}", response.as_text().unwrap_or("No response"));
24//! Ok(())
25//! }
26//! ```
27//!
28//! ## Features
29//!
30//! - **Fluent Builder API**: Chain methods for readable request construction
31//! - **Streaming**: Real-time response streaming with `create_stream()`
32//! - **Function Calling**: Automatic function discovery and execution via macros
33//! - **Built-in Tools**: Google Search, Code Execution, URL Context
34//! - **Multimodal**: Images, audio, video, and document inputs
35//! - **Thinking Mode**: Access model reasoning with configurable levels
36//!
37//! ## API Stability & Forward Compatibility
38//!
39//! This library is designed for forward compatibility with evolving APIs:
40//!
41//! - **`#[non_exhaustive]` enums**: Match statements require wildcard arms (`_ => ...`)
42//! - **`Unknown` variants**: Unrecognized API types are captured, not rejected
43//! - **Graceful degradation**: New API features won't break existing code
44//!
45//! When Google adds new features, your code continues to work. Unknown content types
46//! and tools are preserved for inspection via helper methods like `has_unknown()`.
47//!
48//! ## Module Organization
49//!
50//! - [`Client`]: Main entry point for API interactions
51//! - [`InteractionBuilder`]: Fluent builder for configuring requests
52//! - [`interactions_api`]: Helper functions for constructing content
53//! - [`function_calling`]: Function registration and execution
54
55// =============================================================================
56// Internal HTTP Layer (pub(crate))
57// =============================================================================
58pub(crate) mod http;
59
60// =============================================================================
61// Core Type Modules
62// =============================================================================
63
64// Error types
65pub mod errors;
66pub use errors::GenaiError;
67
68// Content types (Content and related)
69pub mod content;
70pub use content::{
71 Annotation, CodeExecutionLanguage, Content, FileSearchResultItem, GoogleSearchResultItem,
72 Resolution, UrlContextResultItem,
73};
74
75// Request types (includes agent configuration)
76pub mod request;
77pub use request::{
78 AgentConfig, DeepResearchConfig, DynamicConfig, GenerationConfig, InteractionInput,
79 InteractionRequest, Role, SpeechConfig, ThinkingLevel, ThinkingSummaries, Turn, TurnContent,
80};
81
82// Response types
83pub mod response;
84pub use response::{
85 AudioInfo, CodeExecutionCallInfo, CodeExecutionResultInfo, ContentSummary, FunctionCallInfo,
86 FunctionResultInfo, GroundingChunk, GroundingMetadata, ImageInfo, InteractionResponse,
87 InteractionStatus, ModalityTokens, OwnedFunctionCallInfo, UrlContextMetadata,
88 UrlContextResultInfo, UrlMetadataEntry, UrlRetrievalStatus, UsageMetadata, WebSource,
89};
90
91// Tool types (function declarations, built-in tools)
92pub mod tools;
93pub use tools::{
94 FunctionCallingMode, FunctionDeclaration, FunctionDeclarationBuilder, FunctionParameters, Tool,
95};
96
97// Wire streaming types (from API)
98pub mod wire_streaming;
99pub use wire_streaming::{InteractionStreamEvent, StreamChunk, StreamEvent};
100
101// Files API types
102pub use http::files::{
103 DEFAULT_CHUNK_SIZE, FileError, FileMetadata, FileState, ListFilesResponse, ResumableUpload,
104 VideoMetadata,
105};
106
107// =============================================================================
108// Client and Builder
109// =============================================================================
110
111pub mod client;
112pub use client::{Client, ClientBuilder};
113
114pub mod request_builder;
115pub use request_builder::{ConversationBuilder, InteractionBuilder};
116
117// =============================================================================
118// Function Calling
119// =============================================================================
120
121pub mod function_calling;
122pub use function_calling::{CallableFunction, FunctionError, ToolService};
123
124// =============================================================================
125// Streaming Types for Auto Function Calling
126// =============================================================================
127
128pub mod streaming;
129pub use streaming::{
130 AutoFunctionResult, AutoFunctionResultAccumulator, AutoFunctionStreamChunk,
131 AutoFunctionStreamEvent, FunctionExecutionResult, PendingFunctionCall,
132};
133
134// =============================================================================
135// Content Constructor Functions
136// =============================================================================
137//
138// ## Export Strategy
139//
140// Model output constructors for testing and response simulation.
141// Use `Content::*()` constructors for user input content.
142pub mod interactions_api;
143
144// =============================================================================
145// Multimodal File Loading Utilities
146// =============================================================================
147
148pub mod multimodal;
149pub use multimodal::{
150 audio_from_file, audio_from_file_with_mime, detect_mime_type, document_from_file,
151 document_from_file_with_mime, image_from_file, image_from_file_with_mime, video_from_file,
152 video_from_file_with_mime,
153};
154
155// =============================================================================
156// Test Modules
157// =============================================================================
158
159#[cfg(test)]
160mod content_tests;
161#[cfg(test)]
162mod proptest_tests;
163#[cfg(test)]
164mod request_tests;
165#[cfg(test)]
166mod response_tests;
167#[cfg(test)]
168mod streaming_tests;
169
170// =============================================================================
171// Documentation Tests
172// =============================================================================
173//
174// These include markdown documentation files for doctest verification.
175// Code blocks in markdown use annotations:
176// - `rust,ignore` - Not compiled (incomplete snippets)
177// - `rust,no_run` - Compiled but not executed (needs API key)
178// - `rust,compile_fail` - Should fail compilation
179//
180// Run with: cargo test --doc
181
182#[cfg(doctest)]
183mod doc_tests {
184 use doc_comment::doc_comment;
185
186 // Root-level documentation
187 doc_comment!(include_str!("../README.md"));
188 doc_comment!(include_str!("../TROUBLESHOOTING.md"));
189
190 // Detailed guides in docs/
191 doc_comment!(include_str!("../docs/AGENTS_AND_BACKGROUND.md"));
192 doc_comment!(include_str!("../docs/BUILT_IN_TOOLS.md"));
193 doc_comment!(include_str!("../docs/CONFIGURATION.md"));
194 doc_comment!(include_str!("../docs/CONVERSATION_PATTERNS.md"));
195 doc_comment!(include_str!("../docs/ENUM_WIRE_FORMATS.md"));
196 doc_comment!(include_str!("../docs/ERROR_HANDLING.md"));
197 doc_comment!(include_str!("../docs/EXAMPLES_INDEX.md"));
198 doc_comment!(include_str!("../docs/FUNCTION_CALLING.md"));
199 doc_comment!(include_str!("../docs/LOGGING_STRATEGY.md"));
200 doc_comment!(include_str!("../docs/MULTI_TURN_FUNCTION_CALLING.md"));
201 doc_comment!(include_str!("../docs/MULTIMODAL.md"));
202 doc_comment!(include_str!("../docs/OUTPUT_MODALITIES.md"));
203 doc_comment!(include_str!("../docs/RELIABILITY_PATTERNS.md"));
204 doc_comment!(include_str!("../docs/STREAMING_API.md"));
205 doc_comment!(include_str!("../docs/TESTING.md"));
206 doc_comment!(include_str!("../docs/THINKING_MODE.md"));
207}