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
Examples - Real-world usage examples

§Project Structure

This section documents the complete project layout with each entity’s responsibility and scope.

§Responsibility Table

§Production Code & Configuration

Entity	Responsibility	Scope
`src/`	Production source code	Core library implementation (see module docs)
`Cargo.toml`	Crate manifest and configuration	Dependencies, features, metadata
`license`	License terms	MIT license text

§Testing & Documentation

Entity	Responsibility	Scope
`tests/`	Comprehensive test suite	All tests (integration, reliability, components) - see tests/readme.md
`docs/`	API reference and research	OpenAPI specs, endpoint docs, research - see docs/readme.md
`examples/`	Usage demonstrations	Runnable examples for developers - see examples/readme.md

§Specification & Documentation Files

Entity	Responsibility	Scope
`readme.md`	Project overview and onboarding	Quick start, architecture overview, feature summary

§Temporary Files & Working Directories

Entity	Responsibility	Scope
`-default_topic/`	Claude Code working directory	Tool-generated temporary workspace
`-validation_checklist.md`	Validation checklist	Audit validation items (temporary)
`-audit_report_comprehensive.md`	Comprehensive audit report	Audit findings and remediation guidance (temporary)
`-remediation_plan_comprehensive.md`	Remediation strategy	Step-by-step compliance fix plan (temporary)

Note: All entities prefixed with - are temporary and excluded from git tracking.

§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

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: Parallel request orchestration for batch processing. Parallel request orchestration for batch processing. A client wrapper that supports batch processing of requests.
CachedClient: Response caching with LRU eviction policy. Response caching with LRU eviction policy. A client wrapper that caches chat completion responses.
Chat: Chat completion request and response types. Chat completion request and response types. Chat completions API accessor.
ChatCompletionChunk: A single Server-Sent Events chunk from a streaming completion.
ChatCompletionRequest: Request body for the POST chat/completions endpoint.
ChatCompletionResponse: Response body from the POST chat/completions endpoint.
Choice: One completion alternative within a ChatCompletionResponse.
ChunkChoice: One delta choice within a streaming chunk.
CircuitBreaker: Circuit breaker pattern for failure management. Circuit breaker pattern for failure management. Circuit breaker for protecting against cascading failures.
CircuitBreakerConfig: Circuit breaker pattern for failure management. Circuit breaker pattern for failure management. Circuit breaker configuration.
Client: Core HTTP client for XAI API requests. Core HTTP client for XAI API requests. XAI API client.
Delta: Partial message update delivered in a streaming chunk.
EnhancedRetryConfig: Enhanced retry logic with exponential backoff. Enhanced retry logic with exponential backoff. Enhanced retry configuration with exponential backoff.
FailoverConfig: Failover support with multi-endpoint rotation. Failover support with multi-endpoint rotation. Failover configuration.
FailoverManager: Failover support with multi-endpoint rotation. Failover support with multi-endpoint rotation. Failover manager for multiple XAI endpoints.
Function: Function specification (name, description, JSON Schema parameters).
FunctionCall: Name and arguments for a specific function invocation.
HealthCheckResult: Health check endpoints for production readiness. Health check endpoints for production readiness. Result of a health check.
ListModelsResponse: Shared component types (messages, tools, etc). Model information types (model details, listings). Shared component types (messages, tools, etc). Model information types (model details, listings). Response from listing all available models.
Message: A single message in a chat conversation.
MetricGuard: Prometheus metrics collection and export. Prometheus metrics collection and export. A wrapper that automatically records metrics for operations.
MetricsCollector: Prometheus metrics collection and export. Prometheus metrics collection and export. Metrics collector for XAI API operations.
Model: Shared component types (messages, tools, etc). Model information types (model details, listings). Shared component types (messages, tools, etc). Model information types (model details, listings). Information about a specific model.
Models: Model listing and details endpoints. Model listing and details endpoints. Models API accessor.
RateLimiter: Rate limiting with token bucket algorithm. Rate limiting with token bucket algorithm. Token bucket rate limiter.
RateLimiterConfig: Rate limiting with token bucket algorithm. Rate limiting with token bucket algorithm. Rate limiter configuration using token bucket algorithm.
Secret: Secret management for API keys using workspace_tools. Secret management for API keys using workspace_tools. Secure wrapper for XAI API key.
SyncCachedClient: Synchronous blocking wrappers for async API. Synchronous blocking wrappers for async API. Synchronous wrapper for cached_create (requires caching feature).
SyncClient: Synchronous blocking wrappers for async API. Synchronous blocking wrappers for async API. A synchronous (blocking) wrapper around the async XAI client.
SyncStreamIterator: Synchronous blocking wrappers for async API. Synchronous blocking wrappers for async API. Synchronous iterator wrapper around async streaming.
Tool: A function tool definition passed in the tools array of a request.
ToolCall: A function invocation requested by the assistant.
ToolResult: Enhanced function calling with parallel execution. Enhanced function calling with parallel execution. Result of executing a tool call.
Usage: Token usage statistics returned in every completion response.
XaiEnvironmentImpl: Environment configuration and HTTP client setup. Environment configuration and HTTP client setup. Default implementation of XAI environment configuration.

Enums§

CircuitState: Circuit breaker pattern for failure management. Circuit breaker pattern for failure management. Circuit breaker states.
EndpointHealth: Failover support with multi-endpoint rotation. Failover support with multi-endpoint rotation. Endpoint health status.
HealthStatus: Health check endpoints for production readiness. Health check endpoints for production readiness. Health status of the API endpoint.
Role: Role of a participant in a chat conversation.
XaiError: Error types and result handling for XAI API operations. Error types and result handling for XAI API operations. Error types for XAI API operations.

Constants§

DEFAULT_BASE_URL: Environment configuration and HTTP client setup. Environment configuration and HTTP client setup. Default base URL for XAI API.
DEFAULT_TIMEOUT_SECS: Environment configuration and HTTP client setup. Environment configuration and HTTP client setup. Default request timeout in seconds.

Traits§

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

Functions§

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

Type Aliases§

Result: Error types and result handling for XAI API operations. Error types and result handling for XAI API operations. 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

§Project Structure

§Responsibility Table

§Production Code & Configuration

§Testing & Documentation

§Specification & Documentation Files

§Temporary Files & Working Directories

§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`