grok_api

A Rust client library for the Grok AI API (xAI). Simple, robust, and production-ready.

Features

• 🚀 Easy to use - Simple async API with builder pattern
• 🔄 Automatic retries - Built-in retry logic for transient failures
• 🛡️ Robust error handling - Comprehensive error types with detailed messages
• 🌐 Network resilient - Optimized for challenging conditions (Starlink, satellite connections)
• 🔧 Flexible configuration - Customize timeouts, retries, and more
• 📊 Rate limiting - Client-side rate limit tracking (optional)
• 🛠️ Tool/Function calling - Full support for function calling and tools

Quick Start

Add this to your Cargo.toml:

[dependencies]

grok_api = "0.1"

tokio = { version = "1", features = ["full"] }

Simple Example

use grok_api::{GrokClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = GrokClient::new("your-api-key")?;
    
    let response = client
        .chat("What is Rust?", None)
        .await?;
    
    println!("Response: {}", response);
    Ok(())
}

Conversation with History

use grok_api::{GrokClient, ChatMessage, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = GrokClient::new("your-api-key")?;
    
    let messages = vec![
        ChatMessage::system("You are a helpful Rust expert."),
        ChatMessage::user("How do I create a Vec?"),
    ];
    
    let response = client
        .chat_with_history(&messages)
        .temperature(0.7)
        .max_tokens(1000)
        .model("grok-3")
        .send()
        .await?;
    
    println!("Response: {}", response.content().unwrap_or(""));
    println!("Tokens used: {}", response.usage.total_tokens);
    
    Ok(())
}

Advanced Configuration

use grok_api::{GrokClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = GrokClient::builder()
        .api_key("your-api-key")
        .timeout_secs(60)
        .max_retries(5)
        .base_url("https://custom-endpoint.com")  // Optional
        .build()?;
    
    // Use client...
    
    Ok(())
}

API Key

Get your API key from x.ai.

Set it as an environment variable:

export GROK_API_KEY="your-api-key-here"

Or pass it directly to the client:

let client = GrokClient::new("your-api-key")?;

Available Models

• grok-3 - Latest flagship model (default)
• grok-3-mini - Efficient smaller model
• grok-2-latest - Previous generation
• grok-2 - Stable previous generation
• grok-beta - Experimental features
• grok-vision-beta - Vision capabilities

// Use a specific model
let response = client.chat("Hello", Some("grok-3-mini")).await?;

// Or with the builder
let response = client
    .chat_with_history(&messages)
    .model("grok-3")
    .send()
    .await?;

Error Handling

The library provides comprehensive error types:

use grok_api::{GrokClient, Error};

match client.chat("Hello", None).await {
    Ok(response) => println!("Success: {}", response),
    Err(Error::Authentication) => eprintln!("Invalid API key"),
    Err(Error::RateLimit) => eprintln!("Rate limit exceeded"),
    Err(Error::Network(msg)) => eprintln!("Network error: {}", msg),
    Err(Error::Timeout(secs)) => eprintln!("Timeout after {} seconds", secs),
    Err(e) => eprintln!("Other error: {}", e),
}

Retry Logic

Network errors are automatically retried with exponential backoff:

let client = GrokClient::builder()
    .api_key("your-api-key")
    .max_retries(5)  // Retry up to 5 times
    .build()?;

Retryable errors include:

• Network timeouts
• Connection failures
• Server errors (5xx)
• Starlink/satellite network drops

Function Calling / Tools

The library supports Grok's function calling feature:

use grok_api::{GrokClient, ChatMessage};
use serde_json::json;

let tools = vec![
    json!({
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name"
                    }
                },
                "required": ["location"]
            }
        }
    })
];

let messages = vec![
    ChatMessage::user("What's the weather in San Francisco?")
];

let response = client
    .chat_with_history(&messages)
    .tools(tools)
    .send()
    .await?;

if response.has_tool_calls() {
    for tool_call in response.tool_calls().unwrap() {
        println!("Tool: {}", tool_call.function.name);
        println!("Args: {}", tool_call.function.arguments);
    }
}

Starlink Optimization

The library includes special handling for Starlink and other satellite connections:

• Automatic detection of connection drops
• Exponential backoff with jitter
• Extended timeout handling
• Connection pooling and keep-alive

use grok_api::{GrokClient, Error};

let client = GrokClient::builder()
    .api_key("your-api-key")
    .timeout_secs(60)      // Longer timeout for satellite
    .max_retries(5)        // More retries for drops
    .build()?;

match client.chat("Hello", None).await {
    Ok(response) => println!("Success: {}", response),
    Err(e) if e.is_starlink_drop() => {
        eprintln!("Starlink connection dropped, already retried");
    }
    Err(e) => eprintln!("Error: {}", e),
}

Examples

Run the examples:

# Set your API key

export GROK_API_KEY="your-api-key"


# Simple chat

cargo run --example simple_chat


# Multi-turn conversation

cargo run --example conversation


# Streaming (placeholder for future feature)

cargo run --example streaming

Features

Default Features

• retry - Automatic retry logic (enabled by default)

Optional Features

• starlink - Additional optimizations for Starlink connections

[dependencies]

grok_api = { version = "0.1", features = ["starlink"] }

Testing

# Run tests

cargo test


# Run tests with logging

RUST_LOG=debug cargo test


# Run integration tests (requires API key)

GROK_API_KEY="your-key" cargo test --test integration

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.70 or later.

Documentation

Full API documentation is available at docs.rs/grok_api.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Disclaimer

This is an unofficial library and is not affiliated with, endorsed by, or sponsored by xAI or X Corp.

Links

• Crates.io
• Documentation
• GitHub Repository
• xAI Official Site

Changelog

See CHANGELOG.md for release notes and version history.

Support

For bugs and feature requests, please open an issue.

Made with ❤️ and Rust