@tanstack/ai-gemini 0.20.1 → 0.22.0

package/src/adapters/embedding.ts

@@ -0,0 +1,173 @@
+import { BaseEmbeddingAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { requireTextOnlyEmbeddingInput } from '@tanstack/ai'
+import {
+  createGeminiClient,
+  generateId,
+  getGeminiApiKeyFromEnv,
+} from '../utils'
+import type { EmbeddingOptions, EmbeddingResult } from '@tanstack/ai'
+import type { EmbedContentConfig, GoogleGenAI } from '@google/genai'
+import type {
+  GeminiEmbeddingModel,
+  GeminiEmbeddingModelInputModalitiesByName,
+  GeminiEmbeddingModelProviderOptionsByName,
+} from '../model-meta'
+import type { GeminiEmbeddingProviderOptions } from '../embedding/embedding-provider-options'
+import type { GeminiClientConfig } from '../utils/client'
+
+/**
+ * Configuration for Gemini Embedding adapter
+ */
+export interface GeminiEmbeddingConfig extends GeminiClientConfig {}
+
+/**
+ * Gemini Embedding Adapter
+ *
+ * Tree-shakeable adapter for Gemini text embeddings.
+ * Supports gemini-embedding-001.
+ *
+ * Features:
+ * - Batch embedding (one request for the whole input array)
+ * - Matryoshka dimension reduction via the top-level `dimensions` option
+ *   (mapped to the SDK's `outputDimensionality`)
+ * - Task-type hints (`taskType`, `title`) via provider options
+ */
+export class GeminiEmbeddingAdapter<
+  TModel extends GeminiEmbeddingModel,
+> extends BaseEmbeddingAdapter<
+  TModel,
+  GeminiEmbeddingProviderOptions,
+  GeminiEmbeddingModelProviderOptionsByName,
+  GeminiEmbeddingModelInputModalitiesByName
+> {
+  readonly name = 'gemini' as const
+
+  protected client: GoogleGenAI
+
+  constructor(config: GeminiEmbeddingConfig, model: TModel) {
+    super(model, {})
+    this.client = createGeminiClient(config)
+  }
+
+  async createEmbeddings(
+    options: EmbeddingOptions<GeminiEmbeddingProviderOptions>,
+  ): Promise<EmbeddingResult> {
+    const { model, logger, modelOptions } = options
+    const texts = requireTextOnlyEmbeddingInput(options.input, this.name, model)
+
+    try {
+      // Build the config incrementally so possibly-undefined values are never
+      // assigned to optional fields (exactOptionalPropertyTypes).
+      const config: EmbedContentConfig = {}
+      if (options.dimensions !== undefined) {
+        config.outputDimensionality = options.dimensions
+      }
+      if (modelOptions?.taskType !== undefined) {
+        config.taskType = modelOptions.taskType
+      }
+      if (modelOptions?.title !== undefined) {
+        config.title = modelOptions.title
+      }
+
+      logger.request(
+        `activity=embed provider=${this.name} model=${model} inputs=${texts.length}`,
+        { provider: this.name, model },
+      )
+
+      const response = await this.client.models.embedContent({
+        model,
+        contents: texts,
+        config,
+      })
+
+      const embeddings = response.embeddings
+      if (!embeddings || embeddings.length !== texts.length) {
+        throw new Error(
+          `Gemini embedContent returned ${embeddings ? embeddings.length : 'no'} embeddings for ${texts.length} inputs (model: ${model}).`,
+        )
+      }
+
+      // The Gemini embedding API does not report token usage, so `usage` is
+      // omitted from the result.
+      return {
+        id: generateId(this.name),
+        model,
+        embeddings: embeddings.map((embedding, index) => ({
+          vector: embedding.values ?? [],
+          index,
+        })),
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.createEmbeddings fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.createEmbeddings failed`),
+        source: `${this.name}.createEmbeddings`,
+      })
+      throw error
+    }
+  }
+}
+
+/**
+ * Creates a Gemini embedding adapter with explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'gemini-embedding-001')
+ * @param apiKey - Your Google API key
+ * @param config - Optional additional configuration
+ * @returns Configured Gemini embedding adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGeminiEmbedding('gemini-embedding-001', "your-api-key");
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: 'a red guitar'
+ * });
+ * ```
+ */
+export function createGeminiEmbedding<TModel extends GeminiEmbeddingModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GeminiEmbeddingConfig, 'apiKey'>,
+): GeminiEmbeddingAdapter<TModel> {
+  // Put apiKey LAST so caller-supplied config can't silently override the
+  // explicit argument.
+  return new GeminiEmbeddingAdapter({ ...config, apiKey }, model)
+}
+
+/**
+ * Creates a Gemini embedding adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * 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-embedding-001')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Gemini embedding 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 = geminiEmbedding('gemini-embedding-001');
+ *
+ * const result = await embed({
+ *   adapter,
+ *   input: ['a red guitar', 'a blue drum kit'],
+ *   dimensions: 1536
+ * });
+ *
+ * console.log(result.embeddings[0].vector)
+ * ```
+ */
+export function geminiEmbedding<TModel extends GeminiEmbeddingModel>(
+  model: TModel,
+  config?: Omit<GeminiEmbeddingConfig, 'apiKey'>,
+): GeminiEmbeddingAdapter<TModel> {
+  const apiKey = getGeminiApiKeyFromEnv()
+  return createGeminiEmbedding(model, apiKey, config)
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Provider options for Gemini embedding models.
+ *
+ * `dimensions` is deliberately absent: it's a first-class top-level option on
+ * `embed()` and is mapped to the SDK's `outputDimensionality` by the adapter.
+ */
+export interface GeminiEmbeddingProviderOptions {
+  /**
+   * Type of task for which the embedding will be used. Helps the model
+   * produce embeddings optimized for the intended use case.
+   *
+   * @see https://ai.google.dev/gemini-api/docs/embeddings#task-types
+   */
+  taskType?:
+    | 'SEMANTIC_SIMILARITY'
+    | 'CLASSIFICATION'
+    | 'CLUSTERING'
+    | 'RETRIEVAL_DOCUMENT'
+    | 'RETRIEVAL_QUERY'
+    | 'QUESTION_ANSWERING'
+    | 'FACT_VERIFICATION'
+    | 'CODE_RETRIEVAL_QUERY'
+
+  /**
+   * Title for the text. Only applicable when `taskType` is
+   * `RETRIEVAL_DOCUMENT`.
+   */
+  title?: string
+}

package/src/index.ts

@@ -36,6 +36,15 @@ export type {
   ImagePromptLanguage,
 } from './image/image-provider-options'
 
+// Embedding adapter - for embedding vectors
+export {
+  GeminiEmbeddingAdapter,
+  createGeminiEmbedding,
+  geminiEmbedding,
+  type GeminiEmbeddingConfig,
+} from './adapters/embedding'
+export type { GeminiEmbeddingProviderOptions } from './embedding/embedding-provider-options'
+
 // TTS adapter (experimental)
 /**
  * @experimental Gemini TTS is an experimental feature and may change.
@@ -100,6 +109,7 @@ export { GEMINI_TTS_VOICES as GeminiTTSVoices } from './model-meta'
 export { GEMINI_AUDIO_MODELS as GeminiAudioModels } from './model-meta'
 export { GEMINI_VIDEO_MODELS as GeminiVideoModels } from './model-meta'
 export { GEMINI_INTERACTIONS_VIDEO_MODELS as GeminiInteractionsVideoModels } from './model-meta'
+export { GEMINI_EMBEDDING_MODELS } 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'
@@ -112,6 +122,9 @@ export type {
   GeminiChatModelProviderOptionsByName,
   GeminiChatModelToolCapabilitiesByName,
   GeminiModelInputModalitiesByName,
+  GeminiEmbeddingModel,
+  GeminiEmbeddingModelProviderOptionsByName,
+  GeminiEmbeddingModelInputModalitiesByName,
 } from './model-meta'
 export type {
   GeminiStructuredOutputOptions,

package/src/model-meta.ts

@@ -6,6 +6,7 @@ import type {
   GeminiThinkingOptions,
   GeminiToolConfigOptions,
 } from './text/text-provider-options'
+import type { GeminiEmbeddingProviderOptions } from './embedding/embedding-provider-options'
 
 interface ModelMeta<TProviderOptions = unknown> {
   name: string
@@ -743,6 +744,48 @@ const GEMINI_OMNI_FLASH_PREVIEW = {
     GeminiCachedContentOptions
 >
 
+const GEMINI_3_6_FLASH = {
+  name: 'gemini-3.6-flash',
+  max_input_tokens: 1_048_576,
+  max_output_tokens: 65_536,
+  knowledge_cutoff: '2026-03-01',
+  supports: {
+    input: ['text', 'image', 'video', 'audio', 'document'],
+    output: ['text'],
+    capabilities: [
+      'batch_api',
+      'caching',
+      'function_calling',
+      'structured_output',
+      'thinking',
+    ],
+    tools: [
+      'code_execution',
+      'file_search',
+      'google_search',
+      'google_maps',
+      'url_context',
+      'computer_use',
+    ],
+  },
+  pricing: {
+    input: {
+      normal: 1.5,
+      cached: 0.15,
+    },
+    output: {
+      normal: 7.5,
+    },
+  },
+} as const satisfies ModelMeta<
+  GeminiToolConfigOptions &
+    GeminiSafetyOptions &
+    GeminiCommonConfigOptions &
+    GeminiCachedContentOptions &
+    GeminiStructuredOutputOptions &
+    GeminiThinkingOptions
+>
+
 const GEMINI_3_5_FLASH = {
   name: 'gemini-3.5-flash',
   max_input_tokens: 1_048_576,
@@ -757,7 +800,14 @@ const GEMINI_3_5_FLASH = {
       'structured_output',
       'thinking',
     ],
-    tools: ['code_execution', 'file_search', 'google_search', 'url_context'],
+    tools: [
+      'code_execution',
+      'file_search',
+      'google_search',
+      'google_maps',
+      'url_context',
+      'computer_use',
+    ],
   },
   pricing: {
     input: {
@@ -777,8 +827,51 @@ const GEMINI_3_5_FLASH = {
     GeminiThinkingOptions
 >
 
+const GEMINI_3_5_FLASH_LITE = {
+  name: 'gemini-3.5-flash-lite',
+  max_input_tokens: 1_048_576,
+  max_output_tokens: 65_536,
+  knowledge_cutoff: '2025-01-01',
+  supports: {
+    input: ['text', 'image', 'video', 'audio', 'document'],
+    output: ['text'],
+    capabilities: [
+      'batch_api',
+      'caching',
+      'function_calling',
+      'structured_output',
+      'thinking',
+    ],
+    tools: [
+      'code_execution',
+      'file_search',
+      'google_search',
+      'google_maps',
+      'url_context',
+    ],
+  },
+  pricing: {
+    input: {
+      normal: 0.3,
+      cached: 0.03,
+    },
+    output: {
+      normal: 2.5,
+    },
+  },
+} as const satisfies ModelMeta<
+  GeminiToolConfigOptions &
+    GeminiSafetyOptions &
+    GeminiCommonConfigOptions &
+    GeminiCachedContentOptions &
+    GeminiStructuredOutputOptions &
+    GeminiThinkingOptions
+>
+
 export const GEMINI_MODELS = [
+  GEMINI_3_6_FLASH.name,
   GEMINI_3_5_FLASH.name,
+  GEMINI_3_5_FLASH_LITE.name,
   GEMINI_3_1_PRO.name,
   GEMINI_3_FLASH.name,
   GEMINI_3_1_FLASH_LITE.name,
@@ -796,11 +889,13 @@ export const GEMINI_MODELS = [
  * brittle and keeps the engine's legacy finalization fallback.
  */
 export const GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
+  GEMINI_3_6_FLASH.name,
+  GEMINI_3_5_FLASH.name,
+  GEMINI_3_5_FLASH_LITE.name,
   GEMINI_3_1_PRO.name,
   GEMINI_3_FLASH.name,
   GEMINI_3_1_FLASH_LITE.name,
   GEMINI_3_1_FLASH_LITE_PREVIEW.name,
-  GEMINI_3_5_FLASH.name,
 ])
 
 export type GeminiModels = (typeof GEMINI_MODELS)[number]
@@ -897,9 +992,49 @@ export const GEMINI_INTERACTIONS_VIDEO_MODELS = [
   GEMINI_OMNI_FLASH_PREVIEW.name,
 ] as const
 
+/**
+ * Embedding models
+ */
+export const GEMINI_EMBEDDING_MODELS = ['gemini-embedding-001'] as const
+
+export type GeminiEmbeddingModel = (typeof GEMINI_EMBEDDING_MODELS)[number]
+
+/**
+ * Type-only map from embedding model name to its provider options type.
+ */
+export type GeminiEmbeddingModelProviderOptionsByName = {
+  'gemini-embedding-001': GeminiEmbeddingProviderOptions
+}
+
+/**
+ * Per-model input modalities for embedding models. Gemini embedding models
+ * are text-only, so image inputs fail at compile time.
+ */
+export type GeminiEmbeddingModelInputModalitiesByName = {
+  'gemini-embedding-001': readonly ['text']
+}
+
 // Manual type map for per-model provider options
 export type GeminiChatModelProviderOptionsByName = {
   // Models with thinking and structured output support
+  [GEMINI_3_6_FLASH.name]: GeminiToolConfigOptions &
+    GeminiSafetyOptions &
+    GeminiCommonConfigOptions &
+    GeminiCachedContentOptions &
+    GeminiStructuredOutputOptions &
+    GeminiThinkingOptions
+  [GEMINI_3_5_FLASH.name]: GeminiToolConfigOptions &
+    GeminiSafetyOptions &
+    GeminiCommonConfigOptions &
+    GeminiCachedContentOptions &
+    GeminiStructuredOutputOptions &
+    GeminiThinkingOptions
+  [GEMINI_3_5_FLASH_LITE.name]: GeminiToolConfigOptions &
+    GeminiSafetyOptions &
+    GeminiCommonConfigOptions &
+    GeminiCachedContentOptions &
+    GeminiStructuredOutputOptions &
+    GeminiThinkingOptions
   [GEMINI_3_1_PRO.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
@@ -942,12 +1077,6 @@ export type GeminiChatModelProviderOptionsByName = {
     GeminiCachedContentOptions &
     GeminiStructuredOutputOptions &
     GeminiThinkingOptions
-  [GEMINI_3_5_FLASH.name]: GeminiToolConfigOptions &
-    GeminiSafetyOptions &
-    GeminiCommonConfigOptions &
-    GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
 }
 
 /**
@@ -955,6 +1084,9 @@ export type GeminiChatModelProviderOptionsByName = {
  * Based on the 'supports.tools' arrays defined for each model.
  */
 export type GeminiChatModelToolCapabilitiesByName = {
+  [GEMINI_3_6_FLASH.name]: typeof GEMINI_3_6_FLASH.supports.tools
+  [GEMINI_3_5_FLASH.name]: typeof GEMINI_3_5_FLASH.supports.tools
+  [GEMINI_3_5_FLASH_LITE.name]: typeof GEMINI_3_5_FLASH_LITE.supports.tools
   [GEMINI_3_1_PRO.name]: typeof GEMINI_3_1_PRO.supports.tools
   [GEMINI_3_FLASH.name]: typeof GEMINI_3_FLASH.supports.tools
   [GEMINI_3_1_FLASH_LITE.name]: typeof GEMINI_3_1_FLASH_LITE.supports.tools
@@ -962,7 +1094,6 @@ export type GeminiChatModelToolCapabilitiesByName = {
   [GEMINI_2_5_PRO.name]: typeof GEMINI_2_5_PRO.supports.tools
   [GEMINI_2_5_FLASH.name]: typeof GEMINI_2_5_FLASH.supports.tools
   [GEMINI_2_5_FLASH_LITE.name]: typeof GEMINI_2_5_FLASH_LITE.supports.tools
-  [GEMINI_3_5_FLASH.name]: typeof GEMINI_3_5_FLASH.supports.tools
 }
 
 /**
@@ -980,13 +1111,15 @@ export type GeminiChatModelToolCapabilitiesByName = {
  */
 export type GeminiModelInputModalitiesByName = {
   // Models with full multimodal support (text, image, audio, video, document)
+  [GEMINI_3_6_FLASH.name]: typeof GEMINI_3_6_FLASH.supports.input
+  [GEMINI_3_5_FLASH.name]: typeof GEMINI_3_5_FLASH.supports.input
+  [GEMINI_3_5_FLASH_LITE.name]: typeof GEMINI_3_5_FLASH_LITE.supports.input
   [GEMINI_3_1_PRO.name]: typeof GEMINI_3_1_PRO.supports.input
   [GEMINI_3_FLASH.name]: typeof GEMINI_3_FLASH.supports.input
   [GEMINI_3_1_FLASH_LITE.name]: typeof GEMINI_3_1_FLASH_LITE.supports.input
   [GEMINI_3_1_FLASH_LITE_PREVIEW.name]: typeof GEMINI_3_1_FLASH_LITE_PREVIEW.supports.input
   [GEMINI_2_5_PRO.name]: typeof GEMINI_2_5_PRO.supports.input
   [GEMINI_2_5_FLASH_LITE.name]: typeof GEMINI_2_5_FLASH_LITE.supports.input
-  [GEMINI_3_5_FLASH.name]: typeof GEMINI_3_5_FLASH.supports.input
 
   // Models with text, image, audio, video (no document)
   [GEMINI_2_5_FLASH.name]: typeof GEMINI_2_5_FLASH.supports.input

package/dist/esm/experimental/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/esm/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/esm/tools/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}