@tanstack/ai-grok 0.0.1 → 0.3.0

package/package.json

@@ -1,10 +1,53 @@
 {
   "name": "@tanstack/ai-grok",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tanstack/ai-grok",
+  "version": "0.3.0",
+  "description": "Grok (xAI) adapter for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-grok"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "ai",
+    "grok",
+    "xai",
+    "tanstack",
+    "adapter"
+  ],
+  "dependencies": {
+    "openai": "^6.9.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^7.2.7"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@tanstack/ai": "^0.3.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/adapters/image.ts

@@ -0,0 +1,176 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters'
+import { createGrokClient, generateId, getGrokApiKeyFromEnv } from '../utils'
+import {
+  validateImageSize,
+  validateNumberOfImages,
+  validatePrompt,
+} from '../image/image-provider-options'
+import type { GROK_IMAGE_MODELS } from '../model-meta'
+import type {
+  GrokImageModelProviderOptionsByName,
+  GrokImageModelSizeByName,
+  GrokImageProviderOptions,
+} from '../image/image-provider-options'
+import type {
+  GeneratedImage,
+  ImageGenerationOptions,
+  ImageGenerationResult,
+} from '@tanstack/ai'
+import type OpenAI_SDK from 'openai'
+import type { GrokClientConfig } from '../utils'
+
+/**
+ * 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 class GrokImageAdapter<
+  TModel extends GrokImageModel,
+> extends BaseImageAdapter<
+  TModel,
+  GrokImageProviderOptions,
+  GrokImageModelProviderOptionsByName,
+  GrokImageModelSizeByName
+> {
+  readonly kind = 'image' as const
+  readonly name = 'grok' as const
+
+  private client: OpenAI_SDK
+
+  constructor(config: GrokImageConfig, model: TModel) {
+    super({}, model)
+    this.client = createGrokClient(config)
+  }
+
+  async generateImages(
+    options: ImageGenerationOptions<GrokImageProviderOptions>,
+  ): Promise<ImageGenerationResult> {
+    const { model, prompt, numberOfImages, size } = options
+
+    // Validate inputs
+    validatePrompt({ prompt, model })
+    validateImageSize(model, size)
+    validateNumberOfImages(model, numberOfImages)
+
+    // Build request based on model type
+    const request = this.buildRequest(options)
+
+    const response = await this.client.images.generate({
+      ...request,
+      stream: false,
+    })
+
+    return this.transformResponse(model, response)
+  }
+
+  private buildRequest(
+    options: ImageGenerationOptions<GrokImageProviderOptions>,
+  ): OpenAI_SDK.Images.ImageGenerateParams {
+    const { model, prompt, numberOfImages, size, modelOptions } = options
+
+    return {
+      model,
+      prompt,
+      n: numberOfImages ?? 1,
+      size: size as OpenAI_SDK.Images.ImageGenerateParams['size'],
+      ...modelOptions,
+    }
+  }
+
+  private transformResponse(
+    model: string,
+    response: OpenAI_SDK.Images.ImagesResponse,
+  ): ImageGenerationResult {
+    const images: Array<GeneratedImage> = (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,
+          }
+        : undefined,
+    }
+  }
+}
+
+/**
+ * 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 function createGrokImage<TModel extends GrokImageModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GrokImageConfig, 'apiKey'>,
+): GrokImageAdapter<TModel> {
+  return new GrokImageAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * 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 function grokImage<TModel extends GrokImageModel>(
+  model: TModel,
+  config?: Omit<GrokImageConfig, 'apiKey'>,
+): GrokImageAdapter<TModel> {
+  const apiKey = getGrokApiKeyFromEnv()
+  return createGrokImage(model, apiKey, config)
+}

package/src/adapters/summarize.ts

@@ -0,0 +1,181 @@
+import { BaseSummarizeAdapter } from '@tanstack/ai/adapters'
+import { getGrokApiKeyFromEnv } from '../utils'
+import { GrokTextAdapter } from './text'
+import type { GROK_CHAT_MODELS } from '../model-meta'
+import type {
+  StreamChunk,
+  SummarizationOptions,
+  SummarizationResult,
+} from '@tanstack/ai'
+import type { GrokClientConfig } from '../utils'
+
+/**
+ * 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 class GrokSummarizeAdapter<
+  TModel extends GrokSummarizeModel,
+> extends BaseSummarizeAdapter<TModel, GrokSummarizeProviderOptions> {
+  readonly kind = 'summarize' as const
+  readonly name = 'grok' as const
+
+  private textAdapter: GrokTextAdapter<TModel>
+
+  constructor(config: GrokSummarizeConfig, model: TModel) {
+    super({}, model)
+    this.textAdapter = new GrokTextAdapter(config, model)
+  }
+
+  async summarize(options: SummarizationOptions): Promise<SummarizationResult> {
+    const systemPrompt = this.buildSummarizationPrompt(options)
+
+    // Use the text adapter's streaming and collect the result
+    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,
+    })) {
+      // AG-UI TEXT_MESSAGE_CONTENT event
+      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+        if (chunk.content) {
+          summary = chunk.content
+        } else {
+          summary += chunk.delta
+        }
+        model = chunk.model || model
+      }
+      // AG-UI RUN_FINISHED event
+      if (chunk.type === 'RUN_FINISHED') {
+        if (chunk.usage) {
+          usage = chunk.usage
+        }
+      }
+    }
+
+    return { id, model, summary, usage }
+  }
+
+  async *summarizeStream(
+    options: SummarizationOptions,
+  ): AsyncIterable<StreamChunk> {
+    const systemPrompt = this.buildSummarizationPrompt(options)
+
+    // Delegate directly to the text adapter's streaming
+    yield* this.textAdapter.chatStream({
+      model: options.model,
+      messages: [{ role: 'user', content: options.text }],
+      systemPrompts: [systemPrompt],
+      maxTokens: options.maxLength,
+      temperature: 0.3,
+    })
+  }
+
+  private buildSummarizationPrompt(options: SummarizationOptions): string {
+    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
+  }
+}
+
+/**
+ * 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 function createGrokSummarize<TModel extends GrokSummarizeModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GrokSummarizeConfig, 'apiKey'>,
+): GrokSummarizeAdapter<TModel> {
+  return new GrokSummarizeAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * 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 function grokSummarize<TModel extends GrokSummarizeModel>(
+  model: TModel,
+  config?: Omit<GrokSummarizeConfig, 'apiKey'>,
+): GrokSummarizeAdapter<TModel> {
+  const apiKey = getGrokApiKeyFromEnv()
+  return createGrokSummarize(model, apiKey, config)
+}