@tanstack/ai-grok 0.0.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+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

@@ -1,45 +1,130 @@
 # @tanstack/ai-grok
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Grok (xAI) adapter for TanStack AI
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Installation
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @tanstack/ai-grok
+# or
+pnpm add @tanstack/ai-grok
+# or
+yarn add @tanstack/ai-grok
+```
 
-## Purpose
+## Setup
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@tanstack/ai-grok`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+Get your API key from [xAI Console](https://console.x.ai) and set it as an environment variable:
 
-## What is OIDC Trusted Publishing?
+```bash
+export XAI_API_KEY="xai-..."
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Usage
 
-## Setup Instructions
+### Text/Chat Adapter
 
-To properly configure OIDC trusted publishing for this package:
+```typescript
+import { grokText } from '@tanstack/ai-grok'
+import { generate } from '@tanstack/ai'
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+const adapter = grokText()
 
-## DO NOT USE THIS PACKAGE
+const result = await generate({
+  adapter,
+  model: 'grok-3',
+  messages: [
+    { role: 'user', content: 'Explain quantum computing in simple terms' },
+  ],
+})
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+console.log(result.text)
+```
 
-## More Information
+### Summarization Adapter
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```typescript
+import { grokSummarize } from '@tanstack/ai-grok'
+import { summarize } from '@tanstack/ai'
 
----
+const adapter = grokSummarize()
 
-**Maintained for OIDC setup purposes only**
+const result = await summarize({
+  adapter,
+  model: 'grok-3',
+  text: 'Long article text...',
+  style: 'bullet-points',
+})
+
+console.log(result.summary)
+```
+
+### Image Generation Adapter
+
+```typescript
+import { grokImage } from '@tanstack/ai-grok'
+import { generateImages } from '@tanstack/ai'
+
+const adapter = grokImage()
+
+const result = await generateImages({
+  adapter,
+  model: 'grok-2-image-1212',
+  prompt: 'A beautiful sunset over mountains',
+  numberOfImages: 1,
+  size: '1024x1024',
+})
+
+console.log(result.images[0].url)
+```
+
+### With Explicit API Key
+
+```typescript
+import { createGrokText } from '@tanstack/ai-grok'
+
+const adapter = createGrokText('xai-your-api-key-here')
+```
+
+## Supported Models
+
+### Chat Models
+
+- `grok-4` - Latest flagship model
+- `grok-3` - Previous generation model
+- `grok-3-mini` - Smaller, faster model
+- `grok-4-fast` - Fast inference model
+- `grok-4.1-fast` - Production-focused fast model
+- `grok-2-vision-1212` - Vision-capable model (text + image input)
+
+### Image Models
+
+- `grok-2-image-1212` - Image generation model
+
+## Features
+
+- ✅ Streaming chat completions
+- ✅ Structured output (JSON Schema)
+- ✅ Function/tool calling
+- ✅ Multimodal input (text + images for vision models)
+- ✅ Image generation
+- ✅ Text summarization
+- ❌ Embeddings (not supported by xAI)
+
+## Tree-Shakeable Adapters
+
+This package uses tree-shakeable adapters, so you only import what you need:
+
+```typescript
+// Only imports text adapter
+import { grokText } from '@tanstack/ai-grok'
+
+// Only imports image adapter
+import { grokImage } from '@tanstack/ai-grok'
+```
+
+This keeps your bundle size small!
+
+## License
+
+MIT

package/dist/esm/adapters/image.d.ts

@@ -0,0 +1,77 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters';
+import { GROK_IMAGE_MODELS } from '../model-meta.js';
+import { GrokImageModelProviderOptionsByName, GrokImageModelSizeByName, GrokImageProviderOptions } from '../image/image-provider-options.js';
+import { ImageGenerationOptions, ImageGenerationResult } from '@tanstack/ai';
+import { GrokClientConfig } from '../utils.js';
+/**
+ * Configuration for Grok image adapter
+ */
+export interface GrokImageConfig extends GrokClientConfig {
+}
+/** Model type for Grok Image */
+export type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number];
+/**
+ * Grok Image Generation Adapter
+ *
+ * Tree-shakeable adapter for Grok image generation functionality.
+ * Supports grok-2-image-1212 model.
+ *
+ * Features:
+ * - Model-specific type-safe provider options
+ * - Size validation per model
+ * - Number of images validation
+ */
+export declare class GrokImageAdapter<TModel extends GrokImageModel> extends BaseImageAdapter<TModel, GrokImageProviderOptions, GrokImageModelProviderOptionsByName, GrokImageModelSizeByName> {
+    readonly kind: "image";
+    readonly name: "grok";
+    private client;
+    constructor(config: GrokImageConfig, model: TModel);
+    generateImages(options: ImageGenerationOptions<GrokImageProviderOptions>): Promise<ImageGenerationResult>;
+    private buildRequest;
+    private transformResponse;
+}
+/**
+ * Creates a Grok image adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'grok-2-image-1212')
+ * @param apiKey - Your xAI API key
+ * @param config - Optional additional configuration
+ * @returns Configured Grok image adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokImage('grok-2-image-1212', "xai-...");
+ *
+ * const result = await generateImage({
+ *   adapter,
+ *   prompt: 'A cute baby sea otter'
+ * });
+ * ```
+ */
+export declare function createGrokImage<TModel extends GrokImageModel>(model: TModel, apiKey: string, config?: Omit<GrokImageConfig, 'apiKey'>): GrokImageAdapter<TModel>;
+/**
+ * Creates a Grok image adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `XAI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'grok-2-image-1212')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Grok image adapter instance with resolved types
+ * @throws Error if XAI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses XAI_API_KEY from environment
+ * const adapter = grokImage('grok-2-image-1212');
+ *
+ * const result = await generateImage({
+ *   adapter,
+ *   prompt: 'A beautiful sunset over mountains'
+ * });
+ * ```
+ */
+export declare function grokImage<TModel extends GrokImageModel>(model: TModel, config?: Omit<GrokImageConfig, 'apiKey'>): GrokImageAdapter<TModel>;

package/dist/esm/adapters/image.js

@@ -0,0 +1,63 @@
+import { BaseImageAdapter } from "@tanstack/ai/adapters";
+import { createGrokClient, generateId, getGrokApiKeyFromEnv } from "../utils/client.js";
+import { validatePrompt, validateImageSize, validateNumberOfImages } from "../image/image-provider-options.js";
+class GrokImageAdapter extends BaseImageAdapter {
+  constructor(config, model) {
+    super({}, model);
+    this.kind = "image";
+    this.name = "grok";
+    this.client = createGrokClient(config);
+  }
+  async generateImages(options) {
+    const { model, prompt, numberOfImages, size } = options;
+    validatePrompt({ prompt });
+    validateImageSize(model, size);
+    validateNumberOfImages(model, numberOfImages);
+    const request = this.buildRequest(options);
+    const response = await this.client.images.generate({
+      ...request,
+      stream: false
+    });
+    return this.transformResponse(model, response);
+  }
+  buildRequest(options) {
+    const { model, prompt, numberOfImages, size, modelOptions } = options;
+    return {
+      model,
+      prompt,
+      n: numberOfImages ?? 1,
+      size,
+      ...modelOptions
+    };
+  }
+  transformResponse(model, response) {
+    const images = (response.data ?? []).map((item) => ({
+      b64Json: item.b64_json,
+      url: item.url,
+      revisedPrompt: item.revised_prompt
+    }));
+    return {
+      id: generateId(this.name),
+      model,
+      images,
+      usage: response.usage ? {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+        totalTokens: response.usage.total_tokens
+      } : void 0
+    };
+  }
+}
+function createGrokImage(model, apiKey, config) {
+  return new GrokImageAdapter({ apiKey, ...config }, model);
+}
+function grokImage(model, config) {
+  const apiKey = getGrokApiKeyFromEnv();
+  return createGrokImage(model, apiKey, config);
+}
+export {
+  GrokImageAdapter,
+  createGrokImage,
+  grokImage
+};
+//# sourceMappingURL=image.js.map

package/dist/esm/adapters/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { createGrokClient, generateId, getGrokApiKeyFromEnv } from '../utils'\nimport {\n  validateImageSize,\n  validateNumberOfImages,\n  validatePrompt,\n} from '../image/image-provider-options'\nimport type { GROK_IMAGE_MODELS } from '../model-meta'\nimport type {\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageProviderOptions,\n} from '../image/image-provider-options'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n} from '@tanstack/ai'\nimport type OpenAI_SDK from 'openai'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok image adapter\n */\nexport interface GrokImageConfig extends GrokClientConfig {}\n\n/** Model type for Grok Image */\nexport type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number]\n\n/**\n * Grok Image Generation Adapter\n *\n * Tree-shakeable adapter for Grok image generation functionality.\n * Supports grok-2-image-1212 model.\n *\n * Features:\n * - Model-specific type-safe provider options\n * - Size validation per model\n * - Number of images validation\n */\nexport class GrokImageAdapter<\n  TModel extends GrokImageModel,\n> extends BaseImageAdapter<\n  TModel,\n  GrokImageProviderOptions,\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName\n> {\n  readonly kind = 'image' as const\n  readonly name = 'grok' as const\n\n  private client: OpenAI_SDK\n\n  constructor(config: GrokImageConfig, model: TModel) {\n    super({}, model)\n    this.client = createGrokClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): Promise<ImageGenerationResult> {\n    const { model, prompt, numberOfImages, size } = options\n\n    // Validate inputs\n    validatePrompt({ prompt, model })\n    validateImageSize(model, size)\n    validateNumberOfImages(model, numberOfImages)\n\n    // Build request based on model type\n    const request = this.buildRequest(options)\n\n    const response = await this.client.images.generate({\n      ...request,\n      stream: false,\n    })\n\n    return this.transformResponse(model, response)\n  }\n\n  private buildRequest(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): OpenAI_SDK.Images.ImageGenerateParams {\n    const { model, prompt, numberOfImages, size, modelOptions } = options\n\n    return {\n      model,\n      prompt,\n      n: numberOfImages ?? 1,\n      size: size as OpenAI_SDK.Images.ImageGenerateParams['size'],\n      ...modelOptions,\n    }\n  }\n\n  private transformResponse(\n    model: string,\n    response: OpenAI_SDK.Images.ImagesResponse,\n  ): ImageGenerationResult {\n    const images: Array<GeneratedImage> = (response.data ?? []).map((item) => ({\n      b64Json: item.b64_json,\n      url: item.url,\n      revisedPrompt: item.revised_prompt,\n    }))\n\n    return {\n      id: generateId(this.name),\n      model,\n      images,\n      usage: response.usage\n        ? {\n            inputTokens: response.usage.input_tokens,\n            outputTokens: response.usage.output_tokens,\n            totalTokens: response.usage.total_tokens,\n          }\n        : undefined,\n    }\n  }\n}\n\n/**\n * Creates a Grok image adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok image adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokImage('grok-2-image-1212', \"xai-...\");\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A cute baby sea otter'\n * });\n * ```\n */\nexport function createGrokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  return new GrokImageAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok image adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok image adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokImage('grok-2-image-1212');\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A beautiful sunset over mountains'\n * });\n * ```\n */\nexport function grokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokImage(model, apiKey, config)\n}\n"],"names":[],"mappings":";;;AAwCO,MAAM,yBAEH,iBAKR;AAAA,EAMA,YAAY,QAAyB,OAAe;AAClD,UAAM,CAAA,GAAI,KAAK;AANjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAMd,SAAK,SAAS,iBAAiB,MAAM;AAAA,EACvC;AAAA,EAEA,MAAM,eACJ,SACgC;AAChC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,SAAS;AAGhD,mBAAe,EAAE,OAAc,CAAC;AAChC,sBAAkB,OAAO,IAAI;AAC7B,2BAAuB,OAAO,cAAc;AAG5C,UAAM,UAAU,KAAK,aAAa,OAAO;AAEzC,UAAM,WAAW,MAAM,KAAK,OAAO,OAAO,SAAS;AAAA,MACjD,GAAG;AAAA,MACH,QAAQ;AAAA,IAAA,CACT;AAED,WAAO,KAAK,kBAAkB,OAAO,QAAQ;AAAA,EAC/C;AAAA,EAEQ,aACN,SACuC;AACvC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,iBAAiB;AAE9D,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAG,kBAAkB;AAAA,MACrB;AAAA,MACA,GAAG;AAAA,IAAA;AAAA,EAEP;AAAA,EAEQ,kBACN,OACA,UACuB;AACvB,UAAM,UAAiC,SAAS,QAAQ,CAAA,GAAI,IAAI,CAAC,UAAU;AAAA,MACzE,SAAS,KAAK;AAAA,MACd,KAAK,KAAK;AAAA,MACV,eAAe,KAAK;AAAA,IAAA,EACpB;AAEF,WAAO;AAAA,MACL,IAAI,WAAW,KAAK,IAAI;AAAA,MACxB;AAAA,MACA;AAAA,MACA,OAAO,SAAS,QACZ;AAAA,QACE,aAAa,SAAS,MAAM;AAAA,QAC5B,cAAc,SAAS,MAAM;AAAA,QAC7B,aAAa,SAAS,MAAM;AAAA,MAAA,IAE9B;AAAA,IAAA;AAAA,EAER;AACF;AAqBO,SAAS,gBACd,OACA,QACA,QAC0B;AAC1B,SAAO,IAAI,iBAAiB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AAC1D;AA0BO,SAAS,UACd,OACA,QAC0B;AAC1B,QAAM,SAAS,qBAAA;AACf,SAAO,gBAAgB,OAAO,QAAQ,MAAM;AAC9C;"}

package/dist/esm/adapters/summarize.d.ts

@@ -0,0 +1,75 @@
+import { BaseSummarizeAdapter } from '@tanstack/ai/adapters';
+import { GROK_CHAT_MODELS } from '../model-meta.js';
+import { StreamChunk, SummarizationOptions, SummarizationResult } from '@tanstack/ai';
+import { GrokClientConfig } from '../utils.js';
+/**
+ * Configuration for Grok summarize adapter
+ */
+export interface GrokSummarizeConfig extends GrokClientConfig {
+}
+/**
+ * Grok-specific provider options for summarization
+ */
+export interface GrokSummarizeProviderOptions {
+    /** Temperature for response generation (0-2) */
+    temperature?: number;
+    /** Maximum tokens in the response */
+    maxTokens?: number;
+}
+/** Model type for Grok summarization */
+export type GrokSummarizeModel = (typeof GROK_CHAT_MODELS)[number];
+/**
+ * Grok Summarize Adapter
+ *
+ * A thin wrapper around the text adapter that adds summarization-specific prompting.
+ * Delegates all API calls to the GrokTextAdapter.
+ */
+export declare class GrokSummarizeAdapter<TModel extends GrokSummarizeModel> extends BaseSummarizeAdapter<TModel, GrokSummarizeProviderOptions> {
+    readonly kind: "summarize";
+    readonly name: "grok";
+    private textAdapter;
+    constructor(config: GrokSummarizeConfig, model: TModel);
+    summarize(options: SummarizationOptions): Promise<SummarizationResult>;
+    summarizeStream(options: SummarizationOptions): AsyncIterable<StreamChunk>;
+    private buildSummarizationPrompt;
+}
+/**
+ * Creates a Grok summarize adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param apiKey - Your xAI API key
+ * @param config - Optional additional configuration
+ * @returns Configured Grok summarize adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokSummarize('grok-3', "xai-...");
+ * ```
+ */
+export declare function createGrokSummarize<TModel extends GrokSummarizeModel>(model: TModel, apiKey: string, config?: Omit<GrokSummarizeConfig, 'apiKey'>): GrokSummarizeAdapter<TModel>;
+/**
+ * Creates a Grok summarize adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `XAI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Grok summarize adapter instance with resolved types
+ * @throws Error if XAI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses XAI_API_KEY from environment
+ * const adapter = grokSummarize('grok-3');
+ *
+ * await summarize({
+ *   adapter,
+ *   text: "Long article text..."
+ * });
+ * ```
+ */
+export declare function grokSummarize<TModel extends GrokSummarizeModel>(model: TModel, config?: Omit<GrokSummarizeConfig, 'apiKey'>): GrokSummarizeAdapter<TModel>;

package/dist/esm/adapters/summarize.js

@@ -0,0 +1,86 @@
+import { BaseSummarizeAdapter } from "@tanstack/ai/adapters";
+import { getGrokApiKeyFromEnv } from "../utils/client.js";
+import { GrokTextAdapter } from "./text.js";
+class GrokSummarizeAdapter extends BaseSummarizeAdapter {
+  constructor(config, model) {
+    super({}, model);
+    this.kind = "summarize";
+    this.name = "grok";
+    this.textAdapter = new GrokTextAdapter(config, model);
+  }
+  async summarize(options) {
+    const systemPrompt = this.buildSummarizationPrompt(options);
+    let summary = "";
+    const id = "";
+    let model = options.model;
+    let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    for await (const chunk of this.textAdapter.chatStream({
+      model: options.model,
+      messages: [{ role: "user", content: options.text }],
+      systemPrompts: [systemPrompt],
+      maxTokens: options.maxLength,
+      temperature: 0.3
+    })) {
+      if (chunk.type === "TEXT_MESSAGE_CONTENT") {
+        if (chunk.content) {
+          summary = chunk.content;
+        } else {
+          summary += chunk.delta;
+        }
+        model = chunk.model || model;
+      }
+      if (chunk.type === "RUN_FINISHED") {
+        if (chunk.usage) {
+          usage = chunk.usage;
+        }
+      }
+    }
+    return { id, model, summary, usage };
+  }
+  async *summarizeStream(options) {
+    const systemPrompt = this.buildSummarizationPrompt(options);
+    yield* this.textAdapter.chatStream({
+      model: options.model,
+      messages: [{ role: "user", content: options.text }],
+      systemPrompts: [systemPrompt],
+      maxTokens: options.maxLength,
+      temperature: 0.3
+    });
+  }
+  buildSummarizationPrompt(options) {
+    let prompt = "You are a professional summarizer. ";
+    switch (options.style) {
+      case "bullet-points":
+        prompt += "Provide a summary in bullet point format. ";
+        break;
+      case "paragraph":
+        prompt += "Provide a summary in paragraph format. ";
+        break;
+      case "concise":
+        prompt += "Provide a very concise summary in 1-2 sentences. ";
+        break;
+      default:
+        prompt += "Provide a clear and concise summary. ";
+    }
+    if (options.focus && options.focus.length > 0) {
+      prompt += `Focus on the following aspects: ${options.focus.join(", ")}. `;
+    }
+    if (options.maxLength) {
+      prompt += `Keep the summary under ${options.maxLength} tokens. `;
+    }
+    return prompt;
+  }
+}
+function createGrokSummarize(model, apiKey, config) {
+  return new GrokSummarizeAdapter({ apiKey, ...config }, model);
+}
+function grokSummarize(model, config) {
+  const apiKey = getGrokApiKeyFromEnv();
+  return createGrokSummarize(model, apiKey, config);
+}
+export {
+  GrokSummarizeAdapter,
+  createGrokSummarize,
+  grokSummarize
+};
+//# sourceMappingURL=summarize.js.map

package/dist/esm/adapters/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sources":["../../../src/adapters/summarize.ts"],"sourcesContent":["import { BaseSummarizeAdapter } from '@tanstack/ai/adapters'\nimport { getGrokApiKeyFromEnv } from '../utils'\nimport { GrokTextAdapter } from './text'\nimport type { GROK_CHAT_MODELS } from '../model-meta'\nimport type {\n  StreamChunk,\n  SummarizationOptions,\n  SummarizationResult,\n} from '@tanstack/ai'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok summarize adapter\n */\nexport interface GrokSummarizeConfig extends GrokClientConfig {}\n\n/**\n * Grok-specific provider options for summarization\n */\nexport interface GrokSummarizeProviderOptions {\n  /** Temperature for response generation (0-2) */\n  temperature?: number\n  /** Maximum tokens in the response */\n  maxTokens?: number\n}\n\n/** Model type for Grok summarization */\nexport type GrokSummarizeModel = (typeof GROK_CHAT_MODELS)[number]\n\n/**\n * Grok Summarize Adapter\n *\n * A thin wrapper around the text adapter that adds summarization-specific prompting.\n * Delegates all API calls to the GrokTextAdapter.\n */\nexport class GrokSummarizeAdapter<\n  TModel extends GrokSummarizeModel,\n> extends BaseSummarizeAdapter<TModel, GrokSummarizeProviderOptions> {\n  readonly kind = 'summarize' as const\n  readonly name = 'grok' as const\n\n  private textAdapter: GrokTextAdapter<TModel>\n\n  constructor(config: GrokSummarizeConfig, model: TModel) {\n    super({}, model)\n    this.textAdapter = new GrokTextAdapter(config, model)\n  }\n\n  async summarize(options: SummarizationOptions): Promise<SummarizationResult> {\n    const systemPrompt = this.buildSummarizationPrompt(options)\n\n    // Use the text adapter's streaming and collect the result\n    let summary = ''\n    const id = ''\n    let model = options.model\n    let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }\n\n    for await (const chunk of this.textAdapter.chatStream({\n      model: options.model,\n      messages: [{ role: 'user', content: options.text }],\n      systemPrompts: [systemPrompt],\n      maxTokens: options.maxLength,\n      temperature: 0.3,\n    })) {\n      // AG-UI TEXT_MESSAGE_CONTENT event\n      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {\n        if (chunk.content) {\n          summary = chunk.content\n        } else {\n          summary += chunk.delta\n        }\n        model = chunk.model || model\n      }\n      // AG-UI RUN_FINISHED event\n      if (chunk.type === 'RUN_FINISHED') {\n        if (chunk.usage) {\n          usage = chunk.usage\n        }\n      }\n    }\n\n    return { id, model, summary, usage }\n  }\n\n  async *summarizeStream(\n    options: SummarizationOptions,\n  ): AsyncIterable<StreamChunk> {\n    const systemPrompt = this.buildSummarizationPrompt(options)\n\n    // Delegate directly to the text adapter's streaming\n    yield* this.textAdapter.chatStream({\n      model: options.model,\n      messages: [{ role: 'user', content: options.text }],\n      systemPrompts: [systemPrompt],\n      maxTokens: options.maxLength,\n      temperature: 0.3,\n    })\n  }\n\n  private buildSummarizationPrompt(options: SummarizationOptions): string {\n    let prompt = 'You are a professional summarizer. '\n\n    switch (options.style) {\n      case 'bullet-points':\n        prompt += 'Provide a summary in bullet point format. '\n        break\n      case 'paragraph':\n        prompt += 'Provide a summary in paragraph format. '\n        break\n      case 'concise':\n        prompt += 'Provide a very concise summary in 1-2 sentences. '\n        break\n      default:\n        prompt += 'Provide a clear and concise summary. '\n    }\n\n    if (options.focus && options.focus.length > 0) {\n      prompt += `Focus on the following aspects: ${options.focus.join(', ')}. `\n    }\n\n    if (options.maxLength) {\n      prompt += `Keep the summary under ${options.maxLength} tokens. `\n    }\n\n    return prompt\n  }\n}\n\n/**\n * Creates a Grok summarize adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok summarize adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokSummarize('grok-3', \"xai-...\");\n * ```\n */\nexport function createGrokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): GrokSummarizeAdapter<TModel> {\n  return new GrokSummarizeAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok summarize adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok summarize adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokSummarize('grok-3');\n *\n * await summarize({\n *   adapter,\n *   text: \"Long article text...\"\n * });\n * ```\n */\nexport function grokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): GrokSummarizeAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokSummarize(model, apiKey, config)\n}\n"],"names":[],"mappings":";;;AAmCO,MAAM,6BAEH,qBAA2D;AAAA,EAMnE,YAAY,QAA6B,OAAe;AACtD,UAAM,CAAA,GAAI,KAAK;AANjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAMd,SAAK,cAAc,IAAI,gBAAgB,QAAQ,KAAK;AAAA,EACtD;AAAA,EAEA,MAAM,UAAU,SAA6D;AAC3E,UAAM,eAAe,KAAK,yBAAyB,OAAO;AAG1D,QAAI,UAAU;AACd,UAAM,KAAK;AACX,QAAI,QAAQ,QAAQ;AACpB,QAAI,QAAQ,EAAE,cAAc,GAAG,kBAAkB,GAAG,aAAa,EAAA;AAEjE,qBAAiB,SAAS,KAAK,YAAY,WAAW;AAAA,MACpD,OAAO,QAAQ;AAAA,MACf,UAAU,CAAC,EAAE,MAAM,QAAQ,SAAS,QAAQ,MAAM;AAAA,MAClD,eAAe,CAAC,YAAY;AAAA,MAC5B,WAAW,QAAQ;AAAA,MACnB,aAAa;AAAA,IAAA,CACd,GAAG;AAEF,UAAI,MAAM,SAAS,wBAAwB;AACzC,YAAI,MAAM,SAAS;AACjB,oBAAU,MAAM;AAAA,QAClB,OAAO;AACL,qBAAW,MAAM;AAAA,QACnB;AACA,gBAAQ,MAAM,SAAS;AAAA,MACzB;AAEA,UAAI,MAAM,SAAS,gBAAgB;AACjC,YAAI,MAAM,OAAO;AACf,kBAAQ,MAAM;AAAA,QAChB;AAAA,MACF;AAAA,IACF;AAEA,WAAO,EAAE,IAAI,OAAO,SAAS,MAAA;AAAA,EAC/B;AAAA,EAEA,OAAO,gBACL,SAC4B;AAC5B,UAAM,eAAe,KAAK,yBAAyB,OAAO;AAG1D,WAAO,KAAK,YAAY,WAAW;AAAA,MACjC,OAAO,QAAQ;AAAA,MACf,UAAU,CAAC,EAAE,MAAM,QAAQ,SAAS,QAAQ,MAAM;AAAA,MAClD,eAAe,CAAC,YAAY;AAAA,MAC5B,WAAW,QAAQ;AAAA,MACnB,aAAa;AAAA,IAAA,CACd;AAAA,EACH;AAAA,EAEQ,yBAAyB,SAAuC;AACtE,QAAI,SAAS;AAEb,YAAQ,QAAQ,OAAA;AAAA,MACd,KAAK;AACH,kBAAU;AACV;AAAA,MACF,KAAK;AACH,kBAAU;AACV;AAAA,MACF,KAAK;AACH,kBAAU;AACV;AAAA,MACF;AACE,kBAAU;AAAA,IAAA;AAGd,QAAI,QAAQ,SAAS,QAAQ,MAAM,SAAS,GAAG;AAC7C,gBAAU,mCAAmC,QAAQ,MAAM,KAAK,IAAI,CAAC;AAAA,IACvE;AAEA,QAAI,QAAQ,WAAW;AACrB,gBAAU,0BAA0B,QAAQ,SAAS;AAAA,IACvD;AAEA,WAAO;AAAA,EACT;AACF;AAgBO,SAAS,oBACd,OACA,QACA,QAC8B;AAC9B,SAAO,IAAI,qBAAqB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AAC9D;AA0BO,SAAS,cACd,OACA,QAC8B;AAC9B,QAAM,SAAS,qBAAA;AACf,SAAO,oBAAoB,OAAO,QAAQ,MAAM;AAClD;"}

package/dist/esm/adapters/text.d.ts

@@ -0,0 +1,96 @@
+import { BaseTextAdapter, StructuredOutputOptions, StructuredOutputResult } from '@tanstack/ai/adapters';
+import { GROK_CHAT_MODELS, ResolveInputModalities, ResolveProviderOptions } from '../model-meta.js';
+import { StreamChunk, TextOptions } from '@tanstack/ai';
+import { GrokMessageMetadataByModality } from '../message-types.js';
+import { GrokClientConfig } from '../utils.js';
+/**
+ * Configuration for Grok text adapter
+ */
+export interface GrokTextConfig extends GrokClientConfig {
+}
+/**
+ * Alias for TextProviderOptions for external use
+ */
+export type { ExternalTextProviderOptions as GrokTextProviderOptions } from '../text/text-provider-options.js';
+/**
+ * Grok Text (Chat) Adapter
+ *
+ * Tree-shakeable adapter for Grok chat/text completion functionality.
+ * Uses OpenAI-compatible Chat Completions API (not Responses API).
+ */
+export declare class GrokTextAdapter<TModel extends (typeof GROK_CHAT_MODELS)[number]> extends BaseTextAdapter<TModel, ResolveProviderOptions<TModel>, ResolveInputModalities<TModel>, GrokMessageMetadataByModality> {
+    readonly kind: "text";
+    readonly name: "grok";
+    private client;
+    constructor(config: GrokTextConfig, model: TModel);
+    chatStream(options: TextOptions<ResolveProviderOptions<TModel>>): AsyncIterable<StreamChunk>;
+    /**
+     * Generate structured output using Grok's JSON Schema response format.
+     * Uses stream: false to get the complete response in one call.
+     *
+     * Grok has strict requirements for structured output (via OpenAI-compatible API):
+     * - All properties must be in the `required` array
+     * - Optional fields should have null added to their type union
+     * - additionalProperties must be false for all objects
+     *
+     * The outputSchema is already JSON Schema (converted in the ai layer).
+     * We apply Grok-specific transformations for structured output compatibility.
+     */
+    structuredOutput(options: StructuredOutputOptions<ResolveProviderOptions<TModel>>): Promise<StructuredOutputResult<unknown>>;
+    private processGrokStreamChunks;
+    /**
+     * Maps common options to Grok-specific Chat Completions format
+     */
+    private mapTextOptionsToGrok;
+    private convertMessageToGrok;
+    /**
+     * Normalizes message content to an array of ContentPart.
+     * Handles backward compatibility with string content.
+     */
+    private normalizeContent;
+    /**
+     * Extracts text content from a content value that may be string, null, or ContentPart array.
+     */
+    private extractTextContent;
+}
+/**
+ * Creates a Grok text adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param apiKey - Your xAI API key
+ * @param config - Optional additional configuration
+ * @returns Configured Grok text adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokText('grok-3', "xai-...");
+ * // adapter has type-safe providerOptions for grok-3
+ * ```
+ */
+export declare function createGrokText<TModel extends (typeof GROK_CHAT_MODELS)[number]>(model: TModel, apiKey: string, config?: Omit<GrokTextConfig, 'apiKey'>): GrokTextAdapter<TModel>;
+/**
+ * Creates a Grok text adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `XAI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Grok text adapter instance with resolved types
+ * @throws Error if XAI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses XAI_API_KEY from environment
+ * const adapter = grokText('grok-3');
+ *
+ * const stream = chat({
+ *   adapter,
+ *   messages: [{ role: "user", content: "Hello!" }]
+ * });
+ * ```
+ */
+export declare function grokText<TModel extends (typeof GROK_CHAT_MODELS)[number]>(model: TModel, config?: Omit<GrokTextConfig, 'apiKey'>): GrokTextAdapter<TModel>;