@tanstack/ai 0.36.0 → 0.37.0

package/dist/esm/activities/generateSpeech/index.js

@@ -0,0 +1,119 @@
+import { aiEventClient } from "@tanstack/ai-event-client";
+import { streamGenerationResult } from "../stream-generation-result.js";
+import { resolveDebugOption } from "../../logger/resolve.js";
+import { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationError } from "../middleware/run.js";
+const kind = "tts";
+function createId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function generateSpeech(options) {
+  if (options.stream) {
+    return streamGenerationResult(
+      () => runGenerateSpeech(options)
+    );
+  }
+  return runGenerateSpeech(options);
+}
+async function runGenerateSpeech(options) {
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options;
+  const model = adapter.model;
+  const requestId = createId("speech");
+  const startTime = Date.now();
+  const logger = resolveDebugOption(options.debug);
+  const providerName = adapter.provider ?? adapter.name ?? "unknown";
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: "tts",
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId
+  });
+  await runGenerationStart(middleware, mwCtx);
+  aiEventClient.emit("speech:request:started", {
+    requestId,
+    provider: adapter.name,
+    model,
+    text: rest.text,
+    voice: rest.voice,
+    format: rest.format,
+    speed: rest.speed,
+    modelOptions: rest.modelOptions,
+    timestamp: startTime
+  });
+  logger.request(`activity=generateSpeech provider=${providerName}`, {
+    provider: providerName,
+    model
+  });
+  try {
+    const result = await adapter.generateSpeech({ ...rest, model, logger });
+    const duration = Date.now() - startTime;
+    aiEventClient.emit("speech:request:completed", {
+      requestId,
+      provider: adapter.name,
+      model,
+      audio: result.audio,
+      format: result.format,
+      audioDuration: result.duration,
+      contentType: result.contentType,
+      duration,
+      modelOptions: rest.modelOptions,
+      timestamp: Date.now()
+    });
+    if (result.usage) {
+      aiEventClient.emit("speech:usage", {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions,
+        timestamp: Date.now()
+      });
+    }
+    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
+      bytes: result.audio.length,
+      contentType: result.contentType
+    });
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage
+    });
+    return result;
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    const err = error;
+    aiEventClient.emit("speech:request:error", {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration,
+      modelOptions: rest.modelOptions,
+      timestamp: Date.now()
+    });
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration
+    });
+    logger.errors("generateSpeech activity failed", {
+      error,
+      source: "generateSpeech"
+    });
+    throw error;
+  }
+}
+function createSpeechOptions(options) {
+  return options;
+}
+export {
+  createSpeechOptions,
+  generateSpeech,
+  kind
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/activities/generateSpeech/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware'\nimport type { TTSAdapter } from './adapter'\nimport type { StreamChunk, TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> =\n  TAdapter extends TTSAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiSpeech } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiSpeech('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateSpeech(options),\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n>(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    ...rest\n  } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'tts',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateSpeech provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.generateSpeech({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('speech:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {\n      bytes: result.audio.length,\n      contentType: result.contentType,\n    })\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('speech:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration,\n    })\n    logger.errors('generateSpeech activity failed', {\n      error,\n      source: 'generateSpeech',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"names":[],"mappings":"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"}

package/dist/esm/activities/generateTranscription/adapter.d.ts

@@ -0,0 +1,62 @@
+import { TranscriptionOptions, TranscriptionResult } from '../../types.js';
+/**
+ * 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 declare abstract class BaseTranscriptionAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>> implements TranscriptionAdapter<TModel, TProviderOptions> {
+    readonly kind: "transcription";
+    abstract readonly name: string;
+    readonly model: TModel;
+    '~types': {
+        providerOptions: TProviderOptions;
+    };
+    protected config: TranscriptionAdapterConfig;
+    constructor(model: TModel, config?: TranscriptionAdapterConfig);
+    abstract transcribe(options: TranscriptionOptions<TProviderOptions>): Promise<TranscriptionResult>;
+    protected generateId(): string;
+}

package/dist/esm/activities/generateTranscription/adapter.js

@@ -0,0 +1,16 @@
+class BaseTranscriptionAdapter {
+  kind = "transcription";
+  model;
+  config;
+  constructor(model, config = {}) {
+    this.config = config;
+    this.model = model;
+  }
+  generateId() {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+  }
+}
+export {
+  BaseTranscriptionAdapter
+};
+//# sourceMappingURL=adapter.js.map

package/dist/esm/activities/generateTranscription/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sources":["../../../../src/activities/generateTranscription/adapter.ts"],"sourcesContent":["import type { TranscriptionOptions, TranscriptionResult } from '../../types'\n\n/**\n * Configuration for transcription adapter instances\n */\nexport interface TranscriptionAdapterConfig {\n  apiKey?: string\n  baseUrl?: string\n  timeout?: number\n  maxRetries?: number\n  headers?: Record<string, string>\n}\n\n/**\n * Transcription adapter interface with pre-resolved generics.\n *\n * An adapter is created by a provider function: `provider('model')` → `adapter`\n * All type resolution happens at the provider call site, not in this interface.\n *\n * Generic parameters:\n * - TModel: The specific model name (e.g., 'whisper-1')\n * - TProviderOptions: Provider-specific options (already resolved)\n */\nexport interface TranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> {\n  /** Discriminator for adapter kind - used to determine API shape */\n  readonly kind: 'transcription'\n  /** Adapter name identifier */\n  readonly name: string\n  /** The model this adapter is configured for */\n  readonly model: TModel\n\n  /**\n   * @internal Type-only properties for inference. Not assigned at runtime.\n   */\n  '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  /**\n   * Transcribe audio to text\n   */\n  transcribe: (\n    options: TranscriptionOptions<TProviderOptions>,\n  ) => Promise<TranscriptionResult>\n}\n\n/**\n * A TranscriptionAdapter with any/unknown type parameters.\n * Useful as a constraint in generic functions and interfaces.\n */\nexport type AnyTranscriptionAdapter = TranscriptionAdapter<any, any>\n\n/**\n * Abstract base class for audio transcription adapters.\n * Extend this class to implement a transcription adapter for a specific provider.\n *\n * Generic parameters match TranscriptionAdapter - all pre-resolved by the provider function.\n */\nexport abstract class BaseTranscriptionAdapter<\n  TModel extends string = string,\n  TProviderOptions extends object = Record<string, unknown>,\n> implements TranscriptionAdapter<TModel, TProviderOptions> {\n  readonly kind = 'transcription' as const\n  abstract readonly name: string\n  readonly model: TModel\n\n  // Type-only property - never assigned at runtime\n  declare '~types': {\n    providerOptions: TProviderOptions\n  }\n\n  protected config: TranscriptionAdapterConfig\n\n  constructor(model: TModel, config: TranscriptionAdapterConfig = {}) {\n    this.config = config\n    this.model = model\n  }\n\n  abstract transcribe(\n    options: TranscriptionOptions<TProviderOptions>,\n  ): Promise<TranscriptionResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AA6DO,MAAe,yBAGsC;AAAA,EACjD,OAAO;AAAA,EAEP;AAAA,EAOC;AAAA,EAEV,YAAY,OAAe,SAAqC,IAAI;AAClE,SAAK,SAAS;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAMU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC9E;AACF;"}

package/dist/esm/activities/generateTranscription/index.d.ts

@@ -0,0 +1,109 @@
+import { DebugOption } from '../../logger/types.js';
+import { GenerationMiddleware } from '../middleware.js';
+import { TranscriptionAdapter } from './adapter.js';
+import { StreamChunk, TranscriptionResult } from '../../types.js';
+/** The adapter kind this activity handles */
+export declare const kind: "transcription";
+/**
+ * Extract provider options from a TranscriptionAdapter via ~types.
+ */
+export type TranscriptionProviderOptions<TAdapter> = TAdapter extends TranscriptionAdapter<any, any> ? TAdapter['~types']['providerOptions'] : object;
+/**
+ * Options for the transcription activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The transcription adapter type
+ * @template TStream - Whether to stream the output
+ */
+export interface TranscriptionActivityOptions<TAdapter extends TranscriptionAdapter<string, TranscriptionProviderOptions<TAdapter>>, TStream extends boolean = false> {
+    /** 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>;
+    /**
+     * Whether to stream the transcription result.
+     * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+     * When false or not provided, returns a Promise<TranscriptionResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
+    /**
+     * Enable debug logging. Pass `true` to enable all categories, `false` to
+     * silence everything including errors, or a `DebugConfig` object for granular
+     * control and/or a custom `Logger`.
+     */
+    debug?: DebugOption;
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend.
+     */
+    middleware?: Array<GenerationMiddleware>;
+}
+/**
+ * Result type for the transcription activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<TranscriptionResult>
+ */
+export type TranscriptionActivityResult<TStream extends boolean = false> = TStream extends true ? AsyncIterable<StreamChunk> : Promise<TranscriptionResult>;
+/**
+ * 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}`)
+ * })
+ * ```
+ *
+ * @example Streaming transcription result
+ * ```ts
+ * for await (const chunk of generateTranscription({
+ *   adapter: openaiTranscription('whisper-1'),
+ *   audio: audioFile,
+ *   stream: true
+ * })) {
+ *   console.log(chunk)
+ * }
+ * ```
+ */
+export declare function generateTranscription<TAdapter extends TranscriptionAdapter<string, TranscriptionProviderOptions<TAdapter>>, TStream extends boolean = false>(options: TranscriptionActivityOptions<TAdapter, TStream>): TranscriptionActivityResult<TStream>;
+/**
+ * Create typed options for the generateTranscription() function without executing.
+ */
+export declare function createTranscriptionOptions<TAdapter extends TranscriptionAdapter<string, TranscriptionProviderOptions<TAdapter>>, TStream extends boolean = false>(options: TranscriptionActivityOptions<TAdapter, TStream>): TranscriptionActivityOptions<TAdapter, TStream>;
+export type { TranscriptionAdapter, TranscriptionAdapterConfig, AnyTranscriptionAdapter, } from './adapter.js';
+export { BaseTranscriptionAdapter } from './adapter.js';

package/dist/esm/activities/generateTranscription/index.js

@@ -0,0 +1,109 @@
+import { aiEventClient } from "@tanstack/ai-event-client";
+import { streamGenerationResult } from "../stream-generation-result.js";
+import { resolveDebugOption } from "../../logger/resolve.js";
+import { createGenerationContext, runGenerationStart, runGenerationUsage, runGenerationFinish, runGenerationError } from "../middleware/run.js";
+const kind = "transcription";
+function createId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function generateTranscription(options) {
+  if (options.stream) {
+    return streamGenerationResult(
+      () => runGenerateTranscription(options)
+    );
+  }
+  return runGenerateTranscription(
+    options
+  );
+}
+async function runGenerateTranscription(options) {
+  const {
+    adapter,
+    stream: _stream,
+    debug: _debug,
+    middleware,
+    ...rest
+  } = options;
+  const model = adapter.model;
+  const requestId = createId("transcription");
+  const startTime = Date.now();
+  const logger = resolveDebugOption(options.debug);
+  const providerName = adapter.provider ?? adapter.name ?? "unknown";
+  const mwCtx = createGenerationContext({
+    requestId,
+    activity: "transcription",
+    provider: adapter.name,
+    model,
+    modelOptions: rest.modelOptions,
+    createId
+  });
+  await runGenerationStart(middleware, mwCtx);
+  aiEventClient.emit("transcription:request:started", {
+    requestId,
+    provider: adapter.name,
+    model,
+    language: rest.language,
+    prompt: rest.prompt,
+    responseFormat: rest.responseFormat,
+    modelOptions: rest.modelOptions,
+    timestamp: startTime
+  });
+  logger.request(`activity=generateTranscription provider=${providerName}`, {
+    provider: providerName,
+    model
+  });
+  try {
+    const result = await adapter.transcribe({ ...rest, model, logger });
+    const duration = Date.now() - startTime;
+    aiEventClient.emit("transcription:request:completed", {
+      requestId,
+      provider: adapter.name,
+      model,
+      text: result.text,
+      language: result.language,
+      duration,
+      modelOptions: rest.modelOptions,
+      timestamp: Date.now()
+    });
+    logger.output(
+      `activity=generateTranscription length=${result.text.length}`,
+      { hasText: !!result.text }
+    );
+    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage);
+    await runGenerationFinish(middleware, mwCtx, {
+      duration,
+      usage: result.usage
+    });
+    return result;
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    const err = error;
+    aiEventClient.emit("transcription:request:error", {
+      requestId,
+      provider: adapter.name,
+      model,
+      error: { message: err.message, name: err.name },
+      duration,
+      modelOptions: rest.modelOptions,
+      timestamp: Date.now()
+    });
+    await runGenerationError(middleware, mwCtx, {
+      error,
+      duration
+    });
+    logger.errors("generateTranscription activity failed", {
+      error,
+      source: "generateTranscription"
+    });
+    throw error;
+  }
+}
+function createTranscriptionOptions(options) {
+  return options;
+}
+export {
+  createTranscriptionOptions,
+  generateTranscription,
+  kind
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/activities/generateTranscription/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateTranscription/index.ts"],"sourcesContent":["/**\n * Transcription Activity\n *\n * Transcribes audio to text using speech-to-text models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '@tanstack/ai-event-client'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport { resolveDebugOption } from '../../logger/resolve'\nimport {\n  createGenerationContext,\n  runGenerationError,\n  runGenerationFinish,\n  runGenerationStart,\n  runGenerationUsage,\n} from '../middleware'\nimport type { InternalLogger } from '../../logger/internal-logger'\nimport type { DebugOption } from '../../logger/types'\nimport type { GenerationMiddleware } from '../middleware'\nimport type { TranscriptionAdapter } from './adapter'\nimport type { StreamChunk, TranscriptionResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'transcription' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TranscriptionAdapter via ~types.\n */\nexport type TranscriptionProviderOptions<TAdapter> =\n  TAdapter extends TranscriptionAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the transcription activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The transcription adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TranscriptionActivityOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n> {\n  /** The transcription adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Provider-specific options for transcription */\n  modelOptions?: TranscriptionProviderOptions<TAdapter>\n  /**\n   * Whether to stream the transcription result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TranscriptionResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n  /**\n   * Enable debug logging. Pass `true` to enable all categories, `false` to\n   * silence everything including errors, or a `DebugConfig` object for granular\n   * control and/or a custom `Logger`.\n   */\n  debug?: DebugOption\n  /**\n   * Observe-only middleware notified on start, usage, success, and error. Pass\n   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the\n   * `GenerationMiddleware` contract for a custom backend.\n   */\n  middleware?: Array<GenerationMiddleware>\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the transcription activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TranscriptionResult>\n */\nexport type TranscriptionActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<TranscriptionResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Transcription activity - converts audio to text.\n *\n * Uses AI speech-to-text models to transcribe audio content.\n *\n * @example Transcribe an audio file\n * ```ts\n * import { generateTranscription } from '@tanstack/ai'\n * import { openaiTranscription } from '@tanstack/ai-openai'\n *\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile, // File, Blob, or base64 string\n *   language: 'en'\n * })\n *\n * console.log(result.text)\n * ```\n *\n * @example With verbose output for timestamps\n * ```ts\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   responseFormat: 'verbose_json'\n * })\n *\n * result.segments?.forEach(segment => {\n *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)\n * })\n * ```\n *\n * @example Streaming transcription result\n * ```ts\n * for await (const chunk of generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   stream: true\n * })) {\n *   console.log(chunk)\n * }\n * ```\n */\nexport function generateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateTranscription(options),\n    ) as TranscriptionActivityResult<TStream>\n  }\n\n  return runGenerateTranscription(\n    options,\n  ) as TranscriptionActivityResult<TStream>\n}\n\n/**\n * Run non-streaming transcription\n */\nasync function runGenerateTranscription<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n>(\n  options: TranscriptionActivityOptions<TAdapter, boolean>,\n): Promise<TranscriptionResult> {\n  const {\n    adapter,\n    stream: _stream,\n    debug: _debug,\n    middleware,\n    ...rest\n  } = options\n  const model = adapter.model\n  const requestId = createId('transcription')\n  const startTime = Date.now()\n  const logger: InternalLogger = resolveDebugOption(options.debug)\n  const providerName =\n    (adapter as { name?: string; provider?: string }).provider ??\n    (adapter as { name?: string }).name ??\n    'unknown'\n\n  const mwCtx = createGenerationContext({\n    requestId,\n    activity: 'transcription',\n    provider: adapter.name,\n    model,\n    modelOptions: rest.modelOptions,\n    createId,\n  })\n\n  await runGenerationStart(middleware, mwCtx)\n\n  aiEventClient.emit('transcription:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    language: rest.language,\n    prompt: rest.prompt,\n    responseFormat: rest.responseFormat,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  logger.request(`activity=generateTranscription provider=${providerName}`, {\n    provider: providerName,\n    model,\n  })\n\n  try {\n    const result = await adapter.transcribe({ ...rest, model, logger })\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('transcription:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      text: result.text,\n      language: result.language,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    logger.output(\n      `activity=generateTranscription length=${result.text.length}`,\n      { hasText: !!result.text },\n    )\n\n    if (result.usage) await runGenerationUsage(middleware, mwCtx, result.usage)\n    await runGenerationFinish(middleware, mwCtx, {\n      duration,\n      usage: result.usage,\n    })\n\n    return result\n  } catch (error) {\n    const duration = Date.now() - startTime\n    const err = error as Error\n    aiEventClient.emit('transcription:request:error', {\n      requestId,\n      provider: adapter.name,\n      model,\n      error: { message: err.message, name: err.name },\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n    await runGenerationError(middleware, mwCtx, {\n      error,\n      duration,\n    })\n    logger.errors('generateTranscription activity failed', {\n      error,\n      source: 'generateTranscription',\n    })\n    throw error\n  }\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateTranscription() function without executing.\n */\nexport function createTranscriptionOptions<\n  TAdapter extends TranscriptionAdapter<\n    string,\n    TranscriptionProviderOptions<TAdapter>\n  >,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TranscriptionAdapter,\n  TranscriptionAdapterConfig,\n  AnyTranscriptionAdapter,\n} from './adapter'\nexport { BaseTranscriptionAdapter } from './adapter'\n"],"names":[],"mappings":";;;;AA4BO,MAAM,OAAO;AAgFpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAiDO,SAAS,sBAOd,SACsC;AACtC,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,yBAAyB,OAAO;AAAA,IAAA;AAAA,EAEpC;AAEA,SAAO;AAAA,IACL;AAAA,EAAA;AAEJ;AAKA,eAAe,yBAMb,SAC8B;AAC9B,QAAM;AAAA,IACJ;AAAA,IACA,QAAQ;AAAA,IACR,OAAO;AAAA,IACP;AAAA,IACA,GAAG;AAAA,EAAA,IACD;AACJ,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,eAAe;AAC1C,QAAM,YAAY,KAAK,IAAA;AACvB,QAAM,SAAyB,mBAAmB,QAAQ,KAAK;AAC/D,QAAM,eACH,QAAiD,YACjD,QAA8B,QAC/B;AAEF,QAAM,QAAQ,wBAAwB;AAAA,IACpC;AAAA,IACA,UAAU;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,cAAc,KAAK;AAAA,IACnB;AAAA,EAAA,CACD;AAED,QAAM,mBAAmB,YAAY,KAAK;AAE1C,gBAAc,KAAK,iCAAiC;AAAA,IAClD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,UAAU,KAAK;AAAA,IACf,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,2CAA2C,YAAY,IAAI;AAAA,IACxE,UAAU;AAAA,IACV;AAAA,EAAA,CACD;AAED,MAAI;AACF,UAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,GAAG,MAAM,OAAO,QAAQ;AAClE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,mCAAmC;AAAA,MACpD;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,MAAM,OAAO;AAAA,MACb,UAAU,OAAO;AAAA,MACjB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO;AAAA,MACL,yCAAyC,OAAO,KAAK,MAAM;AAAA,MAC3D,EAAE,SAAS,CAAC,CAAC,OAAO,KAAA;AAAA,IAAK;AAG3B,QAAI,OAAO,MAAO,OAAM,mBAAmB,YAAY,OAAO,OAAO,KAAK;AAC1E,UAAM,oBAAoB,YAAY,OAAO;AAAA,MAC3C;AAAA,MACA,OAAO,OAAO;AAAA,IAAA,CACf;AAED,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,WAAW,KAAK,IAAA,IAAQ;AAC9B,UAAM,MAAM;AACZ,kBAAc,KAAK,+BAA+B;AAAA,MAChD;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,EAAE,SAAS,IAAI,SAAS,MAAM,IAAI,KAAA;AAAA,MACzC;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AACD,UAAM,mBAAmB,YAAY,OAAO;AAAA,MAC1C;AAAA,MACA;AAAA,IAAA,CACD;AACD,WAAO,OAAO,yCAAyC;AAAA,MACrD;AAAA,MACA,QAAQ;AAAA,IAAA,CACT;AACD,UAAM;AAAA,EACR;AACF;AASO,SAAS,2BAOd,SACiD;AACjD,SAAO;AACT;"}

package/dist/esm/activities/generateVideo/adapter.d.ts

@@ -0,0 +1,145 @@
+import { ModelInputModalitiesByName, VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
+/**
+ * Structured description of the durations a video model accepts.
+ *
+ * Tagged union so the same shape can express discrete enums (OpenAI Sora,
+ * Veo), continuous ranges, mixed shapes, and models with no duration field.
+ * Consumed by `VideoAdapter.availableDurations()`.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type DurationOptions<T extends string | number | undefined> = {
+    kind: 'discrete';
+    values: ReadonlyArray<NonNullable<T>>;
+} | {
+    kind: 'range';
+    min: number;
+    max: number;
+    step?: number;
+    unit: 'seconds';
+} | {
+    kind: 'mixed';
+    values: ReadonlyArray<NonNullable<T>>;
+    range?: {
+        min: number;
+        max: number;
+        step?: number;
+    };
+} | {
+    kind: 'none';
+};
+/**
+ * Configuration for video adapter instances
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoAdapterConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Video 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.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'sora-2')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ * - TModelProviderOptionsByName: Map from model name to its specific provider options
+ * - TModelSizeByName: Map from model name to its supported sizes
+ * - TModelInputModalitiesByName: Map from model name to the non-text prompt
+ *   modalities it accepts (constrains the `prompt` part types at compile time)
+ * - TModelDurationByName: Map from model name to its supported duration
+ *   union. Defaults to `Record<string, number>` so adapters that haven't
+ *   declared a map keep today's `duration?: number` typing.
+ */
+export interface VideoAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>, TModelInputModalitiesByName extends ModelInputModalitiesByName = ModelInputModalitiesByName, TModelDurationByName extends Record<string, string | number | undefined> = Record<string, number>> {
+    /** Discriminator for adapter kind - used to determine API shape */
+    readonly kind: 'video';
+    /** 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;
+        modelInputModalitiesByName: TModelInputModalitiesByName;
+        modelDurationByName: TModelDurationByName;
+    };
+    /**
+     * Create a new video generation job.
+     * Returns a job ID that can be used to poll for status and retrieve the video.
+     */
+    createVideoJob: (options: VideoGenerationOptions<TProviderOptions, TModelSizeByName[TModel], TModelDurationByName[TModel]>) => Promise<VideoJobResult>;
+    /**
+     * Get the current status of a video generation job.
+     */
+    getVideoStatus: (jobId: string) => Promise<VideoStatusResult>;
+    /**
+     * Get the URL to download/view the generated video.
+     * Should only be called after status is 'completed'.
+     */
+    getVideoUrl: (jobId: string) => Promise<VideoUrlResult>;
+    /**
+     * Describe the durations this adapter's model accepts. Returns a tagged
+     * union so consumers can render UI / coerce input without provider-specific
+     * knowledge.
+     */
+    availableDurations: () => DurationOptions<TModelDurationByName[TModel]>;
+    /**
+     * Coerce a raw seconds value to the closest valid duration for this model.
+     * Returns `undefined` for models with no duration field.
+     */
+    snapDuration: (seconds: number) => TModelDurationByName[TModel] | undefined;
+}
+/**
+ * A VideoAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyVideoAdapter = VideoAdapter<any, any, any, any, any, any>;
+/**
+ * Abstract base class for video generation adapters.
+ * Extend this class to implement a video adapter for a specific provider.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Generic parameters match VideoAdapter - all pre-resolved by the provider function.
+ */
+export declare abstract class BaseVideoAdapter<TModel extends string = string, TProviderOptions extends object = Record<string, unknown>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelSizeByName extends Record<string, string | undefined> = Record<string, string>, TModelInputModalitiesByName extends ModelInputModalitiesByName = ModelInputModalitiesByName, TModelDurationByName extends Record<string, string | number | undefined> = Record<string, number>> implements VideoAdapter<TModel, TProviderOptions, TModelProviderOptionsByName, TModelSizeByName, TModelInputModalitiesByName, TModelDurationByName> {
+    readonly kind: "video";
+    abstract readonly name: string;
+    readonly model: TModel;
+    '~types': {
+        providerOptions: TProviderOptions;
+        modelProviderOptionsByName: TModelProviderOptionsByName;
+        modelSizeByName: TModelSizeByName;
+        modelInputModalitiesByName: TModelInputModalitiesByName;
+        modelDurationByName: TModelDurationByName;
+    };
+    protected config: VideoAdapterConfig;
+    constructor(config: VideoAdapterConfig | undefined, model: TModel);
+    abstract createVideoJob(options: VideoGenerationOptions<TProviderOptions, TModelSizeByName[TModel], TModelDurationByName[TModel]>): Promise<VideoJobResult>;
+    abstract getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    abstract getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    /**
+     * Default implementation returns `{ kind: 'none' }`. Adapters that have
+     * declared their per-model duration map should override this.
+     */
+    availableDurations(): DurationOptions<TModelDurationByName[TModel]>;
+    /**
+     * Default implementation returns `undefined`. Adapters that have declared
+     * their per-model duration map should override.
+     */
+    snapDuration(_seconds: number): TModelDurationByName[TModel] | undefined;
+    protected generateId(): string;
+}

package/dist/esm/activities/generateVideo/adapter.js

@@ -0,0 +1,30 @@
+class BaseVideoAdapter {
+  kind = "video";
+  model;
+  config;
+  constructor(config = {}, model) {
+    this.config = config;
+    this.model = model;
+  }
+  /**
+   * Default implementation returns `{ kind: 'none' }`. Adapters that have
+   * declared their per-model duration map should override this.
+   */
+  availableDurations() {
+    return { kind: "none" };
+  }
+  /**
+   * Default implementation returns `undefined`. Adapters that have declared
+   * their per-model duration map should override.
+   */
+  snapDuration(_seconds) {
+    return void 0;
+  }
+  generateId() {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+  }
+}
+export {
+  BaseVideoAdapter
+};
+//# sourceMappingURL=adapter.js.map