> For the complete documentation index, see [llms.txt](https://weavescope.gitbook.io/beam_weaver/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://weavescope.gitbook.io/beam_weaver/partners/xai.md).

# xAI

BeamWeaver includes an OpenAI-compatible xAI provider under `BeamWeaver.XAI`.

## Implemented

* `BeamWeaver.XAI.ChatModel` implements the xAI Responses API through `BeamWeaver.Core.ChatModel`.
* `BeamWeaver.XAI.ChatCompletionsModel` implements the xAI Chat Completions API.
* `BeamWeaver.XAI.EmbeddingModel` implements the xAI Embeddings API with model `v1`.
* `BeamWeaver.XAI.Tools` renders custom OpenAI-compatible function tools and passes through xAI built-ins such as `web_search`, `x_search`, `code_execution`, `code_interpreter`, `attachment_search`, `collections_search`, `file_search`, `shell`, `view_image`, `view_x_video`, `live_search`, and `mcp`.
* Namespace constructors load defaults from `config :beam_weaver, :xai`; put any OS environment reads in your `config/runtime.exs`. Custom routing can use configured `:base_url`, explicit `:base_url`, or `:endpoint`.
* Responses include normalized provider metadata, reasoning content, citations, usage metadata, and xAI-specific reasoning-token accounting.
* Streaming supports text deltas, reconstructed final assistant messages, and typed stream envelopes tagged with xAI invocation metadata.
* Structured output is available on both Responses and Chat Completions. xAI request rendering keeps dynamic map fields as open object schemas while preserving strict closed-object validation for normal nested objects.
* Deferred Chat Completions requests can be followed up with `BeamWeaver.XAI.Client.deferred_completion/3`.
* Checked-in chat profiles cover `grok-4.3`, `grok-4.20-0309-reasoning`, `grok-4.20-0309-non-reasoning`, `grok-4.20-multi-agent-0309`, and `grok-build-0.1`, with alias handling for documented xAI slugs.
* Retired May 15, 2026 slugs fail before transport with replacement metadata instead of silently changing price or reasoning behavior.

## Usage

```elixir
model =
  BeamWeaver.XAI.chat_model(
    model: "grok-4.3"
  )

BeamWeaver.Core.ChatModel.invoke(model, [
  BeamWeaver.Core.Message.user("Summarize what makes the BEAM good for agents.")
])
```

Use Chat Completions explicitly when that wire shape is required:

```elixir
model =
  BeamWeaver.XAI.chat_completions_model(
    model: "grok-4.3"
  )
```

Tools are provider request values:

```elixir
tools = [
  BeamWeaver.XAI.Tools.web_search(search_depth: :deep),
  BeamWeaver.XAI.Tools.x_search(),
  BeamWeaver.XAI.Tools.code_execution(),
  BeamWeaver.XAI.Tools.function(my_tool, strict: true)
]

BeamWeaver.Core.ChatModel.invoke(model, messages, tools: tools)
```

Use `BeamWeaver.XAI.Tools.live_search/1` for Chat Completions search tools.

Model initialization can use explicit or inferred xAI identifiers:

```elixir
{:ok, model} = BeamWeaver.Models.init_chat_model("xai:grok-4.3")
{:ok, model} = BeamWeaver.Models.init_chat_model("xai:grok-4.20-0309-reasoning")
```

Embeddings use the explicit xAI prefix:

```elixir
{:ok, embeddings} = BeamWeaver.Models.init_embeddings("xai:v1")
{:ok, vector} = BeamWeaver.Core.EmbeddingModel.embed_query(embeddings, "hello")
```

## Current Model Policy

xAI recommends `grok-4.3` for most chat and coding use cases. BeamWeaver keeps profiles for the other current chat models listed above, plus embedding model `v1`. Imagine and voice models are not chat or embedding models and are not constructed through `init_chat_model/2`.

The retired May 15, 2026 slugs are rejected with `:deprecated_model`: `grok-4-1-fast-reasoning`, `grok-4-1-fast-non-reasoning`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, `grok-4-0709`, `grok-code-fast-1`, `grok-3`, and `grok-imagine-image-pro`.

## Remaining xAI Work

* Live-cassette expansion against the xAI API once credentials and stable fixtures are available.
* xAI image/video generation APIs. LangChain's xAI partner currently exposes chat behavior; BeamWeaver does not expose image/video provider APIs.
* Exact Python class identity and serialization compatibility. BeamWeaver keeps native Elixir modules, structs, and tagged errors.

## Related Guides

* [Models](/beam_weaver/core-components/models.md)
* [Tools](/beam_weaver/core-components/tools.md#server-side-provider-tools)
* [Structured Output](/beam_weaver/core-components/structured_output.md)
* [Messages](/beam_weaver/core-components/messages.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://weavescope.gitbook.io/beam_weaver/partners/xai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.