@tanstack/ai 0.0.3 → 0.1.0

package/src/activities/generateImage/adapter.ts

@@ -0,0 +1,104 @@
+import type { ImageGenerationOptions, ImageGenerationResult } from '../../types'
+
+/**
+ * Configuration for image adapter instances
+ */
+export interface ImageAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Image adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'dall-e-3')
+ * - TProviderOptions: Base provider-specific options (already resolved)
+ * - TModelProviderOptionsByName: Map from model name to its specific provider options
+ * - TModelSizeByName: Map from model name to its supported sizes
+ */
+export interface ImageAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelSizeByName extends Record<string, string> = Record<string, string>,
+> {
+  /** Discriminator for adapter kind - used by generate() to determine API shape */
+  readonly kind: 'image'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
+  }
+
+  /**
+   * Generate images from a prompt
+   */
+  generateImages: (
+    options: ImageGenerationOptions<TProviderOptions>,
+  ) => Promise<ImageGenerationResult>
+}
+
+/**
+ * An ImageAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyImageAdapter = ImageAdapter<any, any, any, any>
+
+/**
+ * Abstract base class for image generation adapters.
+ * Extend this class to implement an image adapter for a specific provider.
+ *
+ * Generic parameters match ImageAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseImageAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelSizeByName extends Record<string, string> = Record<string, string>,
+> implements ImageAdapter<
+  TModel,
+  TProviderOptions,
+  TModelProviderOptionsByName,
+  TModelSizeByName
+> {
+  readonly kind = 'image' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
+  }
+
+  protected config: ImageAdapterConfig
+
+  constructor(config: ImageAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateImages(
+    options: ImageGenerationOptions<TProviderOptions>,
+  ): Promise<ImageGenerationResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateImage/index.ts

@@ -0,0 +1,162 @@
+/**
+ * Image Activity
+ *
+ * Generates images from text prompts.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import type { ImageAdapter } from './adapter'
+import type { ImageGenerationResult } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'image' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract model-specific provider options from an ImageAdapter via ~types.
+ * If the model has specific options defined in ModelProviderOptions (and not just via index signature),
+ * use those; otherwise fall back to base provider options.
+ */
+export type ImageProviderOptionsForModel<TAdapter, TModel extends string> =
+  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>
+    ? string extends keyof ModelOptions
+      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions
+        BaseOptions
+      : // ModelOptions has explicit keys - check if TModel is one of them
+        TModel extends keyof ModelOptions
+        ? ModelOptions[TModel]
+        : BaseOptions
+    : object
+
+/**
+ * Extract model-specific size options from an ImageAdapter via ~types.
+ * If the model has specific sizes defined, use those; otherwise fall back to string.
+ */
+export type ImageSizeForModel<TAdapter, TModel extends string> =
+  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>
+    ? string extends keyof SizeByName
+      ? // SizeByName has index signature - fall back to string
+        string
+      : // SizeByName has explicit keys - check if TModel is one of them
+        TModel extends keyof SizeByName
+        ? SizeByName[TModel]
+        : string
+    : string
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the image activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The image adapter type
+ */
+export interface ImageActivityOptions<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+> {
+  /** The image adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** Text description of the desired image(s) */
+  prompt: string
+  /** Number of images to generate (default: 1) */
+  numberOfImages?: number
+  /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
+  size?: ImageSizeForModel<TAdapter, TAdapter['model']>
+  /** Provider-specific options for image generation */
+  modelOptions?: ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/** Result type for the image activity */
+export type ImageActivityResult = Promise<ImageGenerationResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Image activity - generates images from text prompts.
+ *
+ * Uses AI image generation models to create images based on natural language descriptions.
+ *
+ * @example Generate a single image
+ * ```ts
+ * import { generateImage } from '@tanstack/ai'
+ * import { openaiImage } from '@tanstack/ai-openai'
+ *
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-3'),
+ *   prompt: 'A serene mountain landscape at sunset'
+ * })
+ *
+ * console.log(result.images[0].url)
+ * ```
+ *
+ * @example Generate multiple images
+ * ```ts
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-2'),
+ *   prompt: 'A cute robot mascot',
+ *   numberOfImages: 4,
+ *   size: '512x512'
+ * })
+ *
+ * result.images.forEach((image, i) => {
+ *   console.log(`Image ${i + 1}: ${image.url}`)
+ * })
+ * ```
+ *
+ * @example With provider-specific options
+ * ```ts
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-3'),
+ *   prompt: 'A professional headshot photo',
+ *   size: '1024x1024',
+ *   modelOptions: {
+ *     quality: 'hd',
+ *     style: 'natural'
+ *   }
+ * })
+ * ```
+ */
+export async function generateImage<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+>(options: ImageActivityOptions<TAdapter>): ImageActivityResult {
+  const { adapter, ...rest } = options
+  const model = adapter.model
+
+  return adapter.generateImages({ ...rest, model })
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateImage() function without executing.
+ */
+export function createImageOptions<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+>(options: ImageActivityOptions<TAdapter>): ImageActivityOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  ImageAdapter,
+  ImageAdapterConfig,
+  AnyImageAdapter,
+} from './adapter'
+export { BaseImageAdapter } from './adapter'

package/src/activities/generateSpeech/adapter.ts

@@ -0,0 +1,87 @@
+import type { TTSOptions, TTSResult } from '../../types'
+
+/**
+ * Configuration for TTS adapter instances
+ */
+export interface TTSAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * TTS adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'tts-1')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface TTSAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'tts'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  /**
+   * Generate speech from text
+   */
+  generateSpeech: (options: TTSOptions<TProviderOptions>) => Promise<TTSResult>
+}
+
+/**
+ * A TTSAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyTTSAdapter = TTSAdapter<any, any>
+
+/**
+ * Abstract base class for text-to-speech adapters.
+ * Extend this class to implement a TTS adapter for a specific provider.
+ *
+ * Generic parameters match TTSAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseTTSAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements TTSAdapter<TModel, TProviderOptions> {
+  readonly kind = 'tts' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: TTSAdapterConfig
+
+  constructor(config: TTSAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateSpeech(
+    options: TTSOptions<TProviderOptions>,
+  ): Promise<TTSResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateSpeech/index.ts

@@ -0,0 +1,122 @@
+/**
+ * TTS Activity
+ *
+ * Generates speech audio from text using text-to-speech models.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import type { TTSAdapter } from './adapter'
+import type { TTSResult } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'tts' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract provider options from a TTSAdapter via ~types.
+ */
+export type TTSProviderOptions<TAdapter> =
+  TAdapter extends TTSAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the TTS activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The TTS adapter type
+ */
+export interface TTSActivityOptions<
+  TAdapter extends TTSAdapter<string, object>,
+> {
+  /** The TTS adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** The text to convert to speech */
+  text: string
+  /** The voice to use for generation */
+  voice?: string
+  /** The output audio format */
+  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'
+  /** The speed of the generated audio (0.25 to 4.0) */
+  speed?: number
+  /** Provider-specific options for TTS generation */
+  modelOptions?: TTSProviderOptions<TAdapter>
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/** Result type for the TTS activity */
+export type TTSActivityResult = Promise<TTSResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * TTS activity - generates speech from text.
+ *
+ * Uses AI text-to-speech models to create audio from natural language text.
+ *
+ * @example Generate speech from text
+ * ```ts
+ * import { generateSpeech } from '@tanstack/ai'
+ * import { openaiTTS } from '@tanstack/ai-openai'
+ *
+ * const result = await generateSpeech({
+ *   adapter: openaiTTS('tts-1-hd'),
+ *   text: 'Hello, welcome to TanStack AI!',
+ *   voice: 'nova'
+ * })
+ *
+ * console.log(result.audio) // base64-encoded audio
+ * ```
+ *
+ * @example With format and speed options
+ * ```ts
+ * const result = await generateSpeech({
+ *   adapter: openaiTTS('tts-1'),
+ *   text: 'This is slower speech.',
+ *   voice: 'alloy',
+ *   format: 'wav',
+ *   speed: 0.8
+ * })
+ * ```
+ */
+export async function generateSpeech<
+  TAdapter extends TTSAdapter<string, object>,
+>(options: TTSActivityOptions<TAdapter>): TTSActivityResult {
+  const { adapter, ...rest } = options
+  const model = adapter.model
+
+  return adapter.generateSpeech({ ...rest, model })
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateSpeech() function without executing.
+ */
+export function createSpeechOptions<
+  TAdapter extends TTSAdapter<string, object>,
+>(options: TTSActivityOptions<TAdapter>): TTSActivityOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'
+export { BaseTTSAdapter } from './adapter'

package/src/activities/generateTranscription/adapter.ts

@@ -0,0 +1,89 @@
+import type { TranscriptionOptions, TranscriptionResult } from '../../types'
+
+/**
+ * Configuration for transcription adapter instances
+ */
+export interface TranscriptionAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Transcription adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'whisper-1')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface TranscriptionAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'transcription'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  /**
+   * Transcribe audio to text
+   */
+  transcribe: (
+    options: TranscriptionOptions<TProviderOptions>,
+  ) => Promise<TranscriptionResult>
+}
+
+/**
+ * A TranscriptionAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyTranscriptionAdapter = TranscriptionAdapter<any, any>
+
+/**
+ * Abstract base class for audio transcription adapters.
+ * Extend this class to implement a transcription adapter for a specific provider.
+ *
+ * Generic parameters match TranscriptionAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseTranscriptionAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements TranscriptionAdapter<TModel, TProviderOptions> {
+  readonly kind = 'transcription' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: TranscriptionAdapterConfig
+
+  constructor(config: TranscriptionAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract transcribe(
+    options: TranscriptionOptions<TProviderOptions>,
+  ): Promise<TranscriptionResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateTranscription/index.ts

@@ -0,0 +1,132 @@
+/**
+ * Transcription Activity
+ *
+ * Transcribes audio to text using speech-to-text models.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import type { TranscriptionAdapter } from './adapter'
+import type { TranscriptionResult } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'transcription' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract provider options from a TranscriptionAdapter via ~types.
+ */
+export type TranscriptionProviderOptions<TAdapter> =
+  TAdapter extends TranscriptionAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the transcription activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The transcription adapter type
+ */
+export interface TranscriptionActivityOptions<
+  TAdapter extends TranscriptionAdapter<string, object>,
+> {
+  /** The transcription adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */
+  audio: string | File | Blob | ArrayBuffer
+  /** The language of the audio in ISO-639-1 format (e.g., 'en') */
+  language?: string
+  /** An optional prompt to guide the transcription */
+  prompt?: string
+  /** The format of the transcription output */
+  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  /** Provider-specific options for transcription */
+  modelOptions?: TranscriptionProviderOptions<TAdapter>
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/** Result type for the transcription activity */
+export type TranscriptionActivityResult = Promise<TranscriptionResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Transcription activity - converts audio to text.
+ *
+ * Uses AI speech-to-text models to transcribe audio content.
+ *
+ * @example Transcribe an audio file
+ * ```ts
+ * import { generateTranscription } from '@tanstack/ai'
+ * import { openaiTranscription } from '@tanstack/ai-openai'
+ *
+ * const result = await generateTranscription({
+ *   adapter: openaiTranscription('whisper-1'),
+ *   audio: audioFile, // File, Blob, or base64 string
+ *   language: 'en'
+ * })
+ *
+ * console.log(result.text)
+ * ```
+ *
+ * @example With verbose output for timestamps
+ * ```ts
+ * const result = await generateTranscription({
+ *   adapter: openaiTranscription('whisper-1'),
+ *   audio: audioFile,
+ *   responseFormat: 'verbose_json'
+ * })
+ *
+ * result.segments?.forEach(segment => {
+ *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)
+ * })
+ * ```
+ */
+export async function generateTranscription<
+  TAdapter extends TranscriptionAdapter<string, object>,
+>(
+  options: TranscriptionActivityOptions<TAdapter>,
+): TranscriptionActivityResult {
+  const { adapter, ...rest } = options
+  const model = adapter.model
+
+  return adapter.transcribe({ ...rest, model })
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateTranscription() function without executing.
+ */
+export function createTranscriptionOptions<
+  TAdapter extends TranscriptionAdapter<string, object>,
+>(
+  options: TranscriptionActivityOptions<TAdapter>,
+): TranscriptionActivityOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  TranscriptionAdapter,
+  TranscriptionAdapterConfig,
+  AnyTranscriptionAdapter,
+} from './adapter'
+export { BaseTranscriptionAdapter } from './adapter'