[bot] Add xAI Python SDK (xai-sdk) native integration for chat, image, and video generation instrumentation

[braintrust-bot]

Summary

The xAI Python SDK (xai-sdk) is the official Python client for xAI's API (Grok models). It is a gRPC-based SDK (v1.12.2, May 7 2026) with execution APIs for chat completions, image generation, video generation, structured outputs, and server-side tools (web search, X search, code execution). This repository has zero native instrumentation for any xai-sdk execution surface — no integration directory, no wrapper, no patcher, no auto_instrument() support.

Braintrust documents xAI as a supported provider via the gateway/proxy approach: users configure the Braintrust gateway as the base URL and access xAI through the standard OpenAI client. This approach does not cover users of the native xai-sdk, which uses gRPC transport rather than REST. The xai-sdk client is not an openai.OpenAI subclass and cannot be wrapped with wrap_openai().

xAI is listed on the Braintrust integrations directory under supported model providers.

What needs to be instrumented

The xai-sdk package (v1.12.2) exposes these execution surfaces, none of which are instrumented:

Chat completions (highest priority)

Client Method	Description
client.chat.create(messages=..., model=..., ...)	Sync multi-turn chat completion (gRPC)
client.chat.create(..., stream=True)	Streaming chat completion yielding token chunks
await async_client.chat.create(...)	Async chat completion
await async_client.chat.create(..., stream=True)	Async streaming chat completion

Response includes choices, usage (prompt_tokens, completion_tokens), model, and id. Token metrics are directly available for span population.

Image generation

Client Method	Description
client.image.generate(prompt=..., model=..., ...)	Text-to-image generation

Video generation

Client Method	Description
client.video.generate(...)	Text-to-video and image-to-video generation
client.video.extend(...)	Extend existing videos

Server-side tools (Grok-specific agentic surfaces)

Tool	Description
web_search	Autonomous web search during generation
x_search	Autonomous X (Twitter) search during generation
code_execution	Server-side code execution during generation

These server-side tools are unique to xAI/Grok and cannot be traced via the OpenAI compatibility layer.

Structured outputs

API	Description
client.chat.create(response_format=SomePydanticModel, ...)	Structured output with typed Pydantic responses

Implementation notes

gRPC transport: Unlike all existing Braintrust integrations (which patch REST/HTTP clients), xai-sdk uses gRPC. The patching strategy must intercept gRPC service stubs rather than HTTP requests. This is a different instrumentation surface from Stainless-generated REST SDKs like OpenAI, Groq, and Mistral.

Two clients: xai.Client (sync) and xai.AsyncClient (async), both of which need instrumentation.

Server-side tools: When Grok invokes server-side tools autonomously during generation, the response includes tool call events similar to OpenAI-style tool use. These events should be captured as child spans of the chat completion span.

Structured outputs: When response_format is a Pydantic model, the resolved typed output and schema should be captured in span metadata.

No coverage in any instrumentation layer

• No integration directory (py/src/braintrust/integrations/xai/)
• No wrapper function (e.g. wrap_xai())
• No patcher in any existing integration
• No nox test session (test_xai)
• No version entry in py/src/braintrust/integrations/versioning.py
• No mention in py/src/braintrust/integrations/__init__.py

A grep for xai or xai.sdk (case-insensitive) across py/src/braintrust/integrations/ returns zero matches.

Braintrust docs status

unclear — The Braintrust xAI docs page describes a gateway/proxy approach using openai.OpenAI(base_url="https://gateway.braintrust.dev/v1"). This covers users who access xAI through the OpenAI-compatible REST endpoint but does not cover native xai-sdk users who use gRPC. There is no auto_instrument() reference or wrap_xai() function documented.

Upstream references

• xai-sdk on PyPI: https://pypi.org/project/xai-sdk/ (v1.12.2, May 7 2026)
• xAI API documentation: https://docs.x.ai/docs/overview
• xAI Python SDK (Grok SDK) docs: https://docs.x.ai/docs/sdk/grok-sdk
• xAI API reference: https://docs.x.ai/api
• xAI changelog: https://docs.x.ai/docs/changelog

Local repo files inspected

• py/src/braintrust/integrations/ — no xai/ directory exists on main
• py/src/braintrust/wrappers/ — no xAI wrapper
• py/noxfile.py — no test_xai session
• py/src/braintrust/integrations/__init__.py — xAI not listed in integration registry
• py/src/braintrust/integrations/versioning.py — no xAI version matrix
• py/pyproject.toml — no xAI entries in [tool.braintrust.matrix]
• Full repo grep for xai, xai_sdk, xai-sdk across py/src/braintrust/ — zero matches