xai_rust/
lib.rs

1//! # xai-rust
2//!
3//! A Rust SDK for the xAI API (Grok models).
4//!
5//! ## Quick Start
6//!
7//! ```rust,no_run
8//! use xai_rust::{XaiClient, Role};
9//!
10//! #[tokio::main]
11//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
12//!     let client = XaiClient::new(std::env::var("XAI_API_KEY")?)?;
13//!
14//!     let response = client.responses()
15//!         .create("grok-4")
16//!         .message(Role::User, "Hello, Grok!")
17//!         .send()
18//!         .await?;
19//!
20//!     println!("{}", response.output_text().unwrap_or_default());
21//!     Ok(())
22//! }
23//! ```
24//!
25//! ## Blocking Sync Client
26//!
27//! ```rust,no_run
28//! use xai_rust::SyncXaiClient;
29//!
30//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
31//! let client = SyncXaiClient::from_env()?;
32//!
33//! let response = client
34//!     .responses()
35//!     .create("grok-4")
36//!     .user("Say hello.")
37//!     .send()?;
38//!
39//! println!("{}", response.output_text().unwrap_or_default());
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! ## Python SDK-style Helpers
45//!
46//! ```rust,no_run
47//! use xai_rust::XaiClient;
48//! use xai_rust::chat::{system, user, assistant, image, text, web_search};
49//!
50//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
51//! let client = XaiClient::from_env()?;
52//!
53//! let response = client.responses()
54//!     .create("grok-4")
55//!     .messages(vec![
56//!         system("You are a helpful assistant."),
57//!         user("What's in this image?"),
58//!     ])
59//!     .tool(web_search())
60//!     .send()
61//!     .await?;
62//! # Ok(())
63//! # }
64//! ```
65//!
66//! ## Features
67//!
68//! - **Responses API**: The primary endpoint for chat interactions
69//! - **Chat Completions**: Legacy chat API (deprecated but supported)
70//! - **Image Generation**: Generate images with Grok models
71//! - **Files API**: Upload and manage files
72//! - **Models API**: List available models
73//! - **Realtime API**: WebSocket-based voice interactions
74//! - **Batch API**: Process multiple requests in batches
75//! - **Collections API**: Document storage and retrieval
76//! - **Tokenizer API**: Count and get tokens
77//! - **Streaming**: Server-sent events for streaming responses
78//! - **Telemetry (optional)**: Feature-gated `tracing` instrumentation for request/retry events
79
80#![warn(missing_docs)]
81#![forbid(unsafe_code)]
82
83pub mod api;
84pub mod chat;
85pub mod client;
86pub mod config;
87pub mod error;
88pub mod models;
89pub mod stream;
90pub mod sync;
91
92// Re-export main types for convenience
93pub use client::XaiClient;
94pub use config::{ClientConfig, SecretString, XaiClientBuilder};
95pub use error::{Error, Result};
96pub use sync::SyncXaiClient;
97
98// Re-export chat helper functions at top level for convenience
99pub use chat::{
100    assistant, code_interpreter, collections_search, developer, file, file_inline, image,
101    image_base64, image_with_detail, mcp, required_tool, system, text, tool, tool_choice_auto,
102    tool_choice_none, tool_choice_required, tool_result, tool_strict, user, web_search,
103    web_search_allow, web_search_exclude, x_search, IntoMessageContent,
104};
105
106// Re-export commonly used model types
107pub use models::auth::ApiKeyInfo;
108pub use models::batch::{
109    Batch, BatchListResponse, BatchRequest, BatchRequestInfo, BatchRequestListResponse,
110    BatchRequestStatus, BatchResult, BatchResultListResponse, BatchStatus,
111};
112pub use models::collection::{
113    AddDocumentsResponse, BatchGetDocumentsRequest, Collection, CollectionListResponse,
114    CreateCollectionRequest, Document, DocumentListResponse, SearchRequest, SearchResponse,
115    SearchResult, UpdateCollectionRequest,
116};
117pub use models::content::{ContentPart, FileContent, ImageDetail, ImageUrlContent};
118pub use models::file::{DeleteFileResponse, FileListResponse, FileObject, FilePurpose};
119pub use models::file::{
120    FileDownloadRequest, FileUploadChunksRequest, FileUploadChunksResponse,
121    FileUploadInitializeRequest, FileUploadInitializeResponse,
122};
123pub use models::image::{
124    ImageData, ImageGenerationRequest, ImageGenerationResponse, ImageResponseFormat,
125};
126pub use models::message::{Message, MessageContent, Role};
127pub use models::response::{
128    InlineCitation, OutputItem, Response, ResponseFormat, ResponseFormatType, StreamChunk,
129    TextContent,
130};
131pub use models::tokenizer::{TokenizeRequest, TokenizeResponse};
132pub use models::tool::{
133    FunctionCall, FunctionDefinition, McpServer, McpTool, Tool, ToolCall, ToolChoice,
134    WebSearchFilters,
135};
136pub use models::usage::Usage;
137pub use models::videos::{
138    Video, VideoData, VideoEditRequest, VideoGenerationRequest, VideoGenerationResponse,
139    VideoResponseFormat,
140};
141#[cfg(feature = "realtime")]
142pub use models::voice::{
143    AudioFormat, ConversationContent, ConversationContentType, ConversationItem,
144    ConversationItemType, RealtimeClientMessage, RealtimeError, RealtimeResponse,
145    RealtimeServerMessage, SessionConfig, Voice,
146};
xai_rust/lib.rs

xai_rust/
lib.rs
