@standardagents/xai 0.0.1-dev.ffffff → 0.14.0

package/LICENSE.txt

@@ -0,0 +1,48 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2025 FormKit Inc. All Rights Reserved.
+
+UNLICENSED - DO NOT USE
+
+This software and associated documentation files (the "Software") are the sole
+and exclusive property of FormKit Inc. ("FormKit").
+
+USE RESTRICTIONS
+
+The Software is UNLICENSED and proprietary. NO PERMISSION is granted to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, or to permit persons to whom the Software is furnished to do so,
+under any circumstances, without prior written authorization from FormKit Inc.
+
+UNAUTHORIZED USE PROHIBITED
+
+Any use of this Software without a valid, written license agreement signed by
+authorized officers of FormKit Inc. is strictly prohibited and constitutes
+unauthorized use and infringement of FormKit's intellectual property rights.
+
+LICENSING INQUIRIES
+
+Organizations interested in licensing this Software should contact:
+enterprise@formkit.com
+
+A written license agreement must be executed before any use of this Software
+is authorized.
+
+NO WARRANTY
+
+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
+FORMKIT INC. 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.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with the laws
+of the jurisdiction in which FormKit Inc. is incorporated, without regard to
+its conflict of law provisions.
+
+FormKit Inc.
+https://formkit.com
+enterprise@formkit.com

package/README.md

@@ -1,7 +1,134 @@
 # @standardagents/xai
 
-Stub prerelease package for Standard Agents xAI provider publishing setup.
+xAI provider for Standard Agents.
 
-Current bootstrap version: `0.0.1-dev.ffffff`
+This package integrates xAI chat and image models through the Standard Agents provider interface. It uses the official `@ai-sdk/xai` integration under the hood and handles:
 
-This package will be wired into the normal monorepo release flow after trusted publishing is configured.
+- text generation and streaming
+- multimodal chat requests with image inputs
+- local function tools on supported Grok models
+- xAI reasoning controls where supported
+- image generation and edit-style requests
+- usage and cost extraction from xAI API responses
+
+## Install
+
+```bash
+npm install @standardagents/xai @standardagents/spec
+```
+
+## Usage
+
+```ts
+import { xai } from '@standardagents/xai';
+
+const provider = xai({
+  apiKey: process.env.XAI_API_KEY!,
+});
+
+const result = await provider.generate({
+  model: 'grok-4-0709',
+  messages: [
+    { role: 'user', content: 'Write a short tagline for a robotics startup.' },
+  ],
+});
+
+console.log(result.content);
+console.log(result.usage?.cost);
+```
+
+## Factory
+
+The package exports:
+
+- `xai(config)` - provider factory
+- `XAIProvider` - provider class
+- `xaiProviderOptions` - Zod schema for provider-specific options
+
+Factory config:
+
+```ts
+type ProviderFactoryConfig = {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+};
+```
+
+## Supported Features
+
+Depending on the model, the provider supports:
+
+- streaming chat
+- images in chat input
+- local function tool calling
+- JSON mode
+- reasoning controls
+- image generation output
+
+The package includes a curated static catalog for current xAI text and image models, including Grok aliases.
+
+```ts
+const models = await provider.getModels?.();
+const capabilities = await provider.getModelCapabilities?.('grok-4.20-0309-reasoning');
+```
+
+## Provider Options
+
+Common xAI-specific provider options:
+
+- `reasoningEffort`
+- `logprobs`
+- `topLogprobs`
+- `parallel_function_calling`
+- `searchParameters`
+- `aspect_ratio`
+- `output_format`
+- `sync_mode`
+- `resolution`
+- `quality`
+- `numberOfImages`
+
+Example:
+
+```ts
+const result = await provider.generate({
+  model: 'grok-4-0709',
+  messages: [{ role: 'user', content: 'Search the web and summarize today in one paragraph.' }],
+  providerOptions: {
+    reasoningEffort: 'high',
+    searchParameters: {
+      mode: 'auto',
+      returnCitations: true,
+      sources: [{ type: 'web', safeSearch: true }],
+    },
+  },
+});
+```
+
+## Images
+
+For chat models, the provider translates Standard Agents image parts and image attachments into xAI image inputs. For xAI image generation models, it routes image requests through the image generation path and returns generated image attachments in the Standard Agents response format.
+
+## Cost Data
+
+When xAI returns `cost_in_usd_ticks`, this package converts it to USD and attaches the monetary value to `usage.cost`. That means xAI responses can log actual API-reported cost instead of relying only on token-price fallback tables.
+
+## Debugging
+
+Use `inspectRequest()` to view the xAI-native request body that will be sent to the provider:
+
+```ts
+const inspected = await provider.inspectRequest?.({
+  model: 'grok-4.20-0309-non-reasoning',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+
+console.log(inspected?.body);
+```
+
+## Notes
+
+- xAI tool choice translation is normalized to the shapes expected by the xAI SDK.
+- Non-image generic file parts are not supported in xAI chat requests; image parts are supported.
+- Some moving aliases such as `grok-4` and `grok-4-latest` are resolved to the current snapshot IDs internally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/xai",
-  "version": "0.0.1-dev.ffffff",
+  "version": "0.14.0",
   "private": false,
   "publishConfig": {
     "access": "restricted",
@@ -20,13 +20,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "cd ../.. && vitest --dir packages/xai",
-    "test:run": "cd ../.. && vitest run --dir packages/xai"
-  },
   "dependencies": {
     "@ai-sdk/xai": "^3.0.75",
     "ai": "^6.0.142",
@@ -36,9 +29,9 @@
     "@standardagents/spec": "^0.10.0"
   },
   "devDependencies": {
-    "@standardagents/spec": "workspace:*",
     "tsup": "^8.3.5",
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.0",
+    "@standardagents/spec": "0.14.0"
   },
   "keywords": [
     "standardagents",
@@ -49,5 +42,12 @@
     "llm"
   ],
   "author": "FormKit Inc.",
-  "license": "UNLICENSED"
-}
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && vitest --dir packages/xai",
+    "test:run": "cd ../.. && vitest run --dir packages/xai"
+  }
+}