feat(xai): add xAI provider for Grok chat completions

.agents/skills/building-packages/SKILL.md

@@ -20,6 +20,7 @@ Publishable packages are built with **tsup** (esbuild-based), orchestrated by **
 - `@core-ai/omnifact` — Omnifact provider
 - `@core-ai/anthropic-vertex` — Vertex AI Anthropic (Claude) provider
 - `@core-ai/kimi` — Kimi API provider
+- `@core-ai/xai` — xAI (Grok) provider
 
 Internal packages (`eslint-config`, `typescript-config`, `esbuild-config`) are not built or published.
 
@@ -89,7 +90,7 @@ Source code uses `.ts` import extensions with `allowImportingTsExtensions: true`
 Published package dependencies must remain acyclic. Current runtime dependency
 layers are:
 
-- Base providers (`anthropic`, `google-genai`, `kimi`, `mistral`, `openai`)
+- Base providers (`anthropic`, `google-genai`, `kimi`, `mistral`, `openai`, `xai`)
   depend on `core-ai`.
 - Composed providers depend on `core-ai` and their base provider:
     - `anthropic-vertex` → `anthropic`

.agents/skills/contributing/SKILL.md

@@ -74,6 +74,7 @@ All publishable packages share a single version number:
 - `@core-ai/omnifact`
 - `@core-ai/kimi`
 - `@core-ai/anthropic-vertex`
+- `@core-ai/xai`
 
 Selecting any one package in a changeset bumps every package in the fixed group to the same version. Create a changeset for **every package with meaningful changes** — use separate files when the changelog text differs per package.
 

.agents/skills/releasing-packages/SKILL.md

@@ -109,6 +109,7 @@ npm publish -w @core-ai/azure-openai --access public
 npm publish -w @core-ai/omnifact --access public
 npm publish -w @core-ai/anthropic-vertex --access public
 npm publish -w @core-ai/kimi --access public
+npm publish -w @core-ai/xai --access public
 ```
 
 Publish `core-ai` first since providers depend on it.

.changeset/add-xai-provider.md

@@ -0,0 +1,5 @@
+---
+'@core-ai/xai': minor
+---
+
+Add `@core-ai/xai` provider for xAI Grok API with native `reasoning_content` support, configurable reasoning effort, reasoning model parameter validation, and native JSON Schema structured output with a JSON Mode fallback.

.changeset/config.json

@@ -17,7 +17,8 @@
             "@core-ai/azure-openai",
             "@core-ai/omnifact",
             "@core-ai/anthropic-vertex",
-            "@core-ai/kimi"
+            "@core-ai/kimi",
+            "@core-ai/xai"
         ]
     ],
     "linked": [],

README.md

@@ -40,6 +40,7 @@ A type-safe abstraction layer over LLM provider SDKs for TypeScript. Write provi
 | Omnifact              | `@core-ai/omnifact`         | Yes  | Yes       | —          | —                |
 | Vertex AI Anthropic   | `@core-ai/anthropic-vertex` | Yes  | Yes       | —          | —                |
 | Kimi (Moonshot AI)    | `@core-ai/kimi`             | Yes  | Yes       | —          | —                |
+| xAI (Grok)            | `@core-ai/xai`             | Yes  | Yes       | —          | —                |
 
 > **Note:** `@core-ai/openai` uses the Responses API by default and exposes
 > strict Chat Completions through `openai.chat.chatModel()`. Use
@@ -485,6 +486,7 @@ packages/
   omnifact/      — Omnifact API Gateway provider implementation
   anthropic-vertex/ — Vertex AI Anthropic (Claude) provider implementation
   kimi/          — Kimi API provider implementation
+  xai/           — xAI (Grok) provider implementation
   testing/       — Shared test utilities (internal)
 ```
 
@@ -527,6 +529,8 @@ Provider keys:
 - `GOOGLE_API_KEY`
 - `MISTRAL_API_KEY`
 - `OMNIFACT_API_KEY`
+- `KIMI_API_KEY`
+- `XAI_API_KEY`
 - `GOOGLE_VERTEX_PROJECT` (Vertex AI providers; uses Application Default Credentials or `GOOGLE_APPLICATION_CREDENTIALS_JSON`, plain JSON or base64)
 
 ## Contributing

RELEASING.md

@@ -18,6 +18,7 @@ This repository uses Turborepo for build/test tasks and Changesets for versionin
 - `@core-ai/omnifact`
 - `@core-ai/anthropic-vertex`
 - `@core-ai/kimi`
+- `@core-ai/xai`
 
 These packages are configured as a fixed group in `.changeset/config.json`, so they always share the same version.
 

docs/api/providers/xai.mdx

@@ -0,0 +1,242 @@
+---
+title: 'xAI Provider'
+description: 'Create and configure the xAI provider for Grok chat completions'
+---
+
+## Overview
+
+The xAI provider connects to the [xAI API](https://docs.x.ai/) — an OpenAI-compatible Chat Completions endpoint. Use your xAI API key and supported model IDs such as `grok-4.3`.
+
+## Installation
+
+```bash
+npm install @core-ai/xai
+```
+
+## createXAI()
+
+Create an xAI provider instance.
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+
+const xai = createXAI({
+  apiKey: process.env.XAI_API_KEY,
+});
+```
+
+### Options
+
+<ParamField path="apiKey" type="string" optional>
+  Your xAI API key.
+</ParamField>
+
+<ParamField path="baseURL" type="string" optional>
+  Custom API base URL. Defaults to `https://api.x.ai/v1`.
+</ParamField>
+
+<ParamField path="client" type="XAIChatClient" optional>
+  Provide a client implementing the xAI chat completions contract.
+</ParamField>
+
+### Returns
+
+`XAIProvider` with method `chatModel()`.
+
+## Supported models
+
+- **grok-4.3** — flagship model with configurable reasoning effort
+- **grok-4.20-0309-reasoning** — reasoning-focused Grok 4.20 variant
+- **grok-4.20-0309-non-reasoning** — lower-latency Grok 4.20 variant
+- **grok-build-0.1** — coding-focused agentic model
+
+## Capabilities
+
+| Feature | Support |
+|---------|--------|
+| Chat Completion | Yes |
+| Streaming | Yes |
+| Function Calling | Yes |
+| Vision | Yes |
+| Reasoning | Yes (`grok-4.3` supports configurable effort) |
+| Structured Output (`generateObject` / `streamObject`) | Yes (JSON Mode with client-side schema validation) |
+| Embeddings | No |
+| Image Generation | No |
+
+## Examples
+
+### Basic chat
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+import { generate } from '@core-ai/core-ai';
+
+const xai = createXAI({
+  apiKey: process.env.XAI_API_KEY,
+});
+
+const model = xai.chatModel('grok-4.3');
+
+const result = await generate({
+  model,
+  messages: [{ role: 'user', content: 'Explain quantum computing briefly.' }],
+});
+
+console.log(result.content);
+```
+
+### Streaming with reasoning
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+import { stream } from '@core-ai/core-ai';
+
+const xai = createXAI({
+  apiKey: process.env.XAI_API_KEY,
+});
+
+const model = xai.chatModel('grok-4.3');
+
+const chatStream = await stream({
+  model,
+  messages: [{ role: 'user', content: 'Solve 37 * 48 step by step.' }],
+  reasoning: { effort: 'medium' },
+});
+
+for await (const event of chatStream) {
+  if (event.type === 'reasoning-delta') {
+    process.stdout.write(event.text);
+  }
+  if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  }
+}
+```
+
+### Multi-turn reasoning preservation
+
+xAI returns `reasoning_content` for reasoning models. core-ai preserves this automatically when you use `resultToMessage()`:
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+import { generate, resultToMessage } from '@core-ai/core-ai';
+
+const xai = createXAI({ apiKey: process.env.XAI_API_KEY });
+const model = xai.chatModel('grok-4.3');
+
+const messages = [{ role: 'user', content: 'Plan a refactor.' }];
+const firstResult = await generate({
+  model,
+  messages,
+  reasoning: { effort: 'medium' },
+});
+
+const followUp = await generate({
+  model,
+  messages: [
+    ...messages,
+    resultToMessage(firstResult),
+    { role: 'user', content: 'Now implement step one.' },
+  ],
+  reasoning: { effort: 'medium' },
+});
+```
+
+## Reasoning effort
+
+For `grok-4.3`, map core-ai reasoning effort to xAI's `reasoning_effort`:
+
+| core-ai | xAI |
+|---------|-----|
+| `minimal` | `none` |
+| `low` | `low` |
+| `medium` | `medium` |
+| `high` | `high` |
+| `max` | `high` |
+
+<Warning>
+  Reasoning models do not support `stopSequences`, `frequencyPenalty`, or `presencePenalty` in `providerOptions.xai`. The provider validates these locally and rejects unsupported combinations.
+</Warning>
+
+## Structured output
+
+`generateObject()` and `streamObject()` use native xAI JSON Schema response
+formats for documented models and validate the returned JSON with your Zod
+schema. Unknown or incompatible model IDs fall back to JSON Mode with the
+schema included in the prompt.
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+import { generateObject } from '@core-ai/core-ai';
+import { z } from 'zod';
+
+const xai = createXAI({ apiKey: process.env.XAI_API_KEY });
+const model = xai.chatModel('grok-4.3');
+
+const result = await generateObject({
+  model,
+  messages: [{ role: 'user', content: 'Return the weather for Berlin.' }],
+  schema: z.object({
+    city: z.string(),
+    temperatureC: z.number(),
+  }),
+  schemaName: 'weather_schema',
+});
+
+console.log(result.object);
+```
+
+## Provider-specific options
+
+Pass xAI-specific options via `providerOptions.xai`:
+
+```typescript
+await generate({
+  model: xai.chatModel('grok-4.3'),
+  messages: [{ role: 'user', content: 'Hello!' }],
+  providerOptions: {
+    xai: {
+      parallelToolCalls: true,
+      responseFormat: { type: 'json_object' },
+      seed: 42,
+      serviceTier: 'priority',
+      promptCacheKey: 'my-conversation',
+    },
+  },
+});
+```
+
+Available fields: `parallelToolCalls`, `responseFormat`, `stopSequences`, `frequencyPenalty`, `presencePenalty`, `seed`, `user`, `serviceTier`, `promptCacheKey`.
+
+## Error handling
+
+```typescript
+import { ProviderError } from '@core-ai/core-ai';
+
+try {
+  const result = await generate({
+    model: xai.chatModel('grok-4.3'),
+    messages: [{ role: 'user', content: 'Hello!' }],
+  });
+} catch (error) {
+  if (error instanceof ProviderError) {
+    console.error('xAI API error:', error.message);
+    console.error('Status:', error.statusCode);
+  }
+}
+```
+
+## Related
+
+<CardGroup cols={2}>
+  <Card
+    title="OpenAI Compat Provider"
+    icon="message"
+    href="/api/providers/openai"
+  >
+    OpenAI Chat Completions compatibility reference
+  </Card>
+  <Card title="core-ai Functions" icon="function" href="/api/core/generate">
+    Learn about generate, stream, and more
+  </Card>
+</CardGroup>

docs/concepts/providers.mdx

@@ -359,6 +359,39 @@ const model = kimi.chatModel('kimi-k2.7-code');
 
 Pass `providerOptions.kimi` for Kimi-specific Chat Completions options. Kimi K2.7 Code always runs in thinking mode; core-ai preserves `reasoning_content` across turns via `resultToMessage()`.
 
+## xAI
+
+xAI provides access to Grok models through the xAI API — an OpenAI-compatible Chat Completions endpoint with native `reasoning_content` support and configurable reasoning effort for `grok-4.3`.
+
+### Creating a Provider
+
+```typescript
+import { createXAI } from '@core-ai/xai';
+
+const xai = createXAI({
+    apiKey: process.env.XAI_API_KEY,
+    // baseURL defaults to https://api.x.ai/v1
+});
+```
+
+### Provider Options
+
+```typescript
+type XAIProviderOptions = {
+    apiKey?: string;
+    baseURL?: string;
+    client?: XAIChatClient;
+};
+```
+
+### Getting Models
+
+```typescript
+const model = xai.chatModel('grok-4.3');
+```
+
+Pass `providerOptions.xai` for xAI-specific Chat Completions options. For `grok-4.3`, use `reasoning: { effort: 'low' | 'medium' | 'high' }` to control thinking depth; core-ai preserves `reasoning_content` across turns via `resultToMessage()`.
+
 ## Using Custom Clients
 
 All providers support bringing your own client instance, which is useful for advanced configuration:
@@ -390,6 +423,7 @@ const openai = createOpenAI({ client: customClient });
 | Mistral                | ✓    | ✓          | ✗      | Efficient open-source options             |
 | Omnifact               | ✓    | ✗          | ✗      | Organization gateway for enabled models   |
 | Kimi                   | ✓    | ✗          | ✗      | Preserved thinking, coding focus           |
+| xAI                    | ✓    | ✗          | ✗      | Grok models, configurable reasoning        |
 
 ## Next Steps
 

docs/docs.json

@@ -105,7 +105,8 @@
                             "api/providers/google-vertex",
                             "api/providers/mistral",
                             "api/providers/omnifact",
-                            "api/providers/kimi"
+                            "api/providers/kimi",
+                            "api/providers/xai"
                         ]
                     }
                 ]