@tanstack/openai-base 0.2.1 → 0.3.0

package/src/adapters/image.ts

@@ -1,158 +0,0 @@
-import { BaseImageAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
-import { generateId } from '@tanstack/ai-utils'
-import { createOpenAICompatibleClient } from '../utils/client'
-import type {
-  GeneratedImage,
-  ImageGenerationOptions,
-  ImageGenerationResult,
-} from '@tanstack/ai'
-import type OpenAI_SDK from 'openai'
-import type { OpenAICompatibleClientConfig } from '../types/config'
-
-/**
- * OpenAI-Compatible Image Generation Adapter
- *
- * A generalized base class for providers that implement OpenAI-compatible image
- * generation APIs. Providers like OpenAI, Grok, and others can extend this class
- * and only need to:
- * - Set `baseURL` in the config
- * - Lock the generic type parameters to provider-specific types
- * - Override validation or request building methods for provider-specific constraints
- *
- * All methods that validate inputs, build requests, or transform responses are
- * `protected` so subclasses can override them.
- */
-export class OpenAICompatibleImageAdapter<
-  TModel extends string,
-  TProviderOptions extends object = Record<string, any>,
-  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
-  TModelSizeByName extends Record<string, string> = Record<string, string>,
-> extends BaseImageAdapter<
-  TModel,
-  TProviderOptions,
-  TModelProviderOptionsByName,
-  TModelSizeByName
-> {
-  readonly kind = 'image' as const
-  readonly name: string
-
-  protected client: OpenAI_SDK
-
-  constructor(
-    config: OpenAICompatibleClientConfig,
-    model: TModel,
-    name: string = 'openai-compatible',
-  ) {
-    super(model, {})
-    this.name = name
-    this.client = createOpenAICompatibleClient(config)
-  }
-
-  async generateImages(
-    options: ImageGenerationOptions<TProviderOptions>,
-  ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size } = options
-
-    // Validate inputs
-    this.validatePrompt({ prompt, model })
-    this.validateImageSize(model, size)
-    this.validateNumberOfImages(model, numberOfImages)
-
-    // Build request based on model type
-    const request = this.buildRequest(options)
-
-    try {
-      options.logger.request(
-        `activity=image provider=${this.name} model=${model} n=${request.n ?? 1} size=${request.size ?? 'default'}`,
-        { provider: this.name, model },
-      )
-      const response = await this.client.images.generate({
-        ...request,
-        stream: false,
-      })
-
-      return this.transformResponse(model, response)
-    } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      options.logger.errors(`${this.name}.generateImages fatal`, {
-        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
-        source: `${this.name}.generateImages`,
-      })
-      throw error
-    }
-  }
-
-  protected buildRequest(
-    options: ImageGenerationOptions<TProviderOptions>,
-  ): 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,
-    }
-  }
-
-  protected transformResponse(
-    model: string,
-    response: OpenAI_SDK.Images.ImagesResponse,
-  ): ImageGenerationResult {
-    const images: Array<GeneratedImage> = (response.data ?? []).flatMap(
-      (item): Array<GeneratedImage> => {
-        const revisedPrompt = item.revised_prompt
-        if (item.b64_json) {
-          return [{ b64Json: item.b64_json, revisedPrompt }]
-        }
-        if (item.url) {
-          return [{ url: item.url, revisedPrompt }]
-        }
-        return []
-      },
-    )
-
-    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,
-    }
-  }
-
-  protected validatePrompt(options: { prompt: string; model: string }): void {
-    if (options.prompt.length === 0) {
-      throw new Error('Prompt cannot be empty.')
-    }
-  }
-
-  protected validateImageSize(_model: string, _size: string | undefined): void {
-    // Default: no size validation — subclasses can override
-  }
-
-  protected validateNumberOfImages(
-    _model: string,
-    numberOfImages: number | undefined,
-  ): void {
-    if (numberOfImages === undefined) return
-
-    // The base adapter only enforces "must be at least 1". Per-provider /
-    // per-model upper bounds vary widely (some support 4, some 10, some
-    // unlimited), so concrete adapter subclasses are expected to override
-    // this method with a model-specific cap.
-    if (numberOfImages < 1) {
-      throw new Error(
-        `Number of images must be at least 1. Requested: ${numberOfImages}`,
-      )
-    }
-  }
-}

package/src/adapters/summarize.ts

@@ -1,174 +0,0 @@
-import { BaseSummarizeAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
-import { generateId } from '@tanstack/ai-utils'
-import type {
-  StreamChunk,
-  SummarizationOptions,
-  SummarizationResult,
-  TextOptions,
-} from '@tanstack/ai'
-
-/**
- * Minimal interface for a text adapter that supports chatStream.
- * This allows the summarize adapter to work with any OpenAI-compatible
- * text adapter without tight coupling to a specific implementation.
- */
-export interface ChatStreamCapable<TProviderOptions extends object> {
-  chatStream: (
-    options: TextOptions<TProviderOptions>,
-  ) => AsyncIterable<StreamChunk>
-}
-
-/**
- * OpenAI-Compatible Summarize Adapter
- *
- * A thin wrapper around a text adapter that adds summarization-specific prompting.
- * Delegates all API calls to the provided text adapter.
- *
- * Subclasses or instantiators provide a text adapter (or factory) at construction
- * time, allowing any OpenAI-compatible provider to get summarization for free by
- * reusing its text adapter.
- */
-export class OpenAICompatibleSummarizeAdapter<
-  TModel extends string,
-  TProviderOptions extends object = Record<string, any>,
-> extends BaseSummarizeAdapter<TModel, TProviderOptions> {
-  readonly name: string
-
-  private textAdapter: ChatStreamCapable<TProviderOptions>
-
-  constructor(
-    textAdapter: ChatStreamCapable<TProviderOptions>,
-    model: TModel,
-    name: string = 'openai-compatible',
-  ) {
-    super({}, model)
-    this.name = name
-    this.textAdapter = textAdapter
-  }
-
-  async summarize(options: SummarizationOptions): Promise<SummarizationResult> {
-    const systemPrompt = this.buildSummarizationPrompt(options)
-
-    let summary = ''
-    const id = generateId(this.name)
-    let model = options.model
-    let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
-
-    options.logger.request(
-      `activity=summarize provider=${this.name} model=${options.model} text-length=${options.text.length} maxLength=${options.maxLength ?? 'unset'}`,
-      { provider: this.name, model: options.model },
-    )
-
-    try {
-      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,
-        logger: options.logger,
-      } satisfies TextOptions<TProviderOptions>)) {
-        if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
-          if (chunk.content) {
-            summary = chunk.content
-          } else if (chunk.delta) {
-            // Append delta only when present — a content-less chunk with no
-            // delta would otherwise concat literal `'undefined'`.
-            summary += chunk.delta
-          }
-          model = chunk.model || model
-        }
-        if (chunk.type === 'RUN_FINISHED') {
-          if (chunk.usage) {
-            usage = chunk.usage
-          }
-        }
-        // Surface failures: the underlying chatStream emits RUN_ERROR instead
-        // of throwing, so without this branch summarize() would return an
-        // empty summary and pretend a failed run succeeded.
-        if (chunk.type === 'RUN_ERROR') {
-          const message =
-            (chunk.error && typeof chunk.error.message === 'string'
-              ? chunk.error.message
-              : null) ?? 'Summarization failed'
-          const code =
-            chunk.error && typeof chunk.error.code === 'string'
-              ? chunk.error.code
-              : undefined
-          const err = new Error(message)
-          if (code) {
-            ;(err as Error & { code?: string }).code = code
-          }
-          throw err
-        }
-      }
-    } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      options.logger.errors(`${this.name}.summarize fatal`, {
-        error: toRunErrorPayload(error, `${this.name}.summarize failed`),
-        source: `${this.name}.summarize`,
-      })
-      throw error
-    }
-
-    return { id, model, summary, usage }
-  }
-
-  async *summarizeStream(
-    options: SummarizationOptions,
-  ): AsyncIterable<StreamChunk> {
-    const systemPrompt = this.buildSummarizationPrompt(options)
-
-    options.logger.request(
-      `activity=summarizeStream provider=${this.name} model=${options.model} text-length=${options.text.length} maxLength=${options.maxLength ?? 'unset'}`,
-      { provider: this.name, model: options.model },
-    )
-
-    try {
-      yield* this.textAdapter.chatStream({
-        model: options.model,
-        messages: [{ role: 'user', content: options.text }],
-        systemPrompts: [systemPrompt],
-        maxTokens: options.maxLength,
-        temperature: 0.3,
-        logger: options.logger,
-      } satisfies TextOptions<TProviderOptions>)
-    } catch (error: unknown) {
-      options.logger.errors(`${this.name}.summarizeStream fatal`, {
-        error: toRunErrorPayload(error, `${this.name}.summarizeStream failed`),
-        source: `${this.name}.summarizeStream`,
-      })
-      throw error
-    }
-  }
-
-  protected 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
-  }
-}

package/src/adapters/transcription.ts

@@ -1,194 +0,0 @@
-import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
-import { base64ToArrayBuffer, generateId } from '@tanstack/ai-utils'
-import { createOpenAICompatibleClient } from '../utils/client'
-import type {
-  TranscriptionOptions,
-  TranscriptionResult,
-  TranscriptionSegment,
-} from '@tanstack/ai'
-import type OpenAI_SDK from 'openai'
-import type { OpenAICompatibleClientConfig } from '../types/config'
-
-/**
- * OpenAI-Compatible Transcription (Speech-to-Text) Adapter
- *
- * A generalized base class for providers that implement OpenAI-compatible audio
- * transcription APIs. Providers can extend this class and only need to:
- * - Set `baseURL` in the config
- * - Lock the generic type parameters to provider-specific types
- * - Override audio handling or response mapping methods as needed
- *
- * All methods that handle audio input or map response formats are `protected`
- * so subclasses can override them.
- */
-export class OpenAICompatibleTranscriptionAdapter<
-  TModel extends string,
-  TProviderOptions extends object = Record<string, any>,
-> extends BaseTranscriptionAdapter<TModel, TProviderOptions> {
-  readonly name: string
-
-  protected client: OpenAI_SDK
-
-  constructor(
-    config: OpenAICompatibleClientConfig,
-    model: TModel,
-    name: string = 'openai-compatible',
-  ) {
-    super(model, {})
-    this.name = name
-    this.client = createOpenAICompatibleClient(config)
-  }
-
-  async transcribe(
-    options: TranscriptionOptions<TProviderOptions>,
-  ): Promise<TranscriptionResult> {
-    const { model, audio, language, prompt, responseFormat, modelOptions } =
-      options
-
-    // Convert audio input to File object
-    const file = this.prepareAudioFile(audio)
-
-    // Build request
-    const request: OpenAI_SDK.Audio.TranscriptionCreateParams = {
-      model,
-      file,
-      language,
-      prompt,
-      response_format: this.mapResponseFormat(responseFormat),
-      ...modelOptions,
-    }
-
-    // Call API - use verbose_json to get timestamps when available
-    const useVerbose =
-      responseFormat === 'verbose_json' ||
-      (!responseFormat && this.shouldDefaultToVerbose(model))
-
-    try {
-      options.logger.request(
-        `activity=transcription provider=${this.name} model=${model} verbose=${useVerbose}`,
-        { provider: this.name, model },
-      )
-      if (useVerbose) {
-        const response = await this.client.audio.transcriptions.create({
-          ...request,
-          response_format: 'verbose_json',
-        })
-
-        return {
-          id: generateId(this.name),
-          model,
-          text: response.text,
-          language: response.language,
-          duration: response.duration,
-          segments: response.segments?.map(
-            (seg): TranscriptionSegment => ({
-              id: seg.id,
-              start: seg.start,
-              end: seg.end,
-              text: seg.text,
-              // The OpenAI SDK types `avg_logprob` as `number`, so call Math.exp
-              // directly. Previously this was guarded with `seg.avg_logprob ?`
-              // which treated `0` (perfect-confidence) as missing.
-              confidence: Math.exp(seg.avg_logprob),
-            }),
-          ),
-          words: response.words?.map((w) => ({
-            word: w.word,
-            start: w.start,
-            end: w.end,
-          })),
-        }
-      } else {
-        const response = await this.client.audio.transcriptions.create(request)
-
-        return {
-          id: generateId(this.name),
-          model,
-          text: typeof response === 'string' ? response : response.text,
-          language,
-        }
-      }
-    } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      options.logger.errors(`${this.name}.transcribe fatal`, {
-        error: toRunErrorPayload(error, `${this.name}.transcribe failed`),
-        source: `${this.name}.transcribe`,
-      })
-      throw error
-    }
-  }
-
-  protected prepareAudioFile(audio: string | File | Blob | ArrayBuffer): File {
-    // If already a File, return it
-    if (typeof File !== 'undefined' && audio instanceof File) {
-      return audio
-    }
-
-    // If Blob, convert to File
-    if (typeof Blob !== 'undefined' && audio instanceof Blob) {
-      this.ensureFileSupport()
-      return new File([audio], 'audio.mp3', {
-        type: audio.type || 'audio/mpeg',
-      })
-    }
-
-    // If ArrayBuffer, convert to File
-    if (typeof ArrayBuffer !== 'undefined' && audio instanceof ArrayBuffer) {
-      this.ensureFileSupport()
-      return new File([audio], 'audio.mp3', { type: 'audio/mpeg' })
-    }
-
-    // If base64 string, decode and convert to File
-    if (typeof audio === 'string') {
-      this.ensureFileSupport()
-
-      // Check if it's a data URL
-      if (audio.startsWith('data:')) {
-        const parts = audio.split(',')
-        const header = parts[0]
-        const base64Data = parts[1] || ''
-        const mimeMatch = header?.match(/data:([^;]+)/)
-        const mimeType = mimeMatch?.[1] || 'audio/mpeg'
-        const bytes = base64ToArrayBuffer(base64Data)
-        const extension = mimeType.split('/')[1] || 'mp3'
-        return new File([bytes], `audio.${extension}`, { type: mimeType })
-      }
-
-      // Assume raw base64
-      const bytes = base64ToArrayBuffer(audio)
-      return new File([bytes], 'audio.mp3', { type: 'audio/mpeg' })
-    }
-
-    throw new Error('Invalid audio input type')
-  }
-
-  /**
-   * Checks that the global `File` constructor is available.
-   * Throws a descriptive error in environments that lack it (e.g. Node < 20).
-   */
-  private ensureFileSupport(): void {
-    if (typeof File === 'undefined') {
-      throw new Error(
-        '`File` is not available in this environment. ' +
-          'Use Node.js 20 or newer, or pass a File object directly.',
-      )
-    }
-  }
-
-  /**
-   * Whether the adapter should default to verbose_json when no response format is specified.
-   * Override in provider-specific subclasses for model-specific behavior.
-   */
-  protected shouldDefaultToVerbose(_model: string): boolean {
-    return false
-  }
-
-  protected mapResponseFormat(
-    format?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt',
-  ): OpenAI_SDK.Audio.TranscriptionCreateParams['response_format'] {
-    if (!format) return 'json'
-    return format as OpenAI_SDK.Audio.TranscriptionCreateParams['response_format']
-  }
-}

package/src/adapters/tts.ts

@@ -1,124 +0,0 @@
-import { BaseTTSAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
-import { arrayBufferToBase64, generateId } from '@tanstack/ai-utils'
-import { createOpenAICompatibleClient } from '../utils/client'
-import type { TTSOptions, TTSResult } from '@tanstack/ai'
-import type OpenAI_SDK from 'openai'
-import type { OpenAICompatibleClientConfig } from '../types/config'
-
-/**
- * OpenAI-Compatible Text-to-Speech Adapter
- *
- * A generalized base class for providers that implement OpenAI-compatible TTS APIs.
- * Providers can extend this class and only need to:
- * - Set `baseURL` in the config
- * - Lock the generic type parameters to provider-specific types
- * - Override validation methods or request building for provider-specific constraints
- *
- * All methods that validate inputs or build requests are `protected` so subclasses
- * can override them.
- */
-export class OpenAICompatibleTTSAdapter<
-  TModel extends string,
-  TProviderOptions extends object = Record<string, any>,
-> extends BaseTTSAdapter<TModel, TProviderOptions> {
-  readonly name: string
-
-  protected client: OpenAI_SDK
-
-  constructor(
-    config: OpenAICompatibleClientConfig,
-    model: TModel,
-    name: string = 'openai-compatible',
-  ) {
-    super(model, {})
-    this.name = name
-    this.client = createOpenAICompatibleClient(config)
-  }
-
-  async generateSpeech(
-    options: TTSOptions<TProviderOptions>,
-  ): Promise<TTSResult> {
-    const { model, text, voice, format, speed, modelOptions } = options
-
-    // Validate inputs
-    this.validateAudioInput(text)
-    this.validateSpeed(speed)
-    this.validateInstructions(model, modelOptions)
-
-    // Build request
-    const request: OpenAI_SDK.Audio.SpeechCreateParams = {
-      model,
-      input: text,
-      voice: (voice || 'alloy') as OpenAI_SDK.Audio.SpeechCreateParams['voice'],
-      response_format: format,
-      speed,
-      ...modelOptions,
-    }
-
-    try {
-      options.logger.request(
-        `activity=tts provider=${this.name} model=${model} format=${request.response_format ?? 'default'} voice=${request.voice}`,
-        { provider: this.name, model },
-      )
-      const response = await this.client.audio.speech.create(request)
-
-      // Convert response to base64. Buffer is Node-only; use atob fallback in
-      // browser/edge runtimes where the SDK can run.
-      const arrayBuffer = await response.arrayBuffer()
-      const base64 = arrayBufferToBase64(arrayBuffer)
-
-      const outputFormat = (request.response_format as string) || 'mp3'
-      const contentType = this.getContentType(outputFormat)
-
-      return {
-        id: generateId(this.name),
-        model,
-        audio: base64,
-        format: outputFormat,
-        contentType,
-      }
-    } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      options.logger.errors(`${this.name}.generateSpeech fatal`, {
-        error: toRunErrorPayload(error, `${this.name}.generateSpeech failed`),
-        source: `${this.name}.generateSpeech`,
-      })
-      throw error
-    }
-  }
-
-  protected validateAudioInput(text: string): void {
-    if (text.length > 4096) {
-      throw new Error('Input text exceeds maximum length of 4096 characters.')
-    }
-  }
-
-  protected validateSpeed(speed?: number): void {
-    if (speed !== undefined) {
-      if (speed < 0.25 || speed > 4.0) {
-        throw new Error('Speed must be between 0.25 and 4.0.')
-      }
-    }
-  }
-
-  protected validateInstructions(
-    _model: string,
-    _modelOptions?: TProviderOptions,
-  ): void {
-    // Default: no instructions validation — subclasses can override
-  }
-
-  protected getContentType(format: string): string {
-    const contentTypes: Record<string, string> = {
-      mp3: 'audio/mpeg',
-      opus: 'audio/opus',
-      aac: 'audio/aac',
-      flac: 'audio/flac',
-      wav: 'audio/wav',
-      pcm: 'audio/pcm',
-    }
-    return contentTypes[format] || 'audio/mpeg'
-  }
-}