@core-ai/xai 0.25.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +85 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.js +150 -0
- package/package.json +62 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Omnifact (https://omnifact.ai)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# @core-ai/xai
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@core-ai/xai)
|
|
4
|
+
|
|
5
|
+
xAI (Grok) provider package for `@core-ai/core-ai`.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @core-ai/core-ai @core-ai/xai zod
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { generate } from '@core-ai/core-ai';
|
|
17
|
+
import { createXAI } from '@core-ai/xai';
|
|
18
|
+
|
|
19
|
+
const xai = createXAI({
|
|
20
|
+
apiKey: process.env.XAI_API_KEY,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const model = xai.chatModel('grok-4.7');
|
|
24
|
+
|
|
25
|
+
const result = await generate({
|
|
26
|
+
model,
|
|
27
|
+
messages: [{ role: 'user', content: 'Explain quantum tunneling briefly.' }],
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
console.log(result.content);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
By default, requests go to `https://api.x.ai/v1`. Set `baseURL` to use a custom or regional endpoint.
|
|
34
|
+
|
|
35
|
+
## Responses and Chat Completions
|
|
36
|
+
|
|
37
|
+
`xai.chatModel()` uses xAI's Responses API, the recommended API for Grok models. Requests are stateless: the provider sends `store: false` and round-trips encrypted reasoning content instead of relying on server-side conversation state.
|
|
38
|
+
|
|
39
|
+
`xai.chat.chatModel()` uses the legacy Chat Completions API.
|
|
40
|
+
|
|
41
|
+
## Reasoning
|
|
42
|
+
|
|
43
|
+
| Model | Reasoning | Effort control |
|
|
44
|
+
| -------------------------------------------------------------------------- | ------------- | ------------------------------ |
|
|
45
|
+
| `grok-4.7`, `grok-4.6`, `grok-4.5`, `grok-4.3` | Always on | `low`, `medium`, `high`, `max` |
|
|
46
|
+
| `grok-4.20-0309-reasoning`, `grok-4.20-multi-agent-0309`, `grok-build-0.1` | Always on | None |
|
|
47
|
+
| `grok-4.20-0309-non-reasoning` | Not supported | None |
|
|
48
|
+
|
|
49
|
+
`max` is sent to xAI as `xhigh`. `minimal` is clamped to `low`. Models without effort control never receive an effort parameter.
|
|
50
|
+
|
|
51
|
+
Reasoning is preserved across turns when you pass `resultToMessage(result)` back in `messages`: as encrypted reasoning items on the Responses API, and as `reasoning_content` on Chat Completions.
|
|
52
|
+
|
|
53
|
+
## Usage reporting
|
|
54
|
+
|
|
55
|
+
`usage.outputTokens` always includes reasoning tokens on both APIs. xAI's Chat Completions API reports reasoning tokens separately from `completion_tokens`; the provider adds them.
|
|
56
|
+
|
|
57
|
+
## Structured output and tools
|
|
58
|
+
|
|
59
|
+
`generateObject()` and `streamObject()` use xAI's native `json_schema` structured output. Every Grok model supports strict tool schemas (`strict: true` on a tool) and accepts text and image input.
|
|
60
|
+
|
|
61
|
+
## Provider options
|
|
62
|
+
|
|
63
|
+
Pass xAI-specific options via `providerOptions.xai`:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
await generate({
|
|
67
|
+
model: xai.chatModel('grok-4.7'),
|
|
68
|
+
messages: [{ role: 'user', content: 'Hello' }],
|
|
69
|
+
providerOptions: {
|
|
70
|
+
xai: {
|
|
71
|
+
promptCacheKey: 'conversation-42',
|
|
72
|
+
parallelToolCalls: false,
|
|
73
|
+
},
|
|
74
|
+
},
|
|
75
|
+
});
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- Responses API: `store`, `include`, `parallelToolCalls`, `user`, `promptCacheKey`
|
|
79
|
+
- Chat Completions API: `parallelToolCalls`, `seed`, `user`
|
|
80
|
+
|
|
81
|
+
Stop sequences and frequency/presence penalties are not available: xAI reasoning models reject them.
|
|
82
|
+
|
|
83
|
+
## Not supported
|
|
84
|
+
|
|
85
|
+
Embeddings, image generation, and xAI's server-side tools (web search, X search, code execution, remote MCP) are not available through this package.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { ChatModel } from '@core-ai/core-ai';
|
|
2
|
+
import { OpenAIProviderBaseOptions } from '@core-ai/openai';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
|
|
5
|
+
type XAIProviderOptions = OpenAIProviderBaseOptions;
|
|
6
|
+
type XAIProvider = {
|
|
7
|
+
/** Responses API — xAI's recommended surface. */
|
|
8
|
+
chatModel(modelId: string): ChatModel;
|
|
9
|
+
/** Legacy Chat Completions API. */
|
|
10
|
+
chat: {
|
|
11
|
+
chatModel(modelId: string): ChatModel;
|
|
12
|
+
};
|
|
13
|
+
};
|
|
14
|
+
declare function createXAI(options?: XAIProviderOptions): XAIProvider;
|
|
15
|
+
|
|
16
|
+
declare const DEFAULT_BASE_URL = "https://api.x.ai/v1";
|
|
17
|
+
|
|
18
|
+
declare const xaiResponsesGenerateProviderOptionsSchema: z.ZodObject<{
|
|
19
|
+
store: z.ZodOptional<z.ZodBoolean>;
|
|
20
|
+
include: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
21
|
+
parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
|
|
22
|
+
user: z.ZodOptional<z.ZodString>;
|
|
23
|
+
promptCacheKey: z.ZodOptional<z.ZodString>;
|
|
24
|
+
}, z.core.$strict>;
|
|
25
|
+
declare const xaiChatGenerateProviderOptionsSchema: z.ZodObject<{
|
|
26
|
+
parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
|
|
27
|
+
user: z.ZodOptional<z.ZodString>;
|
|
28
|
+
seed: z.ZodOptional<z.ZodNumber>;
|
|
29
|
+
}, z.core.$strict>;
|
|
30
|
+
type XAIResponsesGenerateProviderOptions = z.infer<typeof xaiResponsesGenerateProviderOptionsSchema>;
|
|
31
|
+
type XAIChatGenerateProviderOptions = z.infer<typeof xaiChatGenerateProviderOptionsSchema>;
|
|
32
|
+
declare module '@core-ai/core-ai' {
|
|
33
|
+
interface GenerateProviderOptions {
|
|
34
|
+
xai?: XAIResponsesGenerateProviderOptions | XAIChatGenerateProviderOptions;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
type XAIReasoningMetadata = {
|
|
38
|
+
encryptedContent?: string;
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
export { DEFAULT_BASE_URL, type XAIChatGenerateProviderOptions, type XAIProvider, type XAIProviderOptions, type XAIReasoningMetadata, type XAIResponsesGenerateProviderOptions, createXAI, xaiChatGenerateProviderOptionsSchema, xaiResponsesGenerateProviderOptionsSchema };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
// src/provider.ts
|
|
2
|
+
import {
|
|
3
|
+
createOpenAIProvider
|
|
4
|
+
} from "@core-ai/openai";
|
|
5
|
+
|
|
6
|
+
// src/constants.ts
|
|
7
|
+
var DEFAULT_BASE_URL = "https://api.x.ai/v1";
|
|
8
|
+
|
|
9
|
+
// src/model-capabilities.ts
|
|
10
|
+
import {
|
|
11
|
+
SUPPORTED_TOOL_SCHEMA_STRICTNESS,
|
|
12
|
+
UNKNOWN_MODEL
|
|
13
|
+
} from "@core-ai/core-ai";
|
|
14
|
+
var CONFIGURABLE_EFFORTS = [
|
|
15
|
+
"low",
|
|
16
|
+
"medium",
|
|
17
|
+
"high",
|
|
18
|
+
"max"
|
|
19
|
+
];
|
|
20
|
+
var NO_EFFORTS = [];
|
|
21
|
+
var XAI_MODALITIES = {
|
|
22
|
+
input: ["text", "image"],
|
|
23
|
+
output: ["text"]
|
|
24
|
+
};
|
|
25
|
+
function createCapabilities(mode, supportedEfforts) {
|
|
26
|
+
return {
|
|
27
|
+
reasoning: {
|
|
28
|
+
mode,
|
|
29
|
+
supportedEfforts,
|
|
30
|
+
// xAI rejects stop sequences and penalties on reasoning models,
|
|
31
|
+
// not temperature / topP; those are excluded via provider options.
|
|
32
|
+
restrictsSamplingParams: false,
|
|
33
|
+
supportedToolChoices: ["auto", "none", "required", "tool"]
|
|
34
|
+
},
|
|
35
|
+
modalities: XAI_MODALITIES,
|
|
36
|
+
tools: {
|
|
37
|
+
strictSchemas: SUPPORTED_TOOL_SCHEMA_STRICTNESS
|
|
38
|
+
}
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
var CONFIGURABLE_REASONING = createCapabilities(
|
|
42
|
+
"always-on",
|
|
43
|
+
CONFIGURABLE_EFFORTS
|
|
44
|
+
);
|
|
45
|
+
var FIXED_REASONING = createCapabilities("always-on", NO_EFFORTS);
|
|
46
|
+
var NO_REASONING = createCapabilities("unsupported", NO_EFFORTS);
|
|
47
|
+
var XAI_MODEL_CAPABILITIES = {
|
|
48
|
+
// New Grok models have all been reasoning models with effort control.
|
|
49
|
+
[UNKNOWN_MODEL]: CONFIGURABLE_REASONING,
|
|
50
|
+
"grok-4.7": CONFIGURABLE_REASONING,
|
|
51
|
+
"grok-4.6": CONFIGURABLE_REASONING,
|
|
52
|
+
"grok-4.5": CONFIGURABLE_REASONING,
|
|
53
|
+
"grok-4.5-latest": CONFIGURABLE_REASONING,
|
|
54
|
+
"grok-build-latest": CONFIGURABLE_REASONING,
|
|
55
|
+
"grok-4.3": CONFIGURABLE_REASONING,
|
|
56
|
+
"grok-4.3-latest": CONFIGURABLE_REASONING,
|
|
57
|
+
"grok-4.20-0309-reasoning": FIXED_REASONING,
|
|
58
|
+
"grok-4.20-0309": FIXED_REASONING,
|
|
59
|
+
"grok-4.20": FIXED_REASONING,
|
|
60
|
+
"grok-4.20-reasoning": FIXED_REASONING,
|
|
61
|
+
"grok-4.20-reasoning-latest": FIXED_REASONING,
|
|
62
|
+
"grok-4.20-reasoning-gv2": FIXED_REASONING,
|
|
63
|
+
"grok-4.20-beta": FIXED_REASONING,
|
|
64
|
+
"grok-4.20-beta-0309": FIXED_REASONING,
|
|
65
|
+
"grok-4.20-beta-0309-reasoning": FIXED_REASONING,
|
|
66
|
+
"grok-4.20-beta-latest": FIXED_REASONING,
|
|
67
|
+
"grok-4.20-beta-latest-reasoning": FIXED_REASONING,
|
|
68
|
+
"grok-4.20-beta-reasoning": FIXED_REASONING,
|
|
69
|
+
"grok-4.20-experimental-beta-0304": FIXED_REASONING,
|
|
70
|
+
"grok-4.20-experimental-beta-0304-reasoning": FIXED_REASONING,
|
|
71
|
+
"grok-4.20-experimental-beta-latest": FIXED_REASONING,
|
|
72
|
+
"grok-4.20-experimental-beta-reasoning-latest": FIXED_REASONING,
|
|
73
|
+
"grok-4.20-multi-agent-0309": FIXED_REASONING,
|
|
74
|
+
"grok-4.20-multi-agent": FIXED_REASONING,
|
|
75
|
+
"grok-4.20-multi-agent-latest": FIXED_REASONING,
|
|
76
|
+
"grok-4.20-multi-agent-beta-0309": FIXED_REASONING,
|
|
77
|
+
"grok-4.20-multi-agent-beta-latest": FIXED_REASONING,
|
|
78
|
+
"grok-4.20-multi-agent-experimental-beta-0304": FIXED_REASONING,
|
|
79
|
+
"grok-4.20-multi-agent-experimental-beta-latest": FIXED_REASONING,
|
|
80
|
+
"grok-build-0.1": FIXED_REASONING,
|
|
81
|
+
"grok-code-fast-1": FIXED_REASONING,
|
|
82
|
+
"grok-code-fast-1-0825": FIXED_REASONING,
|
|
83
|
+
"grok-code-fast": FIXED_REASONING,
|
|
84
|
+
"grok-4.20-0309-non-reasoning": NO_REASONING,
|
|
85
|
+
"grok-4.20-non-reasoning": NO_REASONING,
|
|
86
|
+
"grok-4.20-non-reasoning-latest": NO_REASONING,
|
|
87
|
+
"grok-4.20-non-reasoning-gv2": NO_REASONING,
|
|
88
|
+
"grok-4.20-beta-non-reasoning": NO_REASONING,
|
|
89
|
+
"grok-4.20-beta-0309-non-reasoning": NO_REASONING,
|
|
90
|
+
"grok-4.20-beta-latest-non-reasoning": NO_REASONING,
|
|
91
|
+
"grok-4.20-experimental-beta-0304-non-reasoning": NO_REASONING,
|
|
92
|
+
"grok-4.20-experimental-beta-non-reasoning-latest": NO_REASONING
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
// src/provider-options.ts
|
|
96
|
+
import {
|
|
97
|
+
openaiChatGenerateProviderOptionsSchema,
|
|
98
|
+
openaiResponsesGenerateProviderOptionsSchema
|
|
99
|
+
} from "@core-ai/openai";
|
|
100
|
+
var xaiResponsesGenerateProviderOptionsSchema = openaiResponsesGenerateProviderOptionsSchema.pick({
|
|
101
|
+
store: true,
|
|
102
|
+
include: true,
|
|
103
|
+
parallelToolCalls: true,
|
|
104
|
+
user: true,
|
|
105
|
+
promptCacheKey: true
|
|
106
|
+
});
|
|
107
|
+
var xaiChatGenerateProviderOptionsSchema = openaiChatGenerateProviderOptionsSchema.pick({
|
|
108
|
+
parallelToolCalls: true,
|
|
109
|
+
seed: true,
|
|
110
|
+
user: true
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
// src/provider.ts
|
|
114
|
+
function createXAI(options = {}) {
|
|
115
|
+
if (!options.apiKey && !options.client) {
|
|
116
|
+
throw new Error("createXAI: apiKey is required.");
|
|
117
|
+
}
|
|
118
|
+
const provider = createOpenAIProvider(
|
|
119
|
+
{
|
|
120
|
+
...options,
|
|
121
|
+
baseURL: options.baseURL ?? DEFAULT_BASE_URL
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
modelCapabilities: XAI_MODEL_CAPABILITIES,
|
|
125
|
+
providerId: "xai",
|
|
126
|
+
providerOptionsSchema: xaiChatGenerateProviderOptionsSchema,
|
|
127
|
+
responsesProviderOptionsSchema: xaiResponsesGenerateProviderOptionsSchema,
|
|
128
|
+
compatibility: {
|
|
129
|
+
reasoning: {
|
|
130
|
+
requestField: "reasoning_content"
|
|
131
|
+
},
|
|
132
|
+
structuredOutputMode: "json-schema",
|
|
133
|
+
maxTokensParameter: "max_completion_tokens",
|
|
134
|
+
// Chat Completions reports reasoning tokens outside
|
|
135
|
+
// `completion_tokens`; the Responses API includes them.
|
|
136
|
+
reasoningTokenAccounting: "separate"
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
);
|
|
140
|
+
return {
|
|
141
|
+
chatModel: provider.chatModel,
|
|
142
|
+
chat: provider.chat
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
export {
|
|
146
|
+
DEFAULT_BASE_URL,
|
|
147
|
+
createXAI,
|
|
148
|
+
xaiChatGenerateProviderOptionsSchema,
|
|
149
|
+
xaiResponsesGenerateProviderOptionsSchema
|
|
150
|
+
};
|
package/package.json
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@core-ai/xai",
|
|
3
|
+
"version": "0.25.0",
|
|
4
|
+
"description": "xAI (Grok) provider package for @core-ai/core-ai",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Omnifact (https://omnifact.ai)",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/agdevhq/core-ai.git",
|
|
10
|
+
"directory": "packages/xai"
|
|
11
|
+
},
|
|
12
|
+
"keywords": [
|
|
13
|
+
"llm",
|
|
14
|
+
"ai",
|
|
15
|
+
"xai",
|
|
16
|
+
"grok",
|
|
17
|
+
"provider",
|
|
18
|
+
"sdk"
|
|
19
|
+
],
|
|
20
|
+
"type": "module",
|
|
21
|
+
"main": "./dist/index.js",
|
|
22
|
+
"types": "./dist/index.d.ts",
|
|
23
|
+
"exports": {
|
|
24
|
+
".": {
|
|
25
|
+
"types": "./dist/index.d.ts",
|
|
26
|
+
"import": "./dist/index.js",
|
|
27
|
+
"require": "./dist/index.js",
|
|
28
|
+
"default": "./dist/index.js"
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
"files": [
|
|
32
|
+
"dist",
|
|
33
|
+
"README.md",
|
|
34
|
+
"LICENSE"
|
|
35
|
+
],
|
|
36
|
+
"publishConfig": {
|
|
37
|
+
"access": "public",
|
|
38
|
+
"provenance": true
|
|
39
|
+
},
|
|
40
|
+
"scripts": {
|
|
41
|
+
"build": "tsup",
|
|
42
|
+
"lint": "eslint src/ --max-warnings 0",
|
|
43
|
+
"check-types": "tsc --noEmit",
|
|
44
|
+
"test": "vitest run",
|
|
45
|
+
"test:watch": "vitest"
|
|
46
|
+
},
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"@core-ai/core-ai": "^0.25.0",
|
|
49
|
+
"@core-ai/openai": "^0.25.0"
|
|
50
|
+
},
|
|
51
|
+
"peerDependencies": {
|
|
52
|
+
"zod": "^4.0.0"
|
|
53
|
+
},
|
|
54
|
+
"devDependencies": {
|
|
55
|
+
"@core-ai/eslint-config": "*",
|
|
56
|
+
"@core-ai/testing": "*",
|
|
57
|
+
"@core-ai/typescript-config": "*",
|
|
58
|
+
"openai": "^6.47.0",
|
|
59
|
+
"typescript": "^5.7.3",
|
|
60
|
+
"vitest": "^3.2.4"
|
|
61
|
+
}
|
|
62
|
+
}
|