@tanstack/ai-gemini 0.9.0 → 0.10.0

package/src/adapters/image.ts

@@ -74,34 +74,50 @@ export class GeminiImageAdapter<
   private client: GoogleGenAI
 
   constructor(config: GeminiImageConfig, model: TModel) {
-    super({}, model)
+    super(model, config)
     this.client = createGeminiClient(config)
   }
 
   async generateImages(
     options: ImageGenerationOptions<GeminiImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt } = options
+    const { model, prompt, logger } = options
 
-    validatePrompt({ prompt, model })
+    logger.request(
+      `activity=generateImage provider=gemini model=${this.model}`,
+      {
+        provider: 'gemini',
+        model: this.model,
+      },
+    )
 
-    if (this.isGeminiImageModel(model)) {
-      return this.generateWithGeminiApi(options)
-    }
+    try {
+      validatePrompt({ prompt, model })
 
-    // Imagen models path (generateImages API)
-    validateImageSize(model, options.size)
-    validateNumberOfImages(model, options.numberOfImages)
+      if (this.isGeminiImageModel(model)) {
+        return await this.generateWithGeminiApi(options)
+      }
 
-    const config = this.buildImagenConfig(options)
+      // Imagen models path (generateImages API)
+      validateImageSize(model, options.size)
+      validateNumberOfImages(model, options.numberOfImages)
 
-    const response = await this.client.models.generateImages({
-      model,
-      prompt,
-      config,
-    })
+      const config = this.buildImagenConfig(options)
 
-    return this.transformImagenResponse(model, response)
+      const response = await this.client.models.generateImages({
+        model,
+        prompt,
+        config,
+      })
+
+      return this.transformImagenResponse(model, response)
+    } catch (error) {
+      logger.errors('gemini.generateImage fatal', {
+        error,
+        source: 'gemini.generateImage',
+      })
+      throw error
+    }
   }
 
   private isGeminiImageModel(model: string): boolean {
@@ -122,8 +138,24 @@ export class GeminiImageAdapter<
         ? `${prompt} Generate ${numberOfImages} distinct images.`
         : prompt
 
+    // GeminiImageProviderOptions is Imagen-shaped — most fields
+    // (personGeneration, safetyFilterLevel, addWatermark, outputMimeType,
+    // outputCompressionQuality, guidanceScale, enhancePrompt,
+    // includeSafetyAttributes, includeRaiReason, outputGcsUri, labels,
+    // negativePrompt, language) are only valid on GenerateImagesConfig and
+    // would be rejected by the Gemini-native generateContent path. Pick only
+    // the fields that are valid on GenerateContentConfig instead of spreading
+    // the whole options object.
+    const nativeConfig: GenerateContentConfig = {}
+    if (modelOptions?.seed !== undefined) {
+      nativeConfig.seed = modelOptions.seed
+    }
+
     const config: GenerateContentConfig = {
-      // Include TEXT so the model can interleave descriptions between images
+      ...nativeConfig,
+      // Include TEXT so the model can interleave descriptions between images.
+      // IMPORTANT: responseModalities is a protected default — set it AFTER
+      // nativeConfig so nothing can silently disable image output.
       responseModalities: ['TEXT', 'IMAGE'],
       ...(parsedSize && {
         imageConfig: {
@@ -135,7 +167,6 @@ export class GeminiImageAdapter<
           }),
         },
       }),
-      ...modelOptions,
     }
 
     const response = await this.client.models.generateContent({
@@ -152,6 +183,7 @@ export class GeminiImageAdapter<
     response: GenerateContentResponse,
   ): ImageGenerationResult {
     const images: Array<GeneratedImage> = []
+    const textParts: Array<string> = []
     const parts = response.candidates?.[0]?.content?.parts ?? []
 
     for (const part of parts) {
@@ -161,9 +193,23 @@ export class GeminiImageAdapter<
         part.inlineData.data.length > 0
       ) {
         images.push({ b64Json: part.inlineData.data })
+      } else if (typeof part.text === 'string' && part.text.length > 0) {
+        textParts.push(part.text)
       }
     }
 
+    // If the model returned only text parts (for example a safety refusal
+    // or a "can't do that" message), surface the text instead of silently
+    // resolving to an empty images array — otherwise callers can't tell a
+    // generation failure apart from a genuine empty response.
+    if (images.length === 0) {
+      const reason =
+        textParts.length > 0
+          ? `: ${textParts.join(' ').trim()}`
+          : ' (no inline image or text parts were returned).'
+      throw new Error(`Gemini ${model} returned no images${reason}`)
+    }
+
     return {
       id: generateId(this.name),
       model,
@@ -189,12 +235,43 @@ export class GeminiImageAdapter<
     model: string,
     response: GenerateImagesResponse,
   ): ImageGenerationResult {
-    const images: Array<GeneratedImage> = (response.generatedImages ?? []).map(
-      (item) => ({
-        b64Json: item.image?.imageBytes,
-        revisedPrompt: item.enhancedPrompt,
-      }),
-    )
+    const entries = response.generatedImages ?? []
+    const images: Array<GeneratedImage> = []
+    const filterReasons: Array<string> = []
+
+    for (const item of entries) {
+      const b64Json = item.image?.imageBytes
+      if (b64Json) {
+        images.push({ b64Json, revisedPrompt: item.enhancedPrompt })
+        continue
+      }
+      // Imagen can drop individual entries with a raiFilteredReason when
+      // Responsible-AI filters fire. Preserve the reason so callers can
+      // surface it instead of silently getting back fewer images.
+      const reason = (item as { raiFilteredReason?: string }).raiFilteredReason
+      if (reason) {
+        filterReasons.push(reason)
+      }
+    }
+
+    // Every entry was filtered — no usable images to return. Throw rather
+    // than resolve to an empty array so the caller is forced to handle the
+    // failure mode explicitly.
+    if (entries.length > 0 && images.length === 0) {
+      const joined = filterReasons.length > 0 ? filterReasons.join('; ') : ''
+      throw new Error(
+        `Imagen ${model} returned no images: all ${entries.length} generated image(s) were filtered by Responsible-AI${joined ? ` (${joined})` : ''}.`,
+      )
+    }
+
+    // Partial filter: surface via console.warn since ImageGenerationResult
+    // has no warnings field. Callers that care can still inspect the count
+    // mismatch between requested and returned images.
+    if (filterReasons.length > 0 && typeof console !== 'undefined') {
+      console.warn(
+        `[gemini-image] ${filterReasons.length} of ${entries.length} images from ${model} were filtered by Responsible-AI: ${filterReasons.join('; ')}`,
+      )
+    }
 
     return {
       id: generateId(this.name),

package/src/adapters/summarize.ts

@@ -81,8 +81,14 @@ export class GeminiSummarizeAdapter<
   }
 
   async summarize(options: SummarizationOptions): Promise<SummarizationResult> {
+    const { logger } = options
     const model = options.model
 
+    logger.request(`activity=summarize provider=gemini`, {
+      provider: 'gemini',
+      model,
+    })
+
     // Build the system prompt based on format
     const formatInstructions = this.getFormatInstructions(options.style)
     const lengthInstructions = options.maxLength
@@ -91,40 +97,49 @@ export class GeminiSummarizeAdapter<
 
     const systemPrompt = `You are a helpful assistant that summarizes text. ${formatInstructions}${lengthInstructions}`
 
-    const response = await this.client.models.generateContent({
-      model,
-      contents: [
-        {
-          role: 'user',
-          parts: [
-            { text: `Please summarize the following:\n\n${options.text}` },
-          ],
+    try {
+      const response = await this.client.models.generateContent({
+        model,
+        contents: [
+          {
+            role: 'user',
+            parts: [
+              { text: `Please summarize the following:\n\n${options.text}` },
+            ],
+          },
+        ],
+        config: {
+          systemInstruction: systemPrompt,
         },
-      ],
-      config: {
-        systemInstruction: systemPrompt,
-      },
-    })
+      })
 
-    const summary = response.text ?? ''
-    const inputTokens = response.usageMetadata?.promptTokenCount ?? 0
-    const outputTokens = response.usageMetadata?.candidatesTokenCount ?? 0
+      const summary = response.text ?? ''
+      const inputTokens = response.usageMetadata?.promptTokenCount ?? 0
+      const outputTokens = response.usageMetadata?.candidatesTokenCount ?? 0
 
-    return {
-      id: generateId('sum'),
-      model,
-      summary,
-      usage: {
-        promptTokens: inputTokens,
-        completionTokens: outputTokens,
-        totalTokens: inputTokens + outputTokens,
-      },
+      return {
+        id: generateId('sum'),
+        model,
+        summary,
+        usage: {
+          promptTokens: inputTokens,
+          completionTokens: outputTokens,
+          totalTokens: inputTokens + outputTokens,
+        },
+      }
+    } catch (error) {
+      logger.errors('gemini.summarize fatal', {
+        error,
+        source: 'gemini.summarize',
+      })
+      throw error
     }
   }
 
   async *summarizeStream(
     options: SummarizationOptions,
   ): AsyncIterable<StreamChunk> {
+    const { logger } = options
     const model = options.model
     const id = generateId('sum')
     let accumulatedContent = ''
@@ -139,69 +154,85 @@ export class GeminiSummarizeAdapter<
 
     const systemPrompt = `You are a helpful assistant that summarizes text. ${formatInstructions}${lengthInstructions}`
 
-    const result = await this.client.models.generateContentStream({
+    logger.request(`activity=summarize provider=gemini`, {
+      provider: 'gemini',
       model,
-      contents: [
-        {
-          role: 'user',
-          parts: [
-            { text: `Please summarize the following:\n\n${options.text}` },
-          ],
-        },
-      ],
-      config: {
-        systemInstruction: systemPrompt,
-      },
+      stream: true,
     })
 
-    for await (const chunk of result) {
-      // Track usage metadata
-      if (chunk.usageMetadata) {
-        inputTokens = chunk.usageMetadata.promptTokenCount ?? inputTokens
-        outputTokens = chunk.usageMetadata.candidatesTokenCount ?? outputTokens
-      }
+    try {
+      const result = await this.client.models.generateContentStream({
+        model,
+        contents: [
+          {
+            role: 'user',
+            parts: [
+              { text: `Please summarize the following:\n\n${options.text}` },
+            ],
+          },
+        ],
+        config: {
+          systemInstruction: systemPrompt,
+        },
+      })
 
-      if (chunk.candidates?.[0]?.content?.parts) {
-        for (const part of chunk.candidates[0].content.parts) {
-          if (part.text) {
-            accumulatedContent += part.text
-            yield asChunk({
-              type: 'TEXT_MESSAGE_CONTENT',
-              messageId: id,
-              model,
-              timestamp: Date.now(),
-              delta: part.text,
-              content: accumulatedContent,
-            })
+      for await (const chunk of result) {
+        logger.provider(`provider=gemini`, { chunk })
+        // Track usage metadata
+        if (chunk.usageMetadata) {
+          inputTokens = chunk.usageMetadata.promptTokenCount ?? inputTokens
+          outputTokens =
+            chunk.usageMetadata.candidatesTokenCount ?? outputTokens
+        }
+
+        if (chunk.candidates?.[0]?.content?.parts) {
+          for (const part of chunk.candidates[0].content.parts) {
+            if (part.text) {
+              accumulatedContent += part.text
+              yield asChunk({
+                type: 'TEXT_MESSAGE_CONTENT',
+                messageId: id,
+                model,
+                timestamp: Date.now(),
+                delta: part.text,
+                content: accumulatedContent,
+              })
+            }
           }
         }
-      }
 
-      // Check for finish reason
-      const finishReason = chunk.candidates?.[0]?.finishReason
-      if (
-        finishReason === FinishReason.STOP ||
-        finishReason === FinishReason.MAX_TOKENS ||
-        finishReason === FinishReason.SAFETY
-      ) {
-        yield asChunk({
-          type: 'RUN_FINISHED',
-          runId: id,
-          model,
-          timestamp: Date.now(),
-          finishReason:
-            finishReason === FinishReason.STOP
-              ? 'stop'
-              : finishReason === FinishReason.MAX_TOKENS
-                ? 'length'
-                : 'content_filter',
-          usage: {
-            promptTokens: inputTokens,
-            completionTokens: outputTokens,
-            totalTokens: inputTokens + outputTokens,
-          },
-        })
+        // Check for finish reason
+        const finishReason = chunk.candidates?.[0]?.finishReason
+        if (
+          finishReason === FinishReason.STOP ||
+          finishReason === FinishReason.MAX_TOKENS ||
+          finishReason === FinishReason.SAFETY
+        ) {
+          yield asChunk({
+            type: 'RUN_FINISHED',
+            runId: id,
+            model,
+            timestamp: Date.now(),
+            finishReason:
+              finishReason === FinishReason.STOP
+                ? 'stop'
+                : finishReason === FinishReason.MAX_TOKENS
+                  ? 'length'
+                  : 'content_filter',
+            usage: {
+              promptTokens: inputTokens,
+              completionTokens: outputTokens,
+              totalTokens: inputTokens + outputTokens,
+            },
+          })
+        }
       }
+    } catch (error) {
+      logger.errors('gemini.summarize fatal', {
+        error,
+        source: 'gemini.summarize',
+      })
+      throw error
     }
   }
 

package/src/adapters/text.ts

@@ -16,6 +16,7 @@ import type {
   StructuredOutputOptions,
   StructuredOutputResult,
 } from '@tanstack/ai/adapters'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type {
   Content,
   GenerateContentParameters,
@@ -119,14 +120,23 @@ export class GeminiTextAdapter<
     options: TextOptions<GeminiTextProviderOptions>,
   ): AsyncIterable<StreamChunk> {
     const mappedOptions = this.mapCommonOptionsToGemini(options)
+    const { logger } = options
 
     try {
+      logger.request(
+        `activity=chat provider=gemini model=${this.model} messages=${options.messages.length} tools=${options.tools?.length ?? 0} stream=true`,
+        { provider: 'gemini', model: this.model },
+      )
       const result =
         await this.client.models.generateContentStream(mappedOptions)
 
-      yield* this.processStreamChunks(result, options)
+      yield* this.processStreamChunks(result, options, logger)
     } catch (error) {
       const timestamp = Date.now()
+      logger.errors('gemini.chatStream fatal', {
+        error,
+        source: 'gemini.chatStream',
+      })
       yield asChunk({
         type: 'RUN_ERROR',
         model: options.model,
@@ -154,10 +164,15 @@ export class GeminiTextAdapter<
     options: StructuredOutputOptions<GeminiTextProviderOptions>,
   ): Promise<StructuredOutputResult<unknown>> {
     const { chatOptions, outputSchema } = options
+    const { logger } = chatOptions
 
     const mappedOptions = this.mapCommonOptionsToGemini(chatOptions)
 
     try {
+      logger.request(
+        `activity=chat provider=gemini model=${this.model} messages=${chatOptions.messages.length} tools=${chatOptions.tools?.length ?? 0} stream=false`,
+        { provider: 'gemini', model: this.model },
+      )
       // Add structured output configuration
       const result = await this.client.models.generateContent({
         ...mappedOptions,
@@ -186,6 +201,10 @@ export class GeminiTextAdapter<
         rawText,
       }
     } catch (error) {
+      logger.errors('gemini.structuredOutput fatal', {
+        error,
+        source: 'gemini.structuredOutput',
+      })
       throw new Error(
         error instanceof Error
           ? error.message
@@ -214,6 +233,7 @@ export class GeminiTextAdapter<
   private async *processStreamChunks(
     result: AsyncGenerator<GenerateContentResponse, unknown, unknown>,
     options: TextOptions<GeminiTextProviderOptions>,
+    logger: InternalLogger,
   ): AsyncIterable<StreamChunk> {
     const model = options.model
     const timestamp = Date.now()
@@ -243,6 +263,7 @@ export class GeminiTextAdapter<
     let hasEmittedStepStarted = false
 
     for await (const chunk of result) {
+      logger.provider(`provider=gemini`, { chunk })
       // Emit RUN_STARTED on first chunk
       if (!hasEmittedRunStarted) {
         hasEmittedRunStarted = true