@tanstack/ai-gemini 0.0.1

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

@@ -0,0 +1,246 @@
+import type {
+  MediaResolution,
+  SafetySetting,
+  Schema,
+  ThinkingLevel,
+  ToolConfig,
+} from '@google/genai'
+
+export interface GeminiToolConfigOptions {
+  /**
+   * Tool configuration for any Tool specified in the request.
+   */
+  toolConfig?: ToolConfig
+}
+
+export interface GeminiSafetyOptions {
+  /**
+   *  list of unique SafetySetting instances for blocking unsafe content.
+
+This will be enforced on the GenerateContentRequest.contents and GenerateContentResponse.candidates. There should not be more than one setting for each SafetyCategory type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each SafetyCategory specified in the safetySettings. If there is no SafetySetting for a given SafetyCategory provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY are supported
+   */
+  safetySettings?: Array<SafetySetting>
+}
+
+export interface GeminiGenerationConfigOptions {
+  /**
+   * Configuration options for model generation and outputs.
+   */
+  generationConfig?: {
+    /**
+     * The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a stop_sequence. The stop sequence will not be included as part of the response.
+     */
+    stopSequences?: Array<string>
+    /**
+     * The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response.
+
+A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned.
+     */
+    responseModalities?: Array<
+      'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'AUDIO'
+    >
+    /**
+     *  Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)
+     */
+    candidateCount?: number
+    /**
+     * The maximum number of tokens to consider when sampling.
+
+Gemini models use Top-p (nucleus) sampling or a combination of Top-k and nucleus sampling. Top-k sampling considers the set of topK most probable tokens. Models running with nucleus sampling don't allow topK setting.
+
+Note: The default value varies by Model and is specified by theModel.top_p attribute returned from the getModel function. An empty topK attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting topK on requests.
+     */
+    topK?: number
+    /**
+     * Seed used in decoding. If not set, the request uses a randomly generated seed.
+     */
+    seed?: number
+    /**
+     * Presence penalty applied to the next token's logprobs if the token has already been seen in the response.
+
+This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequencyPenalty for a penalty that increases with each use.
+
+A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary.
+
+A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.
+     */
+    presencePenalty?: number
+    /**
+     * Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far.
+
+A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses.
+
+Caution: A negative penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the maxOutputTokens limit.
+     */
+    frequencyPenalty?: number
+    /**
+     *  If true, export the logprobs results in response.
+     */
+    responseLogprobs?: boolean
+
+    /**
+     * Only valid if responseLogprobs=True. This sets the number of top logprobs to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].
+     */
+    logprobs?: number
+
+    /**
+     *  Enables enhanced civic answers. It may not be available for all models.
+     */
+    enableEnhancedCivicAnswers?: boolean
+
+    /**
+     * The speech generation config.
+     */
+    speechConfig?: {
+      voiceConfig: {
+        prebuiltVoiceConfig: {
+          voiceName: string
+        }
+      }
+
+      multiSpeakerVoiceConfig?: {
+        speakerVoiceConfigs?: Array<{
+          speaker: string
+          voiceConfig: {
+            prebuiltVoiceConfig: {
+              voiceName: string
+            }
+          }
+        }>
+      }
+      /**
+       * Language code (in BCP 47 format, e.g. "en-US") for speech synthesis.
+
+Valid values are: de-DE, en-AU, en-GB, en-IN, en-US, es-US, fr-FR, hi-IN, pt-BR, ar-XA, es-ES, fr-CA, id-ID, it-IT, ja-JP, tr-TR, vi-VN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, ta-IN, te-IN, nl-NL, ko-KR, cmn-CN, pl-PL, ru-RU, and th-TH.
+       */
+      languageCode?:
+        | 'de-DE'
+        | 'en-AU'
+        | 'en-GB'
+        | 'en-IN'
+        | 'en-US'
+        | 'es-US'
+        | 'fr-FR'
+        | 'hi-IN'
+        | 'pt-BR'
+        | 'ar-XA'
+        | 'es-ES'
+        | 'fr-CA'
+        | 'id-ID'
+        | 'it-IT'
+        | 'ja-JP'
+        | 'tr-TR'
+        | 'vi-VN'
+        | 'bn-IN'
+        | 'gu-IN'
+        | 'kn-IN'
+        | 'ml-IN'
+        | 'mr-IN'
+        | 'ta-IN'
+        | 'te-IN'
+        | 'nl-NL'
+        | 'ko-KR'
+        | 'cmn-CN'
+        | 'pl-PL'
+        | 'ru-RU'
+        | 'th-TH'
+    }
+    /**
+     * Config for image generation. An error will be returned if this field is set for models that don't support these config options.
+     */
+    imageConfig?: {
+      aspectRatio?:
+        | '1:1'
+        | '2:3'
+        | '3:2'
+        | '3:4'
+        | '4:3'
+        | '9:16'
+        | '16:9'
+        | '21:9'
+    }
+    /**
+     * If specified, the media resolution specified will be used.
+     */
+    mediaResolution?: MediaResolution
+  } & GeminiThinkingOptions &
+    GeminiStructuredOutputOptions
+}
+
+export interface GeminiCachedContentOptions {
+  /**
+   * The name of the content cached to use as context to serve the prediction. Format: cachedContents/{cachedContent}
+   */
+  cachedContent?: `cachedContents/${string}`
+}
+
+export interface GeminiStructuredOutputOptions {
+  /**
+   * MIME type of the generated candidate text. Supported MIME types are: text/plain: (default) Text output. application/json: JSON response in the response candidates. text/x.enum: ENUM as a string response in the response candidates.
+   */
+  responseMimeType?: string
+  /**
+   * Output schema of the generated candidate text. Schemas must be a subset of the OpenAPI schema and can be objects, primitives or arrays.
+
+If set, a compatible responseMimeType must also be set. Compatible MIME types: application/json: Schema for JSON response.
+   */
+  responseSchema?: Schema
+  /**
+   * Output schema of the generated response. This is an alternative to responseSchema that accepts JSON Schema.
+
+If set, responseSchema must be omitted, but responseMimeType is required.
+
+While the full JSON Schema may be sent, not all features are supported. Specifically, only the following properties are supported:
+
+$id
+$defs
+$ref
+$anchor
+type
+format
+title
+description
+enum (for strings and numbers)
+items
+prefixItems
+minItems
+maxItems
+minimum
+maximum
+anyOf
+oneOf (interpreted the same as anyOf)
+properties
+additionalProperties
+required
+The non-standard propertyOrdering property may also be set.
+
+Cyclic references are unrolled to a limited degree and, as such, may only be used within non-required properties. (Nullable properties are not sufficient.) If $ref is set on a sub-schema, no other properties, except for than those starting as a $, may be set.
+   */
+  responseJsonSchema?: Schema
+}
+
+export interface GeminiThinkingOptions {
+  /**
+   * Config for thinking features. An error will be returned if this field is set for models that don't support thinking.
+   */
+  thinkingConfig?: {
+    /**
+     * Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.
+     */
+    includeThoughts: boolean
+
+    /**
+     * The number of thoughts tokens that the model should generate.
+     */
+    thinkingBudget: number
+    /**
+     * The level of thoughts tokens that the model should generate.
+     */
+    thinkingLevel?: ThinkingLevel
+  }
+}
+
+export type ExternalTextProviderOptions = GeminiToolConfigOptions &
+  GeminiSafetyOptions &
+  GeminiGenerationConfigOptions &
+  GeminiCachedContentOptions

package/src/tools/code-execution-tool.ts

@@ -0,0 +1,17 @@
+import type { Tool } from '@tanstack/ai'
+
+export interface CodeExecutionTool {}
+
+export function convertCodeExecutionToolToAdapterFormat(_tool: Tool) {
+  return {
+    codeExecution: {},
+  }
+}
+
+export function codeExecutionTool(): Tool {
+  return {
+    name: 'code_execution',
+    description: '',
+    metadata: {},
+  }
+}

package/src/tools/computer-use-tool.ts

@@ -0,0 +1,25 @@
+import type { ComputerUse } from '@google/genai'
+import type { Tool } from '@tanstack/ai'
+
+export type ComputerUseTool = ComputerUse
+
+export function convertComputerUseToolToAdapterFormat(tool: Tool) {
+  const metadata = tool.metadata as ComputerUseTool
+  return {
+    computerUse: {
+      environment: metadata.environment,
+      excludedPredefinedFunctions: metadata.excludedPredefinedFunctions,
+    },
+  }
+}
+
+export function computerUseTool(config: ComputerUseTool): Tool {
+  return {
+    name: 'computer_use',
+    description: '',
+    metadata: {
+      environment: config.environment,
+      excludedPredefinedFunctions: config.excludedPredefinedFunctions,
+    },
+  }
+}

package/src/tools/file-search-tool.ts

@@ -0,0 +1,19 @@
+import type { Tool } from '@tanstack/ai'
+import type { FileSearch } from '@google/genai'
+
+export type FileSearchTool = FileSearch
+
+export function convertFileSearchToolToAdapterFormat(tool: Tool) {
+  const metadata = tool.metadata as FileSearchTool
+  return {
+    fileSearch: metadata,
+  }
+}
+
+export function fileSearchTool(config: FileSearchTool): Tool {
+  return {
+    name: 'file_search',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/function-declaration-tool.ts

@@ -0,0 +1,34 @@
+import type { FunctionDeclaration } from '@google/genai'
+
+export type FunctionDeclarationTool = FunctionDeclaration
+
+const validateFunctionDeclarationTool = (tool: FunctionDeclarationTool) => {
+  const nameRegex = /^[a-zA-Z0-9_:.-]{1,64}$/
+  const valid = nameRegex.test(tool.name!)
+  if (!valid) {
+    throw new Error(
+      `Invalid function name: ${tool.name}. Must be 1-64 characters long and contain only a-z, A-Z, 0-9, underscores, colons, dots, and dashes.`,
+    )
+  }
+
+  if (tool.parameters && tool.parametersJsonSchema) {
+    throw new Error(
+      `FunctionDeclarationTool cannot have both 'parameters' and 'parametersJsonSchema' defined. Please use only one.`,
+    )
+  }
+
+  if (tool.response && tool.responseJsonSchema) {
+    throw new Error(
+      `FunctionDeclarationTool cannot have both 'response' and 'responseJsonSchema' defined. Please use only one.`,
+    )
+  }
+}
+
+export function functionDeclarationTools(
+  tools: Array<FunctionDeclarationTool>,
+) {
+  tools.forEach(validateFunctionDeclarationTool)
+  return {
+    functionDeclarations: tools,
+  }
+}

package/src/tools/google-maps-tool.ts

@@ -0,0 +1,19 @@
+import type { GoogleMaps } from '@google/genai'
+import type { Tool } from '@tanstack/ai'
+
+export type GoogleMapsTool = GoogleMaps
+
+export function convertGoogleMapsToolToAdapterFormat(tool: Tool) {
+  const metadata = tool.metadata as GoogleMapsTool
+  return {
+    googleMaps: metadata,
+  }
+}
+
+export function googleMapsTool(config?: GoogleMapsTool): Tool {
+  return {
+    name: 'google_maps',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/google-search-retriveal-tool.ts

@@ -0,0 +1,21 @@
+import type { GoogleSearchRetrieval } from '@google/genai'
+import type { Tool } from '@tanstack/ai'
+
+export type GoogleSearchRetrievalTool = GoogleSearchRetrieval
+
+export function convertGoogleSearchRetrievalToolToAdapterFormat(tool: Tool) {
+  const metadata = tool.metadata as GoogleSearchRetrievalTool
+  return {
+    googleSearchRetrieval: metadata,
+  }
+}
+
+export function googleSearchRetrievalTool(
+  config?: GoogleSearchRetrievalTool,
+): Tool {
+  return {
+    name: 'google_search_retrieval',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/google-search-tool.ts

@@ -0,0 +1,19 @@
+import type { GoogleSearch } from '@google/genai'
+import type { Tool } from '@tanstack/ai'
+
+export type GoogleSearchTool = GoogleSearch
+
+export function convertGoogleSearchToolToAdapterFormat(tool: Tool) {
+  const metadata = tool.metadata as GoogleSearchTool
+  return {
+    googleSearch: metadata,
+  }
+}
+
+export function googleSearchTool(config?: GoogleSearchTool): Tool {
+  return {
+    name: 'google_search',
+    description: '',
+    metadata: config,
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,18 @@
+import type { CodeExecutionTool } from './code-execution-tool'
+import type { ComputerUseTool } from './computer-use-tool'
+import type { FileSearchTool } from './file-search-tool'
+import type { FunctionDeclarationTool } from './function-declaration-tool'
+import type { GoogleMapsTool } from './google-maps-tool'
+import type { GoogleSearchRetrievalTool } from './google-search-retriveal-tool'
+import type { GoogleSearchTool } from './google-search-tool'
+import type { UrlContextTool } from './url-context-tool'
+
+export type GoogleGeminiTool =
+  | CodeExecutionTool
+  | ComputerUseTool
+  | FileSearchTool
+  | FunctionDeclarationTool
+  | GoogleMapsTool
+  | GoogleSearchRetrievalTool
+  | GoogleSearchTool
+  | UrlContextTool

package/src/tools/tool-converter.ts

@@ -0,0 +1,99 @@
+import { convertZodToJsonSchema } from '@tanstack/ai'
+import { convertCodeExecutionToolToAdapterFormat } from './code-execution-tool'
+import { convertComputerUseToolToAdapterFormat } from './computer-use-tool'
+import { convertFileSearchToolToAdapterFormat } from './file-search-tool'
+import { convertGoogleMapsToolToAdapterFormat } from './google-maps-tool'
+import { convertGoogleSearchRetrievalToolToAdapterFormat } from './google-search-retriveal-tool'
+import { convertGoogleSearchToolToAdapterFormat } from './google-search-tool'
+import { convertUrlContextToolToAdapterFormat } from './url-context-tool'
+import type { Tool } from '@tanstack/ai'
+import type { ToolUnion } from '@google/genai'
+
+/**
+ * Converts standard Tool format to Gemini-specific tool format
+ *
+ * @param tools - Array of standard Tool objects
+ * @returns Array of Gemini-specific tool definitions
+ *
+ * @example
+ * ```typescript
+ * const tools: Tool[] = [{
+ *   name: "get_weather",
+ *   description: "Get weather for a location",
+ *   inputSchema: z.object({
+ *     location: z.string()
+ *   })
+ * }];
+ *
+ * const geminiTools = convertToolsToProviderFormat(tools);
+ * ```
+ */
+export function convertToolsToProviderFormat<TTool extends Tool>(
+  tools: Array<TTool> | undefined,
+): Array<ToolUnion> {
+  if (!tools || tools.length === 0) {
+    return []
+  }
+  const result: Array<ToolUnion> = []
+  const functionDeclarations: Array<{
+    name: string
+    description?: string
+    parameters?: any
+  }> = []
+
+  // Process each tool and group function declarations together
+  for (const tool of tools) {
+    const name = tool.name
+
+    switch (name) {
+      case 'code_execution':
+        result.push(convertCodeExecutionToolToAdapterFormat(tool))
+        break
+      case 'computer_use':
+        result.push(convertComputerUseToolToAdapterFormat(tool))
+        break
+      case 'file_search':
+        result.push(convertFileSearchToolToAdapterFormat(tool))
+        break
+      case 'google_maps':
+        result.push(convertGoogleMapsToolToAdapterFormat(tool))
+        break
+      case 'google_search_retrieval':
+        result.push(convertGoogleSearchRetrievalToolToAdapterFormat(tool))
+        break
+      case 'google_search':
+        result.push(convertGoogleSearchToolToAdapterFormat(tool))
+        break
+      case 'url_context':
+        result.push(convertUrlContextToolToAdapterFormat(tool))
+        break
+      default:
+        // Collect function declarations to group together
+        // Description is required for Gemini function declarations
+        if (!tool.description) {
+          throw new Error(
+            `Tool ${tool.name} requires a description for Gemini adapter`,
+          )
+        }
+
+        // Convert Zod schema to JSON Schema
+        const jsonSchema = convertZodToJsonSchema(tool.inputSchema)
+
+        functionDeclarations.push({
+          name: tool.name,
+          description: tool.description,
+          parameters: jsonSchema,
+        })
+        break
+    }
+  }
+
+  // If we have function declarations, add them as a single tool
+  if (functionDeclarations.length > 0) {
+    result.push({
+      functionDeclarations: functionDeclarations,
+    })
+  }
+
+  return result
+}

package/src/tools/url-context-tool.ts

@@ -0,0 +1,17 @@
+import type { Tool } from '@tanstack/ai'
+
+export interface UrlContextTool {}
+
+export function convertUrlContextToolToAdapterFormat(_tool: Tool) {
+  return {
+    urlContext: {},
+  }
+}
+
+export function urlContextTool(): Tool {
+  return {
+    name: 'url_context',
+    description: '',
+    metadata: {},
+  }
+}