xai sdk python

The Problem

Applications that talk to xAI's models (Grok chat, image generation, embeddings, document collections) need a typed client that handles gRPC transport, auth, streaming, and message history. Without an SDK, each consumer re-implements that layer against raw protobuf stubs. This repo is the official Python SDK for that API surface.

What This Does

The SDK is a gRPC-based Python library (Python 3.10+) exposing both synchronous (xai_sdk.Client) and asynchronous (xai_sdk.AsyncClient) clients. The src/xai_sdk/ tree covers chat, image generation/understanding, files, collections, search, tokenizer, and telemetry. It ships generated protobuf code for two API versions under src/xai_sdk/proto/v5/ and v6/.

The examples/ folder has 36 runnable scripts mirroring every feature in both sync and async variants (e.g. examples/sync/function_calling.py, examples/aio/stored_chat.py). Tests live in tests/, including a mock gRPC server in tests/server.py.

How It Is Wired

Execution starts at main in examples/aio/auth.py, which reaches 179 functions. The hot path is short: main instantiates Client (called from 18 places) and makes a network call via session.get in two hops. The create function is the highest-blast-radius symbol, called from 117 places; user follows at 82. src/xai_sdk/chat.py is the core module: 68 functions, 6 classes, imported by 21 files. It owns _make_chat, sample, and message append logic.

The module graph shows src/xai_sdk/proto/__init__.py as a hub with 24 importers — churn there ripples widely. tests/server.py (52 functions, 13 classes) is the mock server that the test suite routes through. There are no circular dependencies across the 153 analyzed modules.

How To Use It

Setup — install from PyPI:

pip install xai-sdk
# or
uv add xai-sdk

Configuration — the client reads the XAI_API_KEY environment variable by default; you can pass it explicitly via Client(api_key=...).

Running it — instantiate the client and hold a chat session:

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()
chat = client.chat.create(model="grok-3", messages=[system("You are a pirate assistant.")])
chat.append(user("Hello"))
response = chat.sample()
print(response.content)

Full runnable examples are in examples/sync/ and examples/aio/.

Real-World Use

A support bot that persists conversation context: the append/sample loop manages history client-side while the API stays stateless. For long-running services, use the async client (examples/aio/chat.py) to avoid blocking on gRPC calls, and chat.sample_batch for offline processing.

Code Health & Issues

Static analysis (not opinion) found 27 issues: 5 high, 22 medium, across 4 kinds.

• High – Oversized files: src/xai_sdk/chat.py (971 lines), tests/server.py, tests/aio/chat_test.py. High cognitive load; changes ripple widely.
• High – Duplicated code blocks: 3261 repeated 6-line blocks across 102 files, concentrated in the mirrored sync/async examples. Extract shared helpers.
• High – Deep nesting: max indentation depth 9 in src/xai_sdk/chat.py, tests/server.py, examples/aio/function_calling.py. Flatten with early returns.
• Medium – Hub modules: src/xai_sdk/proto/__init__.py (24 importers), tests/__init__.py (14), src/xai_sdk/telemetry/__init__.py (12). Keep stable and small.

SDLC gaps: no dependency lockfile (non-reproducible builds), no Dependabot/Renovate, no dependency vulnerability scan in CI, and workflow jobs lack timeout-minutes.

The Bottom Line

A solid, well-tested official SDK with real coverage of the xAI API surface and both sync/async paths. The main costs are maintainability: duplicated example code and oversized core modules. Use it if you need Grok chat or xAI image/collection features from Python; just be prepared for slow merges on chat.py.