grok_api 0.1.7

Rust client library for the Grok AI API (xAI)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! # Grok API Client
//!
//! A Rust client library for interacting with the Grok AI API (xAI).
//!
//! This library provides a simple and robust interface to the Grok AI models,
//! with built-in retry logic, error handling, and support for challenging
//! network conditions (like Starlink satellite connections).
//!
//! ## Features
//!
//! - **Simple API**: Easy-to-use async interface
//! - **Robust Error Handling**: Comprehensive error types with detailed messages
//! - **Automatic Retries**: Built-in retry logic for transient network failures
//! - **Starlink Optimized**: Special handling for satellite network drops
//! - **Rate Limiting**: Client-side rate limit tracking (optional)
//! - **Tool/Function Calling**: Support for function calling and tools
//!
//! ## Quick Start
//!
//! ```no_run
//! use grok_api::{GrokClient, Result};
//!
//! #[tokio::main]
//! async fn main() -> Result<()> {
//!     // Create a client with your API key
//!     let client = GrokClient::new("your-api-key")?;
//!
//!     // Send a simple chat message
//!     let response = client
//!         .chat("What is Rust?", None)
//!         .await?;
//!
//!     println!("Response: {}", response);
//!     Ok(())
//! }
//! ```
//!
//! ## Advanced Usage
//!
//! ```no_run
//! use grok_api::{GrokClient, ChatMessage, Result};
//! use serde_json::json;
//!
//! #[tokio::main]
//! async fn main() -> Result<()> {
//!     let client = GrokClient::builder()
//!         .api_key("your-api-key")
//!         .timeout_secs(60)
//!         .max_retries(5)
//!         .build()?;
//!
//!     // Build a conversation
//!     let messages = vec![
//!         ChatMessage::system("You are a helpful Rust programming assistant."),
//!         ChatMessage::user("How do I create a Vec in Rust?"),
//!     ];
//!
//!     let response = client
//!         .chat_with_history(&messages)
//!         .temperature(0.7)
//!         .max_tokens(1000)
//!         .model("grok-3")
//!         .send()
//!         .await?;
//!
//!     println!("Response: {}", response.content().unwrap_or(""));
//!     Ok(())
//! }
//! ```

mod client;
mod error;
mod models;
mod retry;
mod types;

pub use client::{GrokClient, GrokClientBuilder};
pub use error::{Error, Result};
pub use models::{
    ChatMessage, ChatRequest, ChatResponse, Choice, ContentPart, FunctionCall, ImageUrl, Message,
    MessageContent, Model, ToolCall, Usage, VideoUrl,
};
pub use retry::RetryConfig;
pub use types::{Role, StopReason};

/// Re-export commonly used types
pub mod prelude {
    pub use crate::client::{GrokClient, GrokClientBuilder};
    pub use crate::error::{Error, Result};
    pub use crate::models::{ChatMessage, ChatResponse};
    pub use crate::types::Role;
}

// Version information
/// The version of this crate
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// The default API base URL for Grok (xAI)
pub const DEFAULT_API_BASE_URL: &str = "https://api.x.ai";

/// The default model to use if none is specified
pub const DEFAULT_MODEL: &str = "grok-3";

/// Default timeout in seconds
pub const DEFAULT_TIMEOUT_SECS: u64 = 30;

/// Default maximum number of retries
pub const DEFAULT_MAX_RETRIES: u32 = 3;