@warlock.js/ai-xai 4.6.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — @warlock.js/ai-xai
+
+All notable changes to `@warlock.js/ai-xai` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
+
+## 4.6.0
+
+### Added
+
+- **First release.** xAI Grok adapter for `@warlock.js/ai` — a thin wrapper over `@warlock.js/ai-openai`'s `OpenAISDK` pinned to `https://api.x.ai/v1` (`provider: "xai"`), so all wire behavior (streaming, tool calls, structured output, error wrapping) is inherited unchanged.
+- **`XaiSDK`** — `.model()` / `.embedder()` / `.image()` / `.count()` delegated to the wrapped client. `baseURL` and `provider` are optional (default to xAI's endpoint / label); every other `openai` `ClientOptions` value is forwarded verbatim.
+- **xAI-specific capability inference** (`inferVisionCapability` / `inferReasoningCapability`, exported alongside `XAI_VISION_MODEL_PREFIXES` / `XAI_REASONING_MODEL_PREFIXES`) — Grok ids don't match OpenAI's `gpt-*` / `o*` prefixes, so `vision` is auto-`true` for `grok-4` / `grok-2-vision` and `reasoning` for `grok-4` / `grok-3-mini`. An explicit `vision` / `reasoning` per model always wins.
+- **`XAI_CHAT_MODELS`** — convenience list of current public Grok chat ids (`grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `grok-2`).
+- **Optional per-model pricing registry** — resolution at `model()` time is per-model `pricing` > SDK registry > `undefined`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @warlock.js/ai-xai
+
+xAI **Grok** adapter for [`@warlock.js/ai`](../ai). xAI speaks the OpenAI Chat Completions protocol, so this package is a **thin wrapper** over [`@warlock.js/ai-openai`](../ai-openai)'s `OpenAISDK`: it constructs one internal `OpenAISDK` pinned to `https://api.x.ai/v1` with `provider: "xai"` and delegates `model()` / `embedder()` / `image()` / `count()` to it — while injecting xAI's own capability inference so Grok model names resolve to the right `vision` / `reasoning` flags even though they don't match OpenAI's `gpt-*` / `o*` prefixes.
+
+```bash
+npm install @warlock.js/ai @warlock.js/ai-xai @warlock.js/seal openai
+```
+
+> `@warlock.js/seal` is the recommended Standard Schema library for tool inputs and structured output. Any Standard Schema V1 library works (Zod, Valibot, …). `openai` is required because this adapter wraps `@warlock.js/ai-openai`.
+
+## Quick start
+
+```ts
+import { XaiSDK } from "@warlock.js/ai-xai";
+import { ai } from "@warlock.js/ai";
+
+const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });
+
+const myAgent = ai.agent({
+  model: xai.model({ name: "grok-4" }),
+});
+
+const result = await myAgent.execute("Hello!");
+console.log(result.text);
+```
+
+`apiKey` is the only required field — `baseURL` defaults to `https://api.x.ai/v1` (the xAI OpenAI-compatible endpoint) and `provider` defaults to `"xai"`. `XaiSDK` is a class holding one long-lived wrapped client; construct one per account and reuse it.
+
+## API surface
+
+```ts
+new XaiSDK(config: XaiSDKConfig)                // = OpenAISDKConfig (baseURL/provider default to xAI)
+  .model(config: XaiModelConfig)                // → ModelContract
+  .embedder(config: XaiEmbedderConfig)          // → EmbedderContract
+  .image(config: XaiImageConfig)                // → ImageModelContract
+  .count(text, model?)                          // approximate token count
+
+XaiModelConfig {
+  name: string;                                 // e.g. "grok-4", "grok-3-mini", "grok-2-vision"
+  temperature?: number;
+  maxTokens?: number;
+  vision?: boolean;                             // override auto-inference
+  reasoning?: boolean;                          // override auto-inference
+  structuredOutput?: boolean;                   // override; defaults true
+  pricing?: ModelPricing;                       // per-model USD-per-1M rates
+  // ...any other ModelConfig field forwarded to the wrapped OpenAI model
+}
+```
+
+## Models & capabilities
+
+Capabilities are inferred from the Grok model **name** (via `inferVisionCapability` / `inferReasoningCapability`, matched as a prefix so dated / `-latest` / `-fast` / `-beta` variants are covered) and injected as explicit flags before delegating — an explicit value always wins.
+
+| Model           | `vision` | `reasoning`             |
+| --------------- | -------- | ----------------------- |
+| `grok-4`        | true     | true (reasoning-first)  |
+| `grok-3`        | false    | false                   |
+| `grok-3-mini`   | false    | true (the "think" variant) |
+| `grok-2-vision` | true     | false                   |
+| `grok-2`        | false    | false                   |
+
+- `structuredOutput` / `promptCaching` and the image / PDF / audio wire mapping all come from the wrapped OpenAI adapter unchanged.
+- `XAI_CHAT_MODELS`, `XAI_VISION_MODEL_PREFIXES`, and `XAI_REASONING_MODEL_PREFIXES` are exported for menus, validation, and docs.
+
+```ts
+xai.model({ name: "grok-4" });                  // vision + reasoning auto-true
+xai.model({ name: "grok-3-mini" });             // reasoning auto-true, vision false
+xai.model({ name: "grok-2-vision" });           // vision auto-true
+xai.model({ name: "grok-3", vision: true });    // explicit capability override
+```
+
+> Model availability changes over time — pass any current Grok id through `.model({ name })`; the prefix inference covers dated / `-latest` variants. Don't assume a model exists; check xAI's docs.
+
+## Reasoning effort
+
+```ts
+const model = xai.model({ name: "grok-4" });                        // reasoning auto-true
+await model.complete(messages, { reasoning: { effort: "high" } });  // → reasoning_effort: "high"
+```
+
+`reasoning.effort` (`"low" | "medium" | "high"`) maps verbatim to the OpenAI-compatible `reasoning_effort` param and is dropped for a non-reasoning model (e.g. `grok-3`).
+
+## Pricing
+
+`pricing` is an optional registry keyed by model name, rates in **USD per 1,000,000 tokens** (`ModelPricing`). Resolution at `model()` time: per-model `pricing` > SDK registry > `undefined` (no cost computed).
+
+```ts
+const xai = new XaiSDK({
+  apiKey,
+  pricing: {
+    "grok-4": { input: 3, output: 15 },
+    "grok-3-mini": { input: 0.3, output: 0.5 },
+  },
+});
+```
+
+> Set the current xAI rates yourself — the numbers above are illustrative placeholders.
+
+## Embeddings & images
+
+xAI does **not** currently expose a public embeddings endpoint, so `xai.embedder({...})` is wired for protocol parity but a call to `embed()` / `embedMany()` fails upstream — use a dedicated provider (e.g. `@warlock.js/ai-openai`) for vectors. `xai.image({...})` delegates to the wrapped OpenAI Images adapter, which only recognizes the `gpt-image-*` / `dall-e-*` families and rejects any other id at construction; xAI's image generation ("Grok Imagine") is a separate surface.
+
+## OpenAI-compatible endpoints
+
+Override `baseURL` (proxy / gateway) or `provider` (relabel the upstream):
+
+```ts
+new XaiSDK({
+  apiKey,
+  baseURL: "https://gateway.internal/x.ai/v1",
+  provider: "xai-proxy",
+});
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+Covers the wrapped-`OpenAISDK` `baseURL` / `provider` defaults and Grok capability inference.
+
+## License
+
+MIT

package/cjs/index.cjs

@@ -0,0 +1,225 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai_openai = require("@warlock.js/ai-openai");
+
+//#region ../@warlock.js/ai-xai/src/known-models.ts
+/**
+* Capability inference for xAI Grok model ids.
+*
+* xAI speaks the OpenAI Chat Completions protocol, so the wire-level
+* adapter is `OpenAISDK`. But Grok model names (`grok-4`,
+* `grok-2-vision`, …) don't match OpenAI's `gpt-*` / `o*` prefixes, so
+* OpenAI's own inference lists would mis-classify every Grok model as
+* non-vision / non-reasoning. This module supplies xAI's OWN name lists
+* and the `XaiSDK` wrapper injects the resulting capability flags into
+* each `OpenAIModelConfig` before delegating, so the right capabilities
+* are set even though the names aren't OpenAI names.
+*
+* All lists are matched as a prefix so dated / `-latest` / `-fast`
+* variants (`grok-4-0709`, `grok-2-vision-latest`,
+* `grok-3-mini-beta`) are covered without enumerating every release
+* tag. Devs can always override per-model via
+* `xai.model({ name, vision: true | false, reasoning: true | false })`
+* — explicit config wins over inference in either direction.
+*/
+/**
+* Model-name prefixes for Grok families that accept image input
+* (vision) on the OpenAI-compatible Chat Completions endpoint.
+*
+* - `grok-4` is natively multimodal (text + image input).
+* - `grok-2-vision` is the dedicated image-understanding Grok 2 model.
+*
+* Text-only families (`grok-3`, `grok-3-mini`, the base `grok-2`
+* text model) are intentionally excluded so passing an image
+* attachment to them surfaces a clear, agent-side capability error
+* rather than an opaque xAI 400.
+*/
+const XAI_VISION_MODEL_PREFIXES = ["grok-4", "grok-2-vision"];
+/**
+* Model-name prefixes for Grok families that expose internal reasoning
+* and accept reasoning controls (e.g. `reasoning_effort`) on the
+* OpenAI-compatible Chat Completions endpoint.
+*
+* - `grok-4` is a reasoning-first model (it always reasons).
+* - `grok-3-mini` is the "think" variant of Grok 3 and reasons; the
+*   full-size `grok-3` does not, so it is deliberately NOT covered by
+*   the `grok-3-mini` prefix.
+*/
+const XAI_REASONING_MODEL_PREFIXES = ["grok-4", "grok-3-mini"];
+/**
+* A convenience list of the current public Grok chat model ids, handy
+* for menus, validation, and docs. Not exhaustive of every dated alias
+* xAI publishes — pass any id through `xai.model({ name })`; the prefix
+* inference above handles dated / `-latest` variants.
+*
+* @example
+* XAI_CHAT_MODELS.includes("grok-4");          // → true
+*/
+const XAI_CHAT_MODELS = [
+	"grok-4",
+	"grok-3",
+	"grok-3-mini",
+	"grok-2-vision",
+	"grok-2"
+];
+/**
+* Infer whether a given Grok model id supports vision based on xAI's
+* known-prefix list. Unknown ids default to `false` so that passing an
+* image attachment to an unsupported model surfaces a clear,
+* agent-side capability error instead of an opaque xAI 400.
+*
+* @example
+* inferVisionCapability("grok-4");                 // → true
+* inferVisionCapability("grok-2-vision-latest");   // → true
+* inferVisionCapability("grok-3");                 // → false
+* inferVisionCapability("grok-3-mini");            // → false
+*/
+function inferVisionCapability(modelId) {
+	const normalized = modelId.toLowerCase();
+	return XAI_VISION_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+/**
+* Infer whether a given Grok model id is a reasoning model based on
+* xAI's known-prefix list. Unknown ids default to `false` so the
+* adapter never forwards an unsupported reasoning param to a
+* non-reasoning model.
+*
+* @example
+* inferReasoningCapability("grok-4");          // → true
+* inferReasoningCapability("grok-3-mini");     // → true
+* inferReasoningCapability("grok-3");          // → false
+* inferReasoningCapability("grok-2-vision");   // → false
+*/
+function inferReasoningCapability(modelId) {
+	const normalized = modelId.toLowerCase();
+	return XAI_REASONING_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+//#endregion
+//#region ../@warlock.js/ai-xai/src/sdk.ts
+/**
+* The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at
+* `POST /v1/chat/completions` on this host, so the whole adapter rides
+* on the OpenAI wire protocol.
+*/
+const XAI_BASE_URL = "https://api.x.ai/v1";
+/**
+* The default `provider` label stamped on every model this SDK
+* produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,
+* logs, and any provider-aware middleware.
+*/
+const XAI_PROVIDER = "xai";
+/**
+* xAI Grok-backed implementation of `SDKAdapterContract`.
+*
+* **Role.** The package entry point for xAI's Grok models. xAI speaks
+* the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*
+* over the already-battle-tested {@link OpenAISDK} from
+* `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one
+* internal `OpenAISDK` pointed at xAI's `baseURL` and labeled
+* `provider: "xai"`, then delegates `model()` / `embedder()` /
+* `image()` / `count()` to it. Construct one SDK per account and reuse
+* it everywhere.
+*
+* **Responsibility.**
+* - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,
+*   `provider` → `"xai"`) and this provider's OWN capability inference.
+*   Grok model names (`grok-4`, `grok-2-vision`, …) don't match
+*   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`
+*   the wrapper injects the `vision` / `reasoning` flags inferred from
+*   xAI's name lists (see `known-models.ts`). Because explicit config
+*   wins over OpenAI's inference inside `OpenAIModel`, the produced
+*   `ModelContract` carries the correct Grok capabilities.
+* - Does NOT own: the wire protocol, request/response mapping,
+*   streaming, tool-call accumulation, error wrapping, or pricing
+*   resolution — all of that is the wrapped `OpenAISDK`'s job and is
+*   reused verbatim.
+*
+* Modeled as a class (see §4.2 of code-style.md — "long-lived state
+* across many calls"): it holds one live `OpenAISDK` (which in turn
+* holds one live `OpenAI` client), fronted by FP usage like the other
+* adapters.
+*
+* @example
+* const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });
+* const model = xai.model({ name: "grok-4", temperature: 0.7 });
+* const myAgent = ai.agent({ model });
+*
+* @example
+* // Compose into an `ai.xai` namespace for ergonomic agent wiring.
+* const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };
+* const fast = ai.agent({ model: ai.xai.model({ name: "grok-3-mini" }) });
+*/
+var XaiSDK = class {
+	constructor(config) {
+		const { baseURL, provider, ...rest } = config;
+		this.openai = new _warlock_js_ai_openai.OpenAISDK({
+			...rest,
+			baseURL: baseURL ?? XAI_BASE_URL,
+			provider: provider ?? XAI_PROVIDER
+		});
+		this.pricing = config.pricing;
+	}
+	/**
+	* Build a `ModelContract` for a Grok model. Delegates to the wrapped
+	* `OpenAISDK.model()` after injecting this provider's OWN capability
+	* inference: `vision` and `reasoning` are resolved from xAI's
+	* name-prefix lists (see `known-models.ts`) unless the caller set them
+	* explicitly. Because explicit config wins over OpenAI's inference
+	* inside `OpenAIModel`, the returned model self-identifies as
+	* `provider: "xai"` and carries Grok's real capabilities even though
+	* the model name isn't an OpenAI name.
+	*
+	* Pricing resolution is left to the wrapped adapter: per-model
+	* `config.pricing` wins, otherwise the SDK-level registry entry keyed
+	* by `config.name`, otherwise `undefined` (no cost computed).
+	*
+	* @example
+	* xai.model({ name: "grok-4" });        // vision + reasoning auto-true
+	* xai.model({ name: "grok-3-mini" });   // reasoning auto-true, vision false
+	*/
+	model(config) {
+		return this.openai.model({
+			...config,
+			vision: config.vision ?? inferVisionCapability(config.name),
+			reasoning: config.reasoning ?? inferReasoningCapability(config.name)
+		});
+	}
+	/**
+	* Rough token-count estimate. Delegates straight to the wrapped
+	* `OpenAISDK.count()` (the shared character-heuristic from the core
+	* package — offline, good for budgeting/quota guards, not billing).
+	*/
+	async count(text, model) {
+		return this.openai.count(text, model);
+	}
+	/**
+	* Build an `EmbedderContract` by delegating to the wrapped
+	* `OpenAISDK.embedder()`.
+	*
+	* NOTE: xAI does not currently expose a public embeddings endpoint, so
+	* this is wired for protocol parity but a call to `embed()` /
+	* `embedMany()` will fail upstream. Point an embedder at a dedicated
+	* embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.
+	*/
+	embedder(config) {
+		return this.openai.embedder(config);
+	}
+	/**
+	* Build an `ImageModelContract` by delegating to the wrapped
+	* `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.
+	* Pricing resolution mirrors `model()` (per-model `pricing` > SDK
+	* registry > `undefined`).
+	*/
+	image(config) {
+		return this.openai.image(config);
+	}
+};
+
+//#endregion
+exports.XAI_CHAT_MODELS = XAI_CHAT_MODELS;
+exports.XAI_REASONING_MODEL_PREFIXES = XAI_REASONING_MODEL_PREFIXES;
+exports.XAI_VISION_MODEL_PREFIXES = XAI_VISION_MODEL_PREFIXES;
+exports.XaiSDK = XaiSDK;
+exports.inferReasoningCapability = inferReasoningCapability;
+exports.inferVisionCapability = inferVisionCapability;
+//# sourceMappingURL=index.cjs.map

package/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["OpenAISDK"],"sources":["../../../../../../@warlock.js/ai-xai/src/known-models.ts","../../../../../../@warlock.js/ai-xai/src/sdk.ts"],"sourcesContent":["/**\n * Capability inference for xAI Grok model ids.\n *\n * xAI speaks the OpenAI Chat Completions protocol, so the wire-level\n * adapter is `OpenAISDK`. But Grok model names (`grok-4`,\n * `grok-2-vision`, …) don't match OpenAI's `gpt-*` / `o*` prefixes, so\n * OpenAI's own inference lists would mis-classify every Grok model as\n * non-vision / non-reasoning. This module supplies xAI's OWN name lists\n * and the `XaiSDK` wrapper injects the resulting capability flags into\n * each `OpenAIModelConfig` before delegating, so the right capabilities\n * are set even though the names aren't OpenAI names.\n *\n * All lists are matched as a prefix so dated / `-latest` / `-fast`\n * variants (`grok-4-0709`, `grok-2-vision-latest`,\n * `grok-3-mini-beta`) are covered without enumerating every release\n * tag. Devs can always override per-model via\n * `xai.model({ name, vision: true | false, reasoning: true | false })`\n * — explicit config wins over inference in either direction.\n */\n\n/**\n * Model-name prefixes for Grok families that accept image input\n * (vision) on the OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is natively multimodal (text + image input).\n * - `grok-2-vision` is the dedicated image-understanding Grok 2 model.\n *\n * Text-only families (`grok-3`, `grok-3-mini`, the base `grok-2`\n * text model) are intentionally excluded so passing an image\n * attachment to them surfaces a clear, agent-side capability error\n * rather than an opaque xAI 400.\n */\nexport const XAI_VISION_MODEL_PREFIXES = [\"grok-4\", \"grok-2-vision\"] as const;\n\n/**\n * Model-name prefixes for Grok families that expose internal reasoning\n * and accept reasoning controls (e.g. `reasoning_effort`) on the\n * OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is a reasoning-first model (it always reasons).\n * - `grok-3-mini` is the \"think\" variant of Grok 3 and reasons; the\n *   full-size `grok-3` does not, so it is deliberately NOT covered by\n *   the `grok-3-mini` prefix.\n */\nexport const XAI_REASONING_MODEL_PREFIXES = [\"grok-4\", \"grok-3-mini\"] as const;\n\n/**\n * A convenience list of the current public Grok chat model ids, handy\n * for menus, validation, and docs. Not exhaustive of every dated alias\n * xAI publishes — pass any id through `xai.model({ name })`; the prefix\n * inference above handles dated / `-latest` variants.\n *\n * @example\n * XAI_CHAT_MODELS.includes(\"grok-4\");          // → true\n */\nexport const XAI_CHAT_MODELS = [\n  \"grok-4\",\n  \"grok-3\",\n  \"grok-3-mini\",\n  \"grok-2-vision\",\n  \"grok-2\",\n] as const;\n\n/**\n * Infer whether a given Grok model id supports vision based on xAI's\n * known-prefix list. Unknown ids default to `false` so that passing an\n * image attachment to an unsupported model surfaces a clear,\n * agent-side capability error instead of an opaque xAI 400.\n *\n * @example\n * inferVisionCapability(\"grok-4\");                 // → true\n * inferVisionCapability(\"grok-2-vision-latest\");   // → true\n * inferVisionCapability(\"grok-3\");                 // → false\n * inferVisionCapability(\"grok-3-mini\");            // → false\n */\nexport function inferVisionCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_VISION_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n\n/**\n * Infer whether a given Grok model id is a reasoning model based on\n * xAI's known-prefix list. Unknown ids default to `false` so the\n * adapter never forwards an unsupported reasoning param to a\n * non-reasoning model.\n *\n * @example\n * inferReasoningCapability(\"grok-4\");          // → true\n * inferReasoningCapability(\"grok-3-mini\");     // → true\n * inferReasoningCapability(\"grok-3\");          // → false\n * inferReasoningCapability(\"grok-2-vision\");   // → false\n */\nexport function inferReasoningCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_REASONING_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n","import type {\n  EmbedderContract,\n  ImageModelContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  XaiEmbedderConfig,\n  XaiImageConfig,\n  XaiModelConfig,\n  XaiSDKConfig,\n} from \"./config.type\";\nimport { inferReasoningCapability, inferVisionCapability } from \"./known-models\";\n\n/**\n * The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at\n * `POST /v1/chat/completions` on this host, so the whole adapter rides\n * on the OpenAI wire protocol.\n */\nconst XAI_BASE_URL = \"https://api.x.ai/v1\";\n\n/**\n * The default `provider` label stamped on every model this SDK\n * produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware.\n */\nconst XAI_PROVIDER = \"xai\";\n\n/**\n * xAI Grok-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for xAI's Grok models. xAI speaks\n * the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*\n * over the already-battle-tested {@link OpenAISDK} from\n * `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one\n * internal `OpenAISDK` pointed at xAI's `baseURL` and labeled\n * `provider: \"xai\"`, then delegates `model()` / `embedder()` /\n * `image()` / `count()` to it. Construct one SDK per account and reuse\n * it everywhere.\n *\n * **Responsibility.**\n * - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,\n *   `provider` → `\"xai\"`) and this provider's OWN capability inference.\n *   Grok model names (`grok-4`, `grok-2-vision`, …) don't match\n *   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`\n *   the wrapper injects the `vision` / `reasoning` flags inferred from\n *   xAI's name lists (see `known-models.ts`). Because explicit config\n *   wins over OpenAI's inference inside `OpenAIModel`, the produced\n *   `ModelContract` carries the correct Grok capabilities.\n * - Does NOT own: the wire protocol, request/response mapping,\n *   streaming, tool-call accumulation, error wrapping, or pricing\n *   resolution — all of that is the wrapped `OpenAISDK`'s job and is\n *   reused verbatim.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): it holds one live `OpenAISDK` (which in turn\n * holds one live `OpenAI` client), fronted by FP usage like the other\n * adapters.\n *\n * @example\n * const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });\n * const model = xai.model({ name: \"grok-4\", temperature: 0.7 });\n * const myAgent = ai.agent({ model });\n *\n * @example\n * // Compose into an `ai.xai` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };\n * const fast = ai.agent({ model: ai.xai.model({ name: \"grok-3-mini\" }) });\n */\nexport class XaiSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing the actual wire work.\n   * Constructed once with xAI's `baseURL` + `provider` and the caller's\n   * `apiKey` / client options, then reused for every produced model,\n   * embedder, and image model.\n   */\n  private readonly openai: OpenAISDK;\n\n  /**\n   * Optional SDK-level pricing registry, kept so `model()` can resolve\n   * a per-model entry while still applying this provider's default\n   * capability inference. The wrapped `OpenAISDK` also resolves\n   * pricing, but we surface it here for parity and to keep the default\n   * baseURL/provider injection in one place.\n   */\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: XaiSDKConfig) {\n    const { baseURL, provider, ...rest } = config;\n\n    // Inject xAI's defaults — `baseURL` → the xAI OpenAI-compatible\n    // endpoint, `provider` → \"xai\" — while still letting the caller\n    // override either (e.g. a corporate proxy or a relabeled gateway).\n    this.openai = new OpenAISDK({\n      ...rest,\n      baseURL: baseURL ?? XAI_BASE_URL,\n      provider: provider ?? XAI_PROVIDER,\n    });\n\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build a `ModelContract` for a Grok model. Delegates to the wrapped\n   * `OpenAISDK.model()` after injecting this provider's OWN capability\n   * inference: `vision` and `reasoning` are resolved from xAI's\n   * name-prefix lists (see `known-models.ts`) unless the caller set them\n   * explicitly. Because explicit config wins over OpenAI's inference\n   * inside `OpenAIModel`, the returned model self-identifies as\n   * `provider: \"xai\"` and carries Grok's real capabilities even though\n   * the model name isn't an OpenAI name.\n   *\n   * Pricing resolution is left to the wrapped adapter: per-model\n   * `config.pricing` wins, otherwise the SDK-level registry entry keyed\n   * by `config.name`, otherwise `undefined` (no cost computed).\n   *\n   * @example\n   * xai.model({ name: \"grok-4\" });        // vision + reasoning auto-true\n   * xai.model({ name: \"grok-3-mini\" });   // reasoning auto-true, vision false\n   */\n  public model(config: XaiModelConfig): ModelContract {\n    return this.openai.model({\n      ...config,\n      // xAI names don't match OpenAI's vision/reasoning prefixes, so we\n      // resolve them here and pass explicit flags through — explicit\n      // config always wins over the OpenAI adapter's own inference.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    });\n  }\n\n  /**\n   * Rough token-count estimate. Delegates straight to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package — offline, good for budgeting/quota guards, not billing).\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` by delegating to the wrapped\n   * `OpenAISDK.embedder()`.\n   *\n   * NOTE: xAI does not currently expose a public embeddings endpoint, so\n   * this is wired for protocol parity but a call to `embed()` /\n   * `embedMany()` will fail upstream. Point an embedder at a dedicated\n   * embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.\n   */\n  public embedder(config: XaiEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  /**\n   * Build an `ImageModelContract` by delegating to the wrapped\n   * `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.\n   * Pricing resolution mirrors `model()` (per-model `pricing` > SDK\n   * registry > `undefined`).\n   */\n  public image(config: XaiImageConfig): ImageModelContract {\n    return this.openai.image(config);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,4BAA4B,CAAC,UAAU,eAAe;;;;;;;;;;;AAYnE,MAAa,+BAA+B,CAAC,UAAU,aAAa;;;;;;;;;;AAWpE,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,SAA0B;CAC9D,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,0BAA0B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACjF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,SAA0B;CACjE,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,6BAA6B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACpF;;;;;;;;;AC5EA,MAAM,eAAe;;;;;;AAOrB,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrB,IAAa,SAAb,MAAkD;CAkBhD,AAAO,YAAY,QAAsB;EACvC,MAAM,EAAE,SAAS,UAAU,GAAG,SAAS;EAKvC,KAAK,SAAS,IAAIA,gCAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;EACxB,CAAC;EAED,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAAuC;EAClD,OAAO,KAAK,OAAO,MAAM;GACvB,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE,CAAC;CACH;;;;;;CAOA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;CAWA,AAAO,SAAS,QAA6C;EAC3D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;;;;;;;CAQA,AAAO,MAAM,QAA4C;EACvD,OAAO,KAAK,OAAO,MAAM,MAAM;CACjC;AACF"}

package/esm/config.type.d.mts

@@ -0,0 +1,108 @@
+import { OpenAISDKConfig } from "@warlock.js/ai-openai";
+import { EmbedderConfig, ImageModelConfig, ModelConfig } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-xai/src/config.type.d.ts
+/**
+ * Configuration for the xAI Grok SDK adapter.
+ *
+ * xAI speaks the OpenAI Chat Completions protocol, so `XaiSDK` is a thin
+ * wrapper over `OpenAISDK` and this config is the same `OpenAISDKConfig`
+ * shape (every upstream `ClientOptions` value — `timeout`, `maxRetries`,
+ * `defaultHeaders`, `fetch`, `organization`, … — is forwarded verbatim).
+ *
+ * The two xAI-specific defaults are applied by the wrapper, so neither
+ * is required:
+ * - `baseURL` defaults to `https://api.x.ai/v1` (the xAI
+ *   OpenAI-compatible endpoint). Override only to target a proxy/gateway.
+ * - `provider` defaults to `"xai"` — flows through to
+ *   `ModelContract.provider`, `AgentReport.model.provider`, logs, and any
+ *   provider-aware middleware. Set it to relabel a gateway upstream.
+ *
+ * `apiKey` is still required (your xAI API key); everything else is
+ * optional. `pricing` is an optional SDK-level registry keyed by model
+ * name — resolution at `model()` call time: per-model `pricing` > this
+ * SDK registry > `undefined` (no cost computed).
+ *
+ * @example
+ * new XaiSDK({ apiKey: process.env.XAI_API_KEY! });
+ *
+ * @example
+ * // Custom proxy + SDK-level pricing (USD per 1M tokens).
+ * new XaiSDK({
+ *   apiKey,
+ *   baseURL: "https://gateway.internal/x.ai/v1",
+ *   pricing: { "grok-4": { input: 3, output: 15 } },
+ * });
+ */
+type XaiSDKConfig = OpenAISDKConfig;
+/**
+ * Per-model configuration for `XaiSDK.model()`. `name` is the Grok model
+ * id (e.g. `"grok-4"`, `"grok-3"`, `"grok-3-mini"`, `"grok-2-vision"`).
+ *
+ * The wrapper injects xAI's OWN capability inference (see
+ * `known-models.ts`) before delegating to `OpenAISDK.model()`, so Grok
+ * model names resolve to the right `vision` / `reasoning` flags even
+ * though they don't match OpenAI's `gpt-*` / `o*` prefixes. Any explicit
+ * value below still wins over that inference.
+ *
+ * @example
+ * xai.model({ name: "grok-4" });                  // vision + reasoning auto-true
+ * xai.model({ name: "grok-3-mini" });             // reasoning auto-true
+ * xai.model({ name: "grok-2-vision" });           // vision auto-true
+ * xai.model({ name: "grok-3", vision: true });    // explicit capability override
+ */
+type XaiModelConfig = ModelConfig & {
+  /**
+   * Override the auto-inferred vision capability. When omitted, the
+   * adapter checks the model id against xAI's known vision families
+   * (`grok-4`, `grok-2-vision`; see `known-models.ts`). Explicit
+   * `true`/`false` always wins over inference — useful for new Grok
+   * variants or a gateway exposing vision under a custom name.
+   */
+  vision?: boolean;
+  /**
+   * Override the auto-inferred reasoning capability. When omitted, the
+   * adapter checks the model id against xAI's known reasoning families
+   * (`grok-4`, `grok-3-mini`; see `known-models.ts`). When capable,
+   * `ModelCallOptions.reasoning.effort` is forwarded to the
+   * OpenAI-compatible `reasoning_effort` param. Explicit `true`/`false`
+   * always wins over inference.
+   */
+  reasoning?: boolean;
+  /**
+   * Override the inferred `structuredOutput` capability. xAI supports
+   * JSON-schema structured outputs on the Chat Completions endpoint, so
+   * the wrapper leaves this to the underlying OpenAI adapter (default
+   * `true`). Set `false` for a model/route that rejects strict
+   * `json_schema` — the agent then re-injects a soft schema hint.
+   */
+  structuredOutput?: boolean;
+};
+/**
+ * Per-embedder configuration for `XaiSDK.embedder()`. Mirrors the
+ * neutral {@link EmbedderConfig}.
+ *
+ * NOTE: xAI does not currently expose a public embeddings endpoint, so
+ * `embedder()` is wired for protocol parity but a call will fail
+ * upstream. Use a dedicated embeddings provider (e.g.
+ * `@warlock.js/ai-openai`) for vectors.
+ *
+ * @example
+ * xai.embedder({ name: "text-embedding-3-small" }); // delegates; xAI has no embeddings API yet
+ */
+type XaiEmbedderConfig = EmbedderConfig;
+/**
+ * Per-model configuration for `XaiSDK.image()`. Mirrors the neutral
+ * {@link ImageModelConfig}.
+ *
+ * NOTE: `image()` delegates to the wrapped OpenAI Images adapter, which
+ * only recognizes the `gpt-image-*` / `dall-e-*` families and rejects
+ * any other id at construction. xAI's image generation ("Grok Imagine")
+ * is a separate surface, so this hook exists for protocol parity rather
+ * than a verified Grok image model. Use `@warlock.js/ai-openai`'s
+ * `image()` for OpenAI-Images-compatible generation.
+ */
+type XaiImageConfig = ImageModelConfig;
+//#endregion
+export { XaiEmbedderConfig, XaiImageConfig, XaiModelConfig, XaiSDKConfig };
+//# sourceMappingURL=config.type.d.mts.map

package/esm/config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-xai/src/config.type.ts"],"mappings":";;;;;;AAwCA;;;;AAA0C;AAkB1C;;;;;;;;;AAyBkB;AAelB;;;;AAA8C;AAa9C;;;;AAA6C;;;;;;KAvEjC,YAAA,GAAe,eAAe;;;;;;;;;;;;;;;;;KAkB9B,cAAA,GAAiB,WAAW;;;;;;;;EAQtC,MAAA;;;;;;;;;EASA,SAAA;;;;;;;;EAQA,gBAAA;AAAA;;;;;;;;;;;;;KAeU,iBAAA,GAAoB,cAAc;;;;;;;;;;;;KAalC,cAAA,GAAiB,gBAAgB"}

package/esm/index.d.mts

@@ -0,0 +1,4 @@
+import { XaiEmbedderConfig, XaiImageConfig, XaiModelConfig, XaiSDKConfig } from "./config.type.mjs";
+import { XaiSDK } from "./sdk.mjs";
+import { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+export { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, type XaiEmbedderConfig, type XaiImageConfig, type XaiModelConfig, XaiSDK, type XaiSDKConfig, inferReasoningCapability, inferVisionCapability };

package/esm/index.mjs

@@ -0,0 +1,4 @@
+import { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+import { XaiSDK } from "./sdk.mjs";
+
+export { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, XaiSDK, inferReasoningCapability, inferVisionCapability };

package/esm/known-models.d.mts

@@ -0,0 +1,83 @@
+//#region ../@warlock.js/ai-xai/src/known-models.d.ts
+/**
+ * Capability inference for xAI Grok model ids.
+ *
+ * xAI speaks the OpenAI Chat Completions protocol, so the wire-level
+ * adapter is `OpenAISDK`. But Grok model names (`grok-4`,
+ * `grok-2-vision`, …) don't match OpenAI's `gpt-*` / `o*` prefixes, so
+ * OpenAI's own inference lists would mis-classify every Grok model as
+ * non-vision / non-reasoning. This module supplies xAI's OWN name lists
+ * and the `XaiSDK` wrapper injects the resulting capability flags into
+ * each `OpenAIModelConfig` before delegating, so the right capabilities
+ * are set even though the names aren't OpenAI names.
+ *
+ * All lists are matched as a prefix so dated / `-latest` / `-fast`
+ * variants (`grok-4-0709`, `grok-2-vision-latest`,
+ * `grok-3-mini-beta`) are covered without enumerating every release
+ * tag. Devs can always override per-model via
+ * `xai.model({ name, vision: true | false, reasoning: true | false })`
+ * — explicit config wins over inference in either direction.
+ */
+/**
+ * Model-name prefixes for Grok families that accept image input
+ * (vision) on the OpenAI-compatible Chat Completions endpoint.
+ *
+ * - `grok-4` is natively multimodal (text + image input).
+ * - `grok-2-vision` is the dedicated image-understanding Grok 2 model.
+ *
+ * Text-only families (`grok-3`, `grok-3-mini`, the base `grok-2`
+ * text model) are intentionally excluded so passing an image
+ * attachment to them surfaces a clear, agent-side capability error
+ * rather than an opaque xAI 400.
+ */
+declare const XAI_VISION_MODEL_PREFIXES: readonly ["grok-4", "grok-2-vision"];
+/**
+ * Model-name prefixes for Grok families that expose internal reasoning
+ * and accept reasoning controls (e.g. `reasoning_effort`) on the
+ * OpenAI-compatible Chat Completions endpoint.
+ *
+ * - `grok-4` is a reasoning-first model (it always reasons).
+ * - `grok-3-mini` is the "think" variant of Grok 3 and reasons; the
+ *   full-size `grok-3` does not, so it is deliberately NOT covered by
+ *   the `grok-3-mini` prefix.
+ */
+declare const XAI_REASONING_MODEL_PREFIXES: readonly ["grok-4", "grok-3-mini"];
+/**
+ * A convenience list of the current public Grok chat model ids, handy
+ * for menus, validation, and docs. Not exhaustive of every dated alias
+ * xAI publishes — pass any id through `xai.model({ name })`; the prefix
+ * inference above handles dated / `-latest` variants.
+ *
+ * @example
+ * XAI_CHAT_MODELS.includes("grok-4");          // → true
+ */
+declare const XAI_CHAT_MODELS: readonly ["grok-4", "grok-3", "grok-3-mini", "grok-2-vision", "grok-2"];
+/**
+ * Infer whether a given Grok model id supports vision based on xAI's
+ * known-prefix list. Unknown ids default to `false` so that passing an
+ * image attachment to an unsupported model surfaces a clear,
+ * agent-side capability error instead of an opaque xAI 400.
+ *
+ * @example
+ * inferVisionCapability("grok-4");                 // → true
+ * inferVisionCapability("grok-2-vision-latest");   // → true
+ * inferVisionCapability("grok-3");                 // → false
+ * inferVisionCapability("grok-3-mini");            // → false
+ */
+declare function inferVisionCapability(modelId: string): boolean;
+/**
+ * Infer whether a given Grok model id is a reasoning model based on
+ * xAI's known-prefix list. Unknown ids default to `false` so the
+ * adapter never forwards an unsupported reasoning param to a
+ * non-reasoning model.
+ *
+ * @example
+ * inferReasoningCapability("grok-4");          // → true
+ * inferReasoningCapability("grok-3-mini");     // → true
+ * inferReasoningCapability("grok-3");          // → false
+ * inferReasoningCapability("grok-2-vision");   // → false
+ */
+declare function inferReasoningCapability(modelId: string): boolean;
+//#endregion
+export { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, inferReasoningCapability, inferVisionCapability };
+//# sourceMappingURL=known-models.d.mts.map

package/esm/known-models.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-models.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai-xai/src/known-models.ts"],"mappings":";;AAgCA;;;;AAA6E;AAY7E;;;;AAA8E;AAW9E;;;;AAMU;AAcV;;;;AAAqD;AAkBrD;;;;AAAwD;;;;;;cA7D3C,yBAAA;;;;;;;;;;;cAYA,4BAAA;;;;;;;;;;cAWA,eAAA;;;;;;;;;;;;;iBAoBG,qBAAA,CAAsB,OAAe;;;;;;;;;;;;;iBAkBrC,wBAAA,CAAyB,OAAe"}