# xai-org/xai-sdk-python architecture

> Architecture diagram of the GitHub repository xai-org/xai-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xai-org/xai-sdk-python
- Repository: https://github.com/xai-org/xai-sdk-python

## Overview

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: [`src/xai_sdk/__init__.py`](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/__init__.py) (xai_sdk), [`src/xai_sdk/sync/client.py`](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/client.py) (Sync client), [`src/xai_sdk/aio/client.py`](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/aio/client.py) (Async client), [`src/xai_sdk/sync/__init__.py`](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/__init__.py) (Sync wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_sdk["Public SDK"]
  node_sdk_init["xai_sdk<br/>package surface<br/>[__init__.py]"]
  node_sync_client["Sync client<br/>blocking client<br/>[client.py]"]
  node_async_client["Async client<br/>[client.py]"]
  node_chat_api["Chat<br/>conversation API<br/>[chat.py]"]
  node_files_api["Files<br/>file API<br/>[files.py]"]
  node_media_api["Media APIs<br/>image/video API<br/>[image.py]"]
  node_models_api["Models<br/>model API<br/>[models.py]"]
  node_ops_api["Batch/Auth/etc<br/>ops API<br/>[batch.py]"]
  node_sync_wrappers["Sync wrappers<br/>sync layer<br/>[__init__.py]"]
  node_aio_wrappers["Async wrappers<br/>async layer<br/>[__init__.py]"]
  node_response_types["SDK types<br/>typed models<br/>[__init__.py]"]
  node_interceptors["Interceptors<br/>cross-cutting<br/>[interceptors.py]"]
  node_poll_timer["Poll timer<br/>long-running ops<br/>[poll_timer.py]"]
  node_telemetry["Telemetry<br/>observability<br/>[__init__.py]"]
end

subgraph group_transport["Transport"]
  node_proto_v5[("Proto v5<br/>grpc contract")]
  node_proto_v6[("Proto v6<br/>grpc contract")]
  node_xai_backend(("xAI backend<br/>remote service"))
end

subgraph group_support["Support"]
  node_examples["Examples<br/>usage demos"]
  node_tests["Tests"]
end

node_sdk_init -->|"exports"| node_sync_client
node_sdk_init -->|"exports"| node_async_client
node_sdk_init -->|"exports"| node_chat_api
node_sdk_init -->|"exports"| node_files_api
node_sdk_init -->|"exports"| node_media_api
node_sdk_init -->|"exports"| node_models_api
node_sdk_init -->|"exports"| node_ops_api
node_sync_client -->|"uses"| node_sync_wrappers
node_async_client -->|"uses"| node_aio_wrappers
node_sync_wrappers -->|"implements"| node_chat_api
node_sync_wrappers -->|"implements"| node_files_api
node_sync_wrappers -->|"implements"| node_media_api
node_sync_wrappers -->|"implements"| node_models_api
node_aio_wrappers -->|"implements"| node_chat_api
node_aio_wrappers -->|"implements"| node_files_api
node_aio_wrappers -->|"implements"| node_media_api
node_aio_wrappers -->|"implements"| node_models_api
node_chat_api -->|"wraps"| node_response_types
node_media_api -->|"wraps"| node_response_types
node_models_api -->|"wraps"| node_response_types
node_ops_api -->|"uses"| node_poll_timer
node_sync_client -->|"configures"| node_interceptors
node_async_client -->|"configures"| node_interceptors
node_sync_client -->|"calls"| node_proto_v5
node_sync_client -->|"calls"| node_proto_v6
node_async_client -->|"calls"| node_proto_v5
node_async_client -->|"calls"| node_proto_v6
node_proto_v5 -->|"rpc"| node_xai_backend
node_proto_v6 -->|"rpc"| node_xai_backend
node_telemetry -->|"instruments"| node_sync_client
node_telemetry -->|"instruments"| node_async_client
node_examples -.->|"demonstrates"| node_sdk_init
node_tests -.->|"verifies"| node_sync_wrappers
node_tests -.->|"verifies"| node_aio_wrappers
node_tests -.->|"contracts"| node_proto_v5
node_tests -.->|"contracts"| node_proto_v6

click node_sdk_init "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/__init__.py"
click node_sync_client "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/client.py"
click node_async_client "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/aio/client.py"
click node_chat_api "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/chat.py"
click node_files_api "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/files.py"
click node_media_api "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/image.py"
click node_models_api "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/models.py"
click node_ops_api "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/batch.py"
click node_sync_wrappers "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/__init__.py"
click node_aio_wrappers "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/aio/__init__.py"
click node_response_types "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/types/__init__.py"
click node_interceptors "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/interceptors.py"
click node_poll_timer "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/poll_timer.py"
click node_telemetry "https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/telemetry/__init__.py"
click node_proto_v5 "https://github.com/xai-org/xai-sdk-python/tree/main/src/xai_sdk/proto/v5"
click node_proto_v6 "https://github.com/xai-org/xai-sdk-python/tree/main/src/xai_sdk/proto/v6"
click node_examples "https://github.com/xai-org/xai-sdk-python/tree/main/examples"
click node_tests "https://github.com/xai-org/xai-sdk-python/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk_init,node_sync_client,node_async_client,node_chat_api,node_files_api,node_media_api,node_models_api,node_ops_api,node_sync_wrappers,node_aio_wrappers,node_response_types,node_interceptors,node_poll_timer,node_telemetry toneBlue
class node_proto_v5,node_proto_v6,node_xai_backend toneAmber
class node_examples,node_tests toneMint
```

## Components

### Public SDK

User-facing Python API surface

- [xai_sdk](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/__init__.py): package surface · Top-level package exposing the public client API · `src/xai_sdk/__init__.py`
- [Sync client](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/client.py): blocking client · Synchronous client entry point and wrappers · `src/xai_sdk/sync/client.py`
- [Async client](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/aio/client.py): async client · AsyncIO client entry point and wrappers · `src/xai_sdk/aio/client.py`
- [Chat](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/chat.py): conversation API · Multi-turn chat, streaming, tools, deferred and structured output flows · `src/xai_sdk/chat.py`
- [Files](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/files.py): file API · Upload and file-backed workflows · `src/xai_sdk/files.py`
- [Media APIs](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/image.py): image/video API · Image and video generation and understanding surfaces · `src/xai_sdk/image.py`
- [Models](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/models.py): model API · Model discovery and metadata access · `src/xai_sdk/models.py`
- [Batch/Auth/etc](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/batch.py): ops API · Batch jobs, auth, collections, tokenizer, search, and related endpoints · `src/xai_sdk/batch.py`
- [Sync wrappers](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/sync/__init__.py): sync layer · Blocking wrappers for feature modules · `src/xai_sdk/sync/__init__.py`
- [Async wrappers](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/aio/__init__.py): async layer · Async wrappers for feature modules · `src/xai_sdk/aio/__init__.py`
- [SDK types](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/types/__init__.py): typed models · Higher-level chat, image, model, and video response types · `src/xai_sdk/types/__init__.py`
- [Interceptors](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/interceptors.py): cross-cutting · Central request/response interception and metadata hooks · `src/xai_sdk/interceptors.py`
- [Poll timer](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/poll_timer.py): long-running ops · Polling support for deferred and batch-style workflows · `src/xai_sdk/poll_timer.py`
- [Telemetry](https://github.com/xai-org/xai-sdk-python/blob/main/src/xai_sdk/telemetry/__init__.py): observability · Optional OpenTelemetry instrumentation and exporters · `src/xai_sdk/telemetry/__init__.py`

### Transport

gRPC and protobuf contract boundary

- [Proto v5](https://github.com/xai-org/xai-sdk-python/tree/main/src/xai_sdk/proto/v5): grpc contract · Generated protobuf and gRPC stubs for API version 5 · `src/xai_sdk/proto/v5`
- [Proto v6](https://github.com/xai-org/xai-sdk-python/tree/main/src/xai_sdk/proto/v6): grpc contract · Generated protobuf and gRPC stubs for API version 6 · `src/xai_sdk/proto/v6`
- **xAI backend**: remote service · External gRPC backend providing API capabilities

### Support

Examples, tests, and release tooling

- [Examples](https://github.com/xai-org/xai-sdk-python/tree/main/examples): usage demos · Paired sync and async example catalog covering major SDK workflows · `examples`
- [Tests](https://github.com/xai-org/xai-sdk-python/tree/main/tests): contract tests · Sync and async test suites validating wrapper behavior against the RPC surface · `tests`

## Connections

- 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
