@tanstack/ai-gemini 0.0.3 → 0.1.0

package/src/adapters/tts.ts

@@ -0,0 +1,223 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters'
+import {
+  createGeminiClient,
+  generateId,
+  getGeminiApiKeyFromEnv,
+} from '../utils'
+import type { GEMINI_TTS_MODELS, GeminiTTSVoice } from '../model-meta'
+import type { TTSOptions, TTSResult } from '@tanstack/ai'
+import type { GoogleGenAI } from '@google/genai'
+import type { GeminiClientConfig } from '../utils'
+
+/**
+ * Provider-specific options for Gemini TTS
+ *
+ * @experimental Gemini TTS is an experimental feature.
+ * @see https://ai.google.dev/gemini-api/docs/speech-generation
+ */
+export interface GeminiTTSProviderOptions {
+  /**
+   * Voice configuration for TTS.
+   * Choose from 30 available voices with different characteristics.
+   */
+  voiceConfig?: {
+    prebuiltVoiceConfig?: {
+      /**
+       * The voice name to use for speech synthesis.
+       * @see https://ai.google.dev/gemini-api/docs/speech-generation#voices
+       */
+      voiceName?: GeminiTTSVoice
+    }
+  }
+
+  /**
+   * System instruction for controlling speech style.
+   * Use natural language to describe the desired speaking style,
+   * pace, tone, accent, or other characteristics.
+   *
+   * @example "Speak slowly and calmly, as if telling a bedtime story"
+   * @example "Use an upbeat, enthusiastic tone with moderate pace"
+   * @example "Speak with a British accent"
+   */
+  systemInstruction?: string
+
+  /**
+   * Language code hint for the speech synthesis.
+   * Gemini TTS supports 24 languages and can auto-detect,
+   * but you can provide a hint for better results.
+   *
+   * @example "en-US" for American English
+   * @example "es-ES" for Spanish (Spain)
+   * @example "ja-JP" for Japanese
+   */
+  languageCode?: string
+}
+
+/**
+ * Configuration for Gemini TTS adapter
+ *
+ * @experimental Gemini TTS is an experimental feature.
+ */
+export interface GeminiTTSConfig extends GeminiClientConfig {}
+
+/** Model type for Gemini TTS */
+export type GeminiTTSModel = (typeof GEMINI_TTS_MODELS)[number]
+
+/**
+ * Gemini Text-to-Speech Adapter
+ *
+ * Tree-shakeable adapter for Gemini TTS functionality.
+ *
+ * **IMPORTANT**: Gemini TTS uses the Live API (WebSocket-based) which requires
+ * different handling than traditional REST APIs. This adapter provides a
+ * simplified interface but may have limitations.
+ *
+ * @experimental Gemini TTS is an experimental feature and may change.
+ *
+ * Models:
+ * - gemini-2.5-flash-preview-tts
+ */
+export class GeminiTTSAdapter<
+  TModel extends GeminiTTSModel,
+> extends BaseTTSAdapter<TModel, GeminiTTSProviderOptions> {
+  readonly name = 'gemini' as const
+
+  private client: GoogleGenAI
+
+  constructor(config: GeminiTTSConfig, model: TModel) {
+    super(config, model)
+    this.client = createGeminiClient(config)
+  }
+
+  /**
+   * Generate speech from text using Gemini's TTS model.
+   *
+   * @experimental This implementation is experimental and may change.
+   * @see https://ai.google.dev/gemini-api/docs/speech-generation
+   */
+  async generateSpeech(
+    options: TTSOptions<GeminiTTSProviderOptions>,
+  ): Promise<TTSResult> {
+    const { model, text, modelOptions } = options
+
+    const voiceConfig = modelOptions?.voiceConfig || {
+      prebuiltVoiceConfig: {
+        voiceName: 'Kore',
+      },
+    }
+
+    const response = await this.client.models.generateContent({
+      model,
+      contents: [
+        {
+          role: 'user',
+          parts: [{ text }],
+        },
+      ],
+      config: {
+        responseModalities: ['AUDIO'],
+        speechConfig: {
+          voiceConfig,
+          ...(modelOptions?.languageCode && {
+            languageCode: modelOptions.languageCode,
+          }),
+        },
+      },
+      ...(modelOptions?.systemInstruction && {
+        systemInstruction: modelOptions.systemInstruction,
+      }),
+    })
+
+    // Extract audio data from response
+    const candidate = response.candidates?.[0]
+    const parts = candidate?.content?.parts
+
+    if (!parts || parts.length === 0) {
+      throw new Error('No audio output received from Gemini TTS')
+    }
+
+    // Look for inline data (audio)
+    const audioPart = parts.find((part: any) =>
+      part.inlineData?.mimeType?.startsWith('audio/'),
+    )
+
+    if (!audioPart || !audioPart.inlineData || !audioPart.inlineData.data) {
+      throw new Error('No audio data in Gemini TTS response')
+    }
+
+    const audioBase64 = audioPart.inlineData.data
+    const mimeType = audioPart.inlineData.mimeType || 'audio/wav'
+    const format = mimeType.split('/')[1] || 'wav'
+
+    return {
+      id: generateId(this.name),
+      model,
+      audio: audioBase64,
+      format,
+      contentType: mimeType,
+    }
+  }
+}
+
+/**
+ * Creates a Gemini TTS adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @experimental Gemini TTS is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')
+ * @param apiKey - Your Google API key
+ * @param config - Optional additional configuration
+ * @returns Configured Gemini TTS adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGeminiSpeech('gemini-2.5-flash-preview-tts', "your-api-key");
+ *
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'Hello, world!'
+ * });
+ * ```
+ */
+export function createGeminiSpeech<TModel extends GeminiTTSModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GeminiTTSConfig, 'apiKey'>,
+): GeminiTTSAdapter<TModel> {
+  return new GeminiTTSAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Gemini speech adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * @experimental Gemini TTS is an experimental feature and may change.
+ *
+ * Looks for `GOOGLE_API_KEY` or `GEMINI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @param model - The model name (e.g., 'gemini-2.5-flash-preview-tts')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Gemini speech adapter instance with resolved types
+ * @throws Error if GOOGLE_API_KEY or GEMINI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses GOOGLE_API_KEY from environment
+ * const adapter = geminiSpeech('gemini-2.5-flash-preview-tts');
+ *
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'Welcome to TanStack AI!'
+ * });
+ * ```
+ */
+export function geminiSpeech<TModel extends GeminiTTSModel>(
+  model: TModel,
+  config?: Omit<GeminiTTSConfig, 'apiKey'>,
+): GeminiTTSAdapter<TModel> {
+  const apiKey = getGeminiApiKeyFromEnv()
+  return createGeminiSpeech(model, apiKey, config)
+}

package/src/image/image-provider-options.ts

@@ -0,0 +1,239 @@
+import type { GeminiImageModels } from '../model-meta'
+import type {
+  ImagePromptLanguage,
+  PersonGeneration,
+  SafetyFilterLevel,
+} from '@google/genai'
+
+// Re-export SDK types so users can use them directly
+export type { ImagePromptLanguage, PersonGeneration, SafetyFilterLevel }
+
+/**
+ * Gemini Imagen aspect ratio options
+ * Controls the aspect ratio of generated images
+ */
+export type GeminiAspectRatio =
+  | '1:1'
+  | '3:4'
+  | '4:3'
+  | '9:16'
+  | '16:9'
+  | '9:21'
+  | '21:9'
+
+/**
+ * Provider options for Gemini image generation
+ * These options match the @google/genai GenerateImagesConfig interface
+ * and can be spread directly into the API request.
+ */
+export interface GeminiImageProviderOptions {
+  /**
+   * The aspect ratio of generated images
+   * @default '1:1'
+   */
+  aspectRatio?: GeminiAspectRatio
+
+  /**
+   * Controls whether people can appear in generated images
+   * Use PersonGeneration enum values: DONT_ALLOW, ALLOW_ADULT, ALLOW_ALL
+   * @default 'ALLOW_ADULT'
+   */
+  personGeneration?: PersonGeneration
+
+  /**
+   * Safety filter level for content filtering
+   * Use SafetyFilterLevel enum values
+   */
+  safetyFilterLevel?: SafetyFilterLevel
+
+  /**
+   * Optional seed for reproducible image generation
+   * When the same seed is used with the same prompt and settings,
+   * you should get similar (though not identical) results
+   */
+  seed?: number
+
+  /**
+   * Whether to add a SynthID watermark to generated images
+   * SynthID helps identify AI-generated content
+   * @default true
+   */
+  addWatermark?: boolean
+
+  /**
+   * Language of the prompt
+   * Use ImagePromptLanguage enum values
+   */
+  language?: ImagePromptLanguage
+
+  /**
+   * Negative prompt - what to avoid in the generated image
+   * Not all models support negative prompts
+   */
+  negativePrompt?: string
+
+  /**
+   * Output MIME type for the generated image
+   * @default 'image/png'
+   */
+  outputMimeType?: 'image/png' | 'image/jpeg' | 'image/webp'
+
+  /**
+   * Compression quality for JPEG outputs (0-100)
+   * Higher values mean better quality but larger file sizes
+   * @default 75
+   */
+  outputCompressionQuality?: number
+
+  /**
+   * Controls how much the model adheres to the text prompt
+   * Large values increase output and prompt alignment,
+   * but may compromise image quality
+   */
+  guidanceScale?: number
+
+  /**
+   * Whether to use the prompt rewriting logic
+   */
+  enhancePrompt?: boolean
+
+  /**
+   * Whether to report the safety scores of each generated image
+   * and the positive prompt in the response
+   */
+  includeSafetyAttributes?: boolean
+
+  /**
+   * Whether to include the Responsible AI filter reason
+   * if the image is filtered out of the response
+   */
+  includeRaiReason?: boolean
+
+  /**
+   * Cloud Storage URI used to store the generated images
+   */
+  outputGcsUri?: string
+
+  /**
+   * User specified labels to track billing usage
+   */
+  labels?: Record<string, string>
+}
+
+/**
+ * Model-specific provider options mapping
+ * Currently all Imagen models use the same options structure
+ */
+export type GeminiImageModelProviderOptionsByName = {
+  [K in GeminiImageModels]: GeminiImageProviderOptions
+}
+
+/**
+ * Supported size strings for Gemini Imagen models
+ * These map to aspect ratios internally
+ */
+export type GeminiImageSize =
+  | '1024x1024'
+  | '512x512'
+  | '1024x768'
+  | '1536x1024'
+  | '1792x1024'
+  | '1920x1080'
+  | '768x1024'
+  | '1024x1536'
+  | '1024x1792'
+  | '1080x1920'
+
+/**
+ * Model-specific size options mapping
+ * All Imagen models use the same size options
+ */
+export type GeminiImageModelSizeByName = {
+  [K in GeminiImageModels]: GeminiImageSize
+}
+
+/**
+ * Valid sizes for Gemini Imagen models
+ * Gemini uses aspect ratios, but we map common WIDTHxHEIGHT formats to aspect ratios
+ * These are approximate mappings based on common image dimensions
+ */
+export const GEMINI_SIZE_TO_ASPECT_RATIO: Record<string, GeminiAspectRatio> = {
+  // Square
+  '1024x1024': '1:1',
+  '512x512': '1:1',
+  // Landscape
+  '1024x768': '4:3',
+  '1536x1024': '4:3',
+  '1792x1024': '16:9',
+  '1920x1080': '16:9',
+  // Portrait
+  '768x1024': '3:4',
+  '1024x1536': '3:4', // Inverted
+  '1024x1792': '9:16',
+  '1080x1920': '9:16',
+}
+
+/**
+ * Maps a WIDTHxHEIGHT size string to a Gemini aspect ratio
+ * Returns undefined if the size cannot be mapped
+ */
+export function sizeToAspectRatio(
+  size: string | undefined,
+): GeminiAspectRatio | undefined {
+  if (!size) return undefined
+  return GEMINI_SIZE_TO_ASPECT_RATIO[size]
+}
+
+/**
+ * Validates that the provided size can be mapped to an aspect ratio
+ * Throws an error if the size is invalid
+ */
+export function validateImageSize(
+  model: string,
+  size: string | undefined,
+): void {
+  if (!size) return
+
+  const aspectRatio = sizeToAspectRatio(size)
+  if (!aspectRatio) {
+    const validSizes = Object.keys(GEMINI_SIZE_TO_ASPECT_RATIO)
+    throw new Error(
+      `Invalid size "${size}" for model "${model}". ` +
+        `Gemini Imagen uses aspect ratios. Valid sizes that map to aspect ratios: ${validSizes.join(', ')}. ` +
+        `Alternatively, use providerOptions.aspectRatio directly with values: 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9`,
+    )
+  }
+}
+
+/**
+ * Validates the number of images requested
+ * Imagen models support 1-8 images per request (varies by model)
+ */
+export function validateNumberOfImages(
+  model: string,
+  numberOfImages: number | undefined,
+): void {
+  if (numberOfImages === undefined) return
+
+  // Most Imagen models support 1-4 images, some support up to 8
+  const maxImages = 4
+  if (numberOfImages < 1 || numberOfImages > maxImages) {
+    throw new Error(
+      `Invalid numberOfImages "${numberOfImages}" for model "${model}". ` +
+        `Must be between 1 and ${maxImages}.`,
+    )
+  }
+}
+
+/**
+ * Validates the prompt is not empty
+ */
+export function validatePrompt(options: {
+  prompt: string
+  model: string
+}): void {
+  const { prompt, model } = options
+  if (!prompt || prompt.trim().length === 0) {
+    throw new Error(`Prompt cannot be empty for model "${model}".`)
+  }
+}

package/src/index.ts

@@ -1,5 +1,69 @@
-export { GeminiAdapter, createGemini, gemini } from './gemini-adapter'
-export type { GeminiAdapterConfig } from './gemini-adapter'
+// ===========================
+// New tree-shakeable adapters
+// ===========================
+
+// Text/Chat adapter
+export {
+  GeminiTextAdapter,
+  createGeminiChat,
+  geminiText,
+  type GeminiTextConfig,
+  type GeminiTextProviderOptions,
+} from './adapters/text'
+
+// Summarize adapter
+export {
+  GeminiSummarizeAdapter,
+  GeminiSummarizeModels,
+  createGeminiSummarize,
+  geminiSummarize,
+  type GeminiSummarizeAdapterOptions,
+  type GeminiSummarizeModel,
+  type GeminiSummarizeProviderOptions,
+} from './adapters/summarize'
+
+// Image adapter
+export {
+  GeminiImageAdapter,
+  createGeminiImage,
+  geminiImage,
+  type GeminiImageConfig,
+} from './adapters/image'
+export type {
+  GeminiImageProviderOptions,
+  GeminiImageModelProviderOptionsByName,
+  GeminiAspectRatio,
+  // Re-export SDK types for convenience
+  PersonGeneration,
+  SafetyFilterLevel,
+  ImagePromptLanguage,
+} from './image/image-provider-options'
+
+// TTS adapter (experimental)
+/**
+ * @experimental Gemini TTS is an experimental feature and may change.
+ */
+export {
+  GeminiTTSAdapter,
+  createGeminiSpeech,
+  geminiSpeech,
+  type GeminiTTSConfig,
+  type GeminiTTSProviderOptions,
+} from './adapters/tts'
+
+// Re-export models from model-meta for convenience
+export { GEMINI_MODELS as GeminiTextModels } from './model-meta'
+export { GEMINI_IMAGE_MODELS as GeminiImageModels } from './model-meta'
+export { GEMINI_TTS_MODELS as GeminiTTSModels } from './model-meta'
+export { GEMINI_TTS_VOICES as GeminiTTSVoices } from './model-meta'
+export type { GeminiModels as GeminiTextModel } from './model-meta'
+export type { GeminiImageModels as GeminiImageModel } from './model-meta'
+export type { GeminiTTSVoice } from './model-meta'
+
+// ===========================
+// Type Exports
+// ===========================
+
 export type {
   GeminiChatModelProviderOptionsByName,
   GeminiModelInputModalitiesByName,