How xai-org/xai-sdk-python works
1. What this repository is
- This is a Python SDK, not an application server.
- Its core purpose is to expose xAI APIs through a Pythonic client library with both synchronous and asynchronous usage patterns.
2. Public entry points
- The top-level xai_sdk package is the user-facing API surface.
- It exposes Client and AsyncClient, plus convenience modules for chat, files, models, images, video, batch, auth, collections, tokenizer, and telemetry.
3. Client architecture
- The main architectural split is between sync and async implementations.
- src/xai_sdk/sync/* contains blocking client wrappers.
- src/xai_sdk/aio/* contains asyncio-based wrappers.
- Both layers mirror each other closely so the same feature set is available in both execution models.
4. Domain feature modules
- Feature-specific modules organize the SDK by API capability rather than transport:
- chat for multi-turn conversations, streaming, deferred sampling, tool use, and structured outputs
- files for upload and file-backed workflows
- image and video for media generation and understanding
- models for model discovery/metadata
- batch for asynchronous batch jobs
- collections for collection/document workflows
- tokenizer for token counting / tokenization
- auth for auth-related API calls
- This is the layer that shapes the ergonomic SDK API.
5. Transport and service boundary
- The SDK speaks to xAI over gRPC.
- The generated protobuf and gRPC stubs live under src/xai_sdk/proto/v5 and src/xai_sdk/proto/v6.
- This is the clearest hard boundary in the repo: everything above it is a Python wrapper layer; everything below it is wire-format / RPC contract.
6. API versioning strategy
- The presence of both v5 and v6 proto trees shows the SDK supports multiple backend API contract generations.
- The wrapper modules abstract the versioned RPC surface so user code stays stable even as the wire contract evolves.
7. Response and type modeling
- src/xai_sdk/types/* contains higher-level Python types for chat, image, model, and video data.
- These types sit between raw protobuf messages and the public SDK ergonomics, making responses easier to consume while still preserving access to the underlying proto via .proto.
8. Cross-cutting concerns
- interceptors.py likely centralizes request/response interception for concerns such as telemetry, retries, or metadata propagation.
- poll_timer.py supports long-running or deferred operations, especially for deferred chat or batch-style workflows.
- meta.py and __about__.py handle package metadata and version exposure.
9. Telemetry as an optional horizontal subsystem
- src/xai_sdk/telemetry/* is a cross-cutting observability layer built on OpenTelemetry.
- It can export traces to console or OTLP backends and can be enabled or disabled independently of the API clients.
- The telemetry layer is additive: it instruments SDK calls without changing the main request flow.
10. Typical data flow
- User code instantiates Client or AsyncClient.
- The client builds a gRPC channel with auth, timeouts, retries, and optional interceptors.
- Feature modules construct requests using the local Python types.
- Requests are serialized through protobuf/gRPC stubs to xAI services.
- Responses come back as proto messages, then get wrapped into SDK response objects and helper types.
11. Examples as feature maps
- examples/sync and examples/aio are paired demonstrations of the same capabilities.
- They act like a living catalog of supported workflows: chat, streaming, function calling, structured outputs, image/video operations, tokenizer, telemetry, and more.
- The symmetry reinforces that sync/async are first-class parallel architectures.
12. Tests as contract coverage
- The test tree mirrors the sync/async split and the major API surface areas.
- tests/server.py suggests integration-style testing against a local test server or mocked service boundary, which is appropriate for a gRPC SDK.
- This means the repo’s quality boundary is primarily “does the wrapper behavior match the RPC contract?”
13. Packaging and delivery
- pyproject.toml and uv.lock indicate modern Python packaging and dependency management.
- GitHub Actions workflows cover CI, release, version-bump validation, and auto-tagging, which matters because this is a published SDK with strict versioned contracts.
14. How to draw the architecture
- Draw three layers: public Python SDK, transport/proto layer, and xAI backend services.
- Split the public SDK into sync and async branches, with feature modules hanging off each.
- Add a horizontal telemetry overlay that can instrument both branches.
- Show examples and tests as non-runtime support assets that exercise the same public API surface.
Main entry points: xai_sdk/__init__.py xai_sdk · sync/client.py Sync client · aio/client.py Async client · sync/__init__.py Sync wrappers
Components 19
Public SDK
User-facing Python API surface
- xai_sdk · Top-level package exposing the public client API
src/xai_sdk/__init__.py - Sync client · Synchronous client entry point and wrappers
src/xai_sdk/sync/client.py - Async client · AsyncIO client entry point and wrappers
src/xai_sdk/aio/client.py - Chat · Multi-turn chat, streaming, tools, deferred and structured output flows
src/xai_sdk/chat.py - Files · Upload and file-backed workflows
src/xai_sdk/files.py - Media APIs · Image and video generation and understanding surfaces
src/xai_sdk/image.py - Models · Model discovery and metadata access
src/xai_sdk/models.py - Batch/Auth/etc · Batch jobs, auth, collections, tokenizer, search, and related endpoints
src/xai_sdk/batch.py - Sync wrappers · Blocking wrappers for feature modules
src/xai_sdk/sync/__init__.py - Async wrappers · Async wrappers for feature modules
src/xai_sdk/aio/__init__.py - SDK types · Higher-level chat, image, model, and video response types
src/xai_sdk/types/__init__.py - Interceptors · Central request/response interception and metadata hooks
src/xai_sdk/interceptors.py - Poll timer · Polling support for deferred and batch-style workflows
src/xai_sdk/poll_timer.py - Telemetry · Optional OpenTelemetry instrumentation and exporters
src/xai_sdk/telemetry/__init__.py
Transport
gRPC and protobuf contract boundary
Connections 36
- xai_sdk → Sync client: exports · Top-level package exposes the synchronous client
- xai_sdk → Async client: exports · Top-level package exposes the async client
- xai_sdk → Chat: exports · Public chat convenience surface
- xai_sdk → Files: exports · Public files convenience surface
- xai_sdk → Media APIs: exports · Public image and video convenience surface
- xai_sdk → Models: exports · Public models convenience surface
- xai_sdk → Batch/Auth/etc: exports · Public batch/auth/collections/tokenizer surface
- Sync client → Sync wrappers: uses · Blocking feature implementations live under the sync layer
- Async client → Async wrappers: uses · Async feature implementations live under the aio layer
- Sync wrappers → Chat: implements · Sync chat wrapper
- Sync wrappers → Files: implements · Sync files wrapper
- Sync wrappers → Media APIs: implements · Sync media wrappers
- Sync wrappers → Models: implements · Sync models wrapper
- Async wrappers → Chat: implements · Async chat wrapper
- Async wrappers → Files: implements · Async files wrapper
- Async wrappers → Media APIs: implements · Async media wrappers
- Async wrappers → Models: implements · Async models wrapper
- Chat → SDK types: wraps · Chat responses are lifted into SDK types
- Media APIs → SDK types: wraps · Media responses are lifted into SDK types
- Models → SDK types: wraps · Model metadata is presented via SDK types
- Batch/Auth/etc → Poll timer: uses · Deferred and batch operations use polling support
- Sync client → Interceptors: configures · Sync client wires interceptors into transport setup
- Async client → Interceptors: configures · Async client wires interceptors into transport setup
- Sync client → Proto v5: calls · One supported wire contract generation
- Sync client → Proto v6: calls · Current wire contract generation
- Async client → Proto v5: calls · One supported wire contract generation
- Async client → Proto v6: calls · Current wire contract generation
- Proto v5 → xAI backend: rpc · gRPC requests cross the wire boundary
- Proto v6 → xAI backend: rpc · gRPC requests cross the wire boundary
- Telemetry → Sync client: instruments · Observes sync API calls without changing core flow
- Telemetry → Async client: instruments · Observes async API calls without changing core flow
- Examples → xai_sdk: demonstrates · Examples exercise the public package entry points
- Tests → Sync wrappers: verifies · Sync tests cover wrapper behavior
- Tests → Async wrappers: verifies · Async tests cover wrapper behavior
- Tests → Proto v5: contracts · Test coverage validates RPC contract behavior
- Tests → Proto v6: contracts · Test coverage validates RPC contract behavior