grok_api/
lib.rs

1//! # Grok API Client
2//!
3//! A Rust client library for interacting with the Grok AI API (xAI).
4//!
5//! This library provides a simple and robust interface to the Grok AI models,
6//! with built-in retry logic, error handling, and support for challenging
7//! network conditions (like Starlink satellite connections).
8//!
9//! ## Features
10//!
11//! - **Simple API**: Easy-to-use async interface
12//! - **Robust Error Handling**: Comprehensive error types with detailed messages
13//! - **Automatic Retries**: Built-in retry logic for transient network failures
14//! - **Starlink Optimized**: Special handling for satellite network drops
15//! - **Rate Limiting**: Client-side rate limit tracking (optional)
16//! - **Tool/Function Calling**: Support for function calling and tools
17//!
18//! ## Quick Start
19//!
20//! ```no_run
21//! use grok_api::{GrokClient, Result};
22//!
23//! #[tokio::main]
24//! async fn main() -> Result<()> {
25//!     // Create a client with your API key
26//!     let client = GrokClient::new("your-api-key")?;
27//!
28//!     // Send a simple chat message
29//!     let response = client
30//!         .chat("What is Rust?", None)
31//!         .await?;
32//!
33//!     println!("Response: {}", response);
34//!     Ok(())
35//! }
36//! ```
37//!
38//! ## Advanced Usage
39//!
40//! ```no_run
41//! use grok_api::{GrokClient, ChatMessage, Result};
42//! use serde_json::json;
43//!
44//! #[tokio::main]
45//! async fn main() -> Result<()> {
46//!     let client = GrokClient::builder()
47//!         .api_key("your-api-key")
48//!         .timeout_secs(60)
49//!         .max_retries(5)
50//!         .build()?;
51//!
52//!     // Build a conversation
53//!     let messages = vec![
54//!         ChatMessage::system("You are a helpful Rust programming assistant."),
55//!         ChatMessage::user("How do I create a Vec in Rust?"),
56//!     ];
57//!
58//!     let response = client
59//!         .chat_with_history(&messages)
60//!         .temperature(0.7)
61//!         .max_tokens(1000)
62//!         .model("grok-3")
63//!         .send()
64//!         .await?;
65//!
66//!     println!("Response: {}", response.content().unwrap_or(""));
67//!     Ok(())
68//! }
69//! ```
70
71mod client;
72mod error;
73mod models;
74mod retry;
75mod types;
76
77pub use client::{GrokClient, GrokClientBuilder};
78pub use error::{Error, Result};
79pub use models::{
80    ChatMessage, ChatRequest, ChatResponse, Choice, ContentPart, FunctionCall, ImageUrl, Message,
81    MessageContent, Model, ToolCall, Usage, VideoUrl,
82};
83pub use retry::RetryConfig;
84pub use types::{Role, StopReason};
85
86/// Re-export commonly used types
87pub mod prelude {
88    pub use crate::client::{GrokClient, GrokClientBuilder};
89    pub use crate::error::{Error, Result};
90    pub use crate::models::{ChatMessage, ChatResponse};
91    pub use crate::types::Role;
92}
93
94// Version information
95/// The version of this crate
96pub const VERSION: &str = env!("CARGO_PKG_VERSION");
97
98/// The default API base URL for Grok (xAI)
99pub const DEFAULT_API_BASE_URL: &str = "https://api.x.ai";
100
101/// The default model to use if none is specified
102pub const DEFAULT_MODEL: &str = "grok-3";
103
104/// Default timeout in seconds
105pub const DEFAULT_TIMEOUT_SECS: u64 = 30;
106
107/// Default maximum number of retries
108pub const DEFAULT_MAX_RETRIES: u32 = 3;
grok_api/lib.rs

grok_api/
lib.rs
