Crate api_xai

Source

Expand description

§api_xai

Comprehensive Rust client for X.AI’s Grok API with enterprise reliability features.

§🎯 Architecture: Stateless HTTP Client

This API crate is designed as a stateless HTTP client with zero persistence requirements. It provides:

Direct HTTP calls to the X.AI Grok API
In-memory operation state only (resets on restart)
No external storage dependencies (databases, files, caches)
No configuration persistence beyond environment variables

This ensures lightweight, containerized deployments and eliminates operational complexity.

§🏛️ Governing Principle: “Thin Client, Rich API”

Expose all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors.

Key principles:

API Transparency: One-to-one mapping with X.AI Grok API endpoints
Zero Automatic Behavior: No implicit decision-making or magic thresholds
Explicit Control: Developer decides when, how, and why operations occur
Configurable Reliability: Enterprise features available through explicit configuration

§Scope

§In Scope

Chat completions (single and multi-turn)
Streaming responses (Server-Sent Events)
Tool/function calling
Model listing and details
Enterprise reliability (retry, circuit breaker, rate limiting, failover)
Health checks (liveness/readiness probes)
Token counting (local, using tiktoken)
Response caching (LRU)
Input validation
CURL diagnostics for debugging
Batch operations (parallel request orchestration)
Performance metrics (Prometheus)
Synchronous API wrapper

§Out of Scope

Vision/multimodal (no XAI API support)
Audio processing (no XAI API support)
Embeddings (no XAI API support)
Safety settings/content moderation (no XAI API endpoints)
Model tuning/deployment (no XAI API support)
WebSocket streaming (XAI uses SSE only)

§Features

Core Capabilities:

Chat completions with full conversational support
SSE streaming responses
Complete function/tool calling integration
Model management (list, retrieve)

Enterprise Reliability:

Retry logic with exponential backoff and jitter
Circuit breaker for failure threshold management
Rate limiting with token bucket algorithm
Multi-endpoint failover rotation
Kubernetes-style health checks
Structured logging with tracing

Client-Side Enhancements:

Token counting using tiktoken (GPT-4 encoding)
LRU response caching
Request parameter validation
CURL command generation for debugging
Parallel batch processing
Prometheus metrics collection

§Installation

Add to your Cargo.toml:

[dependencies]
api_xai = { version = "0.1.0", features = ["full"] }

§Quick Start

§Basic Chat

use api_xai::{ Client, Secret, XaiEnvironmentImpl, ChatCompletionRequest, Message, ClientApiAccessors };

#[ tokio::main ]
async fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let secret = Secret::load_with_fallbacks( "XAI_API_KEY" )?;
  let env = XaiEnvironmentImpl::new( secret )?;
  let client = Client::build( env )?;

  let request = ChatCompletionRequest::former()
    .model( "grok-2-1212".to_string() )
    .messages( vec![ Message::user( "Hello, Grok!" ) ] )
    .form();

  let response = client.chat().create( request ).await?;
  println!( "Grok: {:?}", response.choices[ 0 ].message.content );

  Ok( () )
}

§Streaming Chat

use api_xai::{ Client, Secret, XaiEnvironmentImpl, ChatCompletionRequest, Message, ClientApiAccessors };
use futures_util::StreamExt;

#[ tokio::main ]
async fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let secret = Secret::load_with_fallbacks( "XAI_API_KEY" )?;
  let env = XaiEnvironmentImpl::new( secret )?;
  let client = Client::build( env )?;

  let request = ChatCompletionRequest::former()
    .model( "grok-2-1212".to_string() )
    .messages( vec![ Message::user( "Tell me a story" ) ] )
    .stream( true )
    .form();

  let mut stream = client.chat().create_stream( request ).await?;

  while let Some( chunk ) = stream.next().await
  {
    let chunk = chunk?;
    if let Some( content ) = chunk.choices[ 0 ].delta.content.as_ref()
    {
      print!( "{}", content );
    }
  }

  Ok( () )
}

§Authentication

§Option 1: Workspace Secret (Recommended)

Create secret/-secrets.sh in your project root:

#!/bin/bash
export XAI_API_KEY="xai-your-key-here"

§Option 2: Environment Variable

export XAI_API_KEY="xai-your-key-here"

The crate uses workspace_tools for secret management with automatic fallback chain:

Workspace secrets (./secret/-secrets.sh)
Alternative files (secrets.sh, .env)
Environment variable

§Feature Flags

§Core Features

enabled - Master switch for core functionality
streaming - SSE streaming support
tool_calling - Function calling and tools

§Enterprise Reliability

retry - Exponential backoff retry logic
circuit_breaker - Circuit breaker pattern
rate_limiting - Token bucket rate limiting
failover - Multi-endpoint failover
health_checks - Health monitoring
structured_logging - Tracing integration

§Client-Side Enhancements

count_tokens - Local token counting (requires: tiktoken-rs)
caching - Response caching (requires: lru)
input_validation - Request validation
curl_diagnostics - Debug utilities
batch_operations - Parallel processing
performance_metrics - Metrics collection (requires: prometheus)
sync_api - Sync wrappers

§Presets

full - All features enabled (default)

§Testing

§Test Coverage

122 doc tests passing
107 integration tests passing
229 total tests with real API validation
No-mockup policy: all tests use real API calls

§Documentation

API Reference - Complete API documentation
OpenAPI Summary - Endpoint reference
Specification - Detailed project specification
Examples - Real-world usage examples

§Dependencies

reqwest: HTTP client with async support
tokio: Async runtime
serde: Serialization/deserialization
workspace_tools: Secret management
error_tools: Unified error handling
tiktoken-rs: Token counting (optional)
lru: Response caching (optional)
prometheus: Metrics collection (optional)

All dependencies workspace-managed for consistency.

§OpenAI Compatibility

The X.AI Grok API is OpenAI-compatible, using the same REST endpoint patterns and request/response formats. Token counting uses GPT-4 encoding (cl100k_base) via tiktoken for accurate counts.

§Contributing

Follow established patterns in existing code
Use 2-space indentation consistently
Add tests for new functionality
Update documentation for public APIs
Ensure zero clippy warnings: cargo clippy -- -D warnings
Follow zero-tolerance mock policy (real API integration only)
Follow the “Thin Client, Rich API” principle

§License

MIT

§Links

Specification - Technical specification
Examples - Usage examples
API Reference - Complete documentation X.AI Grok API client for Rust

This crate provides a comprehensive HTTP client for interacting with X.AI’s Grok API. It handles authentication, request/response serialization, and streaming support.

§Governing Principle : “Thin Client, Rich API”

This library follows the principle of “Thin Client, Rich API” - exposing all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors.

Key Distinction: The principle prohibits automatic/implicit behaviors but explicitly allows and encourages explicit/configurable enterprise reliability features.

§Core Principles

API Transparency: One-to-one mapping with X.AI Grok API endpoints
Zero Automatic Behavior: No implicit decision-making or magic thresholds
Explicit Control: Developer decides when, how, and why operations occur
Information vs Action: Clear separation between data retrieval and state changes
Configurable Reliability: Enterprise features available through explicit configuration

§`OpenAI` Compatibility

The X.AI Grok API is OpenAI-compatible, using the same REST endpoint patterns and request/response formats. This allows for easy migration from OpenAI to X.AI with minimal code changes.

§Enterprise Reliability Features

The following enterprise reliability features are explicitly allowed when implemented with explicit configuration and transparent operation:

Configurable Retry Logic: Exponential backoff with explicit configuration (feature : retry)
Circuit Breaker Pattern: Failure threshold management with transparent state (feature : circuit_breaker)
Rate Limiting: Request throttling with explicit rate configuration (feature : rate_limiting)
Failover Support: Multi-endpoint configuration and automatic switching (feature : failover)
Health Checks: Periodic endpoint health verification and monitoring (feature : health_checks)

§State Management Policy

✅ ALLOWED: Runtime-Stateful, Process-Stateless

Connection pools, circuit breaker state, rate limiting buckets
Retry logic state, failover state, health check state
Runtime state that dies with the process
No persistent storage or cross-process state

❌ PROHIBITED: Process-Persistent State

File storage, databases, configuration accumulation
State that survives process restarts

Implementation Requirements:

Feature gating behind cargo features (retry, circuit_breaker, rate_limiting, failover, health_checks)
Explicit configuration required (no automatic enabling)
Transparent method naming (e.g., execute_with_retries(), execute_with_circuit_breaker())
Zero overhead when features disabled

§Secret Management with `workspace_tools`

This crate follows wTools ecosystem conventions by prioritizing workspace_tools for secret management over environment variables.

§Recommended : Automatic Fallback Chain

The Secret::load_with_fallbacks() method tries multiple sources in priority order:

Workspace secrets (-secrets.sh) - primary workspace pattern
Alternative files (secrets.sh, .env) - workspace alternatives
Environment variable - fallback for CI/deployment

§Setup Instructions

Option 1: Workspace Secrets (Recommended)

Create ./secret/-secrets.sh in your workspace root:

#!/bin/bash
export XAI_API_KEY="xai-your-key-here"

The workspace_tools fallback chain searches:

./secret/{filename} (local workspace)
$PRO/secret/{filename} (PRO workspace)
$HOME/secret/{filename} (home directory)
Environment variable $XAI_API_KEY

Option 2: Environment Variable (CI/Deployment)

export XAI_API_KEY="xai-your-key-here"

§Usage

use api_xai::Secret;

// Recommended : tries all sources (workspace-first)
let secret = Secret::load_with_fallbacks( "XAI_API_KEY" )?;

// Explicit : load from workspace only
let secret = Secret::load_from_workspace( "XAI_API_KEY", "-secrets.sh" )?;

// Explicit : load from environment only
let secret = Secret::load_from_env( "XAI_API_KEY" )?;

§Examples

use api_xai::{ Client, Secret, XaiEnvironmentImpl, ChatCompletionRequest, Message, ClientApiAccessors };

// Create a client
let secret = Secret::new( "xai-your-key-here".to_string() )?;
let env = XaiEnvironmentImpl::new( secret )?;
let client = Client::build( env )?;

// Create a chat request using the Former builder
let request = ChatCompletionRequest::former()
  .model( "grok-2-1212".to_string() )
  .messages( vec![ Message::user( "Hello, Grok! How are you?" ) ] )
  .form();

// Send the request
let response = client.chat().create( request ).await?;
println!( "Grok responded : {:?}", response.choices[ 0 ].message.content );

Re-exports§

pub use client_api_accessors::ClientApiAccessors;

Modules§

batch_operations: Parallel request orchestration for batch processing.
caching: Response caching with LRU eviction policy.
chat: Chat completion request and response types.
circuit_breaker: Circuit breaker pattern for failure management.
client: Core HTTP client for XAI API requests.
client_api_accessors: Trait-based API accessors for chat and models endpoints.
components: Shared component types (messages, tools, etc).
count_tokens: Token counting using tiktoken library.
curl_diagnostics: CURL command generation for debugging.
enhanced_retry: Enhanced retry logic with exponential backoff.
enhanced_tools: Enhanced function calling with parallel execution.
environment: Environment configuration and HTTP client setup.
error: Error types and result handling for XAI API operations.
exposed: Exposed namespace of the module.
failover: Failover support with multi-endpoint rotation.
health_checks: Health check endpoints for production readiness.
input_validation: Request parameter validation and error detection.
models: Model listing and details endpoints.
orphan: Orphan namespace of the module.
own: Own namespace of the module.
performance_metrics: Prometheus metrics collection and export.
prelude: Prelude to use essentials: use my_module ::prelude :: *.
rate_limiting: Rate limiting with token bucket algorithm.
secret: Secret management for API keys using workspace_tools.
structured_logging: Structured logging with tracing integration.
sync_api: Synchronous blocking wrappers for async API.

Macros§

log_circuit_breaker_state: Logs a circuit breaker state change.
log_error: Logs an API error.
log_failover: Logs a failover event.
log_rate_limit: Logs rate limiting information.
log_request: Logs an API request.
log_response: Logs an API response.
log_retry: Logs a retry attempt.

Structs§

BatchProcessor: A client wrapper that supports batch processing of requests.
CachedClient: A client wrapper that caches chat completion responses.
Chat: Chat completions API accessor.
ChatCompletionChunk: Streaming chunk from chat completion.
ChatCompletionRequest: Request to create a chat completion.
ChatCompletionResponse: Response from chat completion request.
Choice: A single completion choice.
ChunkChoice: A single streaming choice.
CircuitBreaker: Circuit breaker for protecting against cascading failures.
CircuitBreakerConfig: Circuit breaker configuration.
Client: XAI API client.
Delta: Incremental message update in streaming.
EnhancedRetryConfig: Enhanced retry configuration with exponential backoff.
FailoverConfig: Failover configuration.
FailoverManager: Failover manager for multiple XAI endpoints.
Function: Function specification.
FunctionCall: Function call details.
HealthCheckResult: Result of a health check.
ListModelsResponse: Response from listing all available models.
Message: A single message in a chat conversation.
MetricGuard: A wrapper that automatically records metrics for operations.
MetricsCollector: Metrics collector for XAI API operations.
Model: Information about a specific model.
Models: Models API accessor.
RateLimiter: Token bucket rate limiter.
RateLimiterConfig: Rate limiter configuration using token bucket algorithm.
Secret: Secure wrapper for XAI API key.
SyncCachedClient: Synchronous wrapper for cached_create (requires caching feature).
SyncClient: A synchronous (blocking) wrapper around the async XAI client.
SyncStreamIterator: Synchronous iterator wrapper around async streaming.
Tool: Tool definition for function calling.
ToolCall: Tool call made by the assistant.
ToolResult: Result of executing a tool call.
Usage: Token usage information for API requests.
XaiEnvironmentImpl: Default implementation of XAI environment configuration.

Enums§

CircuitState: Circuit breaker states.
EndpointHealth: Endpoint health status.
HealthStatus: Health status of the API endpoint.
Role: Message role in a conversation.
XaiError: Error types for XAI API operations.

Constants§

DEFAULT_BASE_URL: Default base URL for XAI API.
DEFAULT_TIMEOUT_SECS: Default request timeout in seconds.

Traits§

ClientApiAccessors: Trait providing convenient API accessors for the client.
XaiEnvironment: Environment configuration trait for XAI API client.

Functions§

count_tokens: Counts tokens in a text string for a specific model.
count_tokens_for_request: Counts tokens in a chat completion request.
create_operation_span: Creates a tracing span for tracking an API operation.
execute_tool_calls_parallel: Executes multiple tool calls in parallel.
execute_tool_calls_sequential: Executes multiple tool calls sequentially.
health_check: Performs a health check on the XAI API endpoint.
liveness_check: Performs a quick liveness check.
readiness_check: Performs a readiness check.
sync_count_tokens: Synchronous wrapper for count_tokens (requires count_tokens feature).
sync_count_tokens_for_request: Synchronous wrapper for count_tokens_for_request (requires count_tokens feature).
sync_validate_request_size: Synchronous wrapper for validate_request_size (requires count_tokens feature).
to_curl: Converts a chat completion request to a CURL command.
to_curl_compact: Converts a chat completion request to a compact CURL command (single line).
to_curl_with_endpoint: Converts a chat completion request to a CURL command with custom endpoint.
to_curl_with_key: Converts a chat completion request to a CURL command with a custom API key.
validate_frequency_penalty: Validates that frequency_penalty is within valid range [-2.0, 2.0].
validate_max_tokens: Validates that max_tokens is positive.
validate_messages: Validates that messages array is non-empty with valid content.
validate_model: Validates that the model name is supported.
validate_presence_penalty: Validates that presence_penalty is within valid range [-2.0, 2.0].
validate_request: Validates a chat completion request.
validate_request_size: Validates that a request fits within the model’s context window.
validate_temperature: Validates that temperature is within valid range [0.0, 2.0].
validate_tools: Validates tool definitions (function calling schemas).
validate_top_p: Validates that top_p is within valid range [0.0, 1.0].

Type Aliases§

Result: Result type alias using error_tools.

Crate api_xai

Crate api_xai Copy item path

§api_xai

§🎯 Architecture: Stateless HTTP Client

§🏛️ Governing Principle: “Thin Client, Rich API”

§Scope

§In Scope

§Out of Scope

§Features

§Installation

§Quick Start

§Basic Chat

§Streaming Chat

§Authentication

§Option 1: Workspace Secret (Recommended)

§Option 2: Environment Variable

§Feature Flags

§Core Features

§Enterprise Reliability

§Client-Side Enhancements

§Presets

§Testing

§Test Coverage

§Documentation

§Dependencies

§OpenAI Compatibility

§Contributing

§License

§Links

§Governing Principle : “Thin Client, Rich API”

§Core Principles

§OpenAI Compatibility

§Enterprise Reliability Features

§State Management Policy

§Secret Management with workspace_tools

§Recommended : Automatic Fallback Chain

§Setup Instructions

§Usage

§Examples

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate api_xai

§`OpenAI` Compatibility

§Secret Management with `workspace_tools`