@providerprotocol/ai 0.0.13 → 0.0.15

package/dist/google/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Provider } from '../provider-mKkz7Q9U.js';
+import { b as Provider } from '../provider-Bi0nyNhA.js';
 
 /**
  * Provider-specific parameters for Google Gemini API requests.
@@ -79,6 +79,50 @@ interface GoogleLLMParams {
      * When set, the cached content is prepended to the request.
      */
     cachedContent?: string;
+    /**
+     * Built-in tools for server-side execution.
+     *
+     * Use the tool helper constructors from the `tools` namespace:
+     * - `tools.googleSearch()` - Google Search grounding
+     * - `tools.codeExecution()` - Python code execution
+     * - `tools.urlContext()` - URL fetching and analysis
+     * - `tools.googleMaps()` - Google Maps grounding
+     * - `tools.fileSearch()` - Document RAG search
+     *
+     * Note: File Search cannot be combined with other built-in tools.
+     *
+     * @example
+     * ```typescript
+     * import { google, tools } from 'provider-protocol/google';
+     *
+     * const model = llm({
+     *   model: google('gemini-2.5-flash'),
+     *   params: {
+     *     builtInTools: [
+     *       tools.googleSearch(),
+     *       tools.codeExecution(),
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    builtInTools?: GoogleBuiltInTool[];
+    /**
+     * Tool configuration for retrieval (e.g., user location for Maps).
+     *
+     * @example
+     * ```typescript
+     * const params: GoogleLLMParams = {
+     *   builtInTools: [tools.googleMaps()],
+     *   toolConfig: {
+     *     retrievalConfig: {
+     *       latLng: { latitude: 40.758896, longitude: -73.985130 },
+     *     },
+     *   },
+     * };
+     * ```
+     */
+    toolConfig?: GoogleToolConfig;
 }
 /**
  * Configuration for extended thinking/reasoning in Gemini 3+ models.
@@ -106,9 +150,10 @@ interface GoogleContent {
  * Union type for all possible content part types in Google messages.
  *
  * Parts can contain text, inline images, function calls (from model),
- * or function responses (from user providing tool results).
+ * function responses (from user providing tool results), or code execution
+ * results (from built-in code execution tool).
  */
-type GooglePart = GoogleTextPart | GoogleImagePart | GoogleFunctionCallPart | GoogleFunctionResponsePart;
+type GooglePart = GoogleTextPart | GoogleImagePart | GoogleFunctionCallPart | GoogleFunctionResponsePart | GoogleExecutableCodePart | GoogleCodeExecutionResultPart;
 /**
  * Text content part.
  */
@@ -160,6 +205,36 @@ interface GoogleFunctionResponsePart {
         response: Record<string, unknown>;
     };
 }
+/**
+ * Executable code part generated by the model.
+ *
+ * Contains code that was written by the model for execution
+ * via the built-in code execution tool.
+ */
+interface GoogleExecutableCodePart {
+    /** Executable code details. */
+    executableCode: {
+        /** Programming language of the code. */
+        language: 'PYTHON' | 'LANGUAGE_UNSPECIFIED';
+        /** The code to execute. */
+        code: string;
+    };
+}
+/**
+ * Code execution result part from built-in code execution.
+ *
+ * Contains the output from executing code via the code execution tool.
+ * Always follows an ExecutableCode part.
+ */
+interface GoogleCodeExecutionResultPart {
+    /** Code execution result details. */
+    codeExecutionResult: {
+        /** Execution outcome. */
+        outcome: 'OUTCOME_UNSPECIFIED' | 'OUTCOME_OK' | 'OUTCOME_FAILED' | 'OUTCOME_DEADLINE_EXCEEDED';
+        /** Execution output (stdout on success, stderr on failure). */
+        output: string;
+    };
+}
 /**
  * Tool definition containing function declarations.
  *
@@ -191,6 +266,39 @@ interface GoogleFunctionDeclaration {
         required?: string[];
     };
 }
+/**
+ * Request body for creating a cached content entry.
+ *
+ * @see {@link https://ai.google.dev/api/caching Google Caching API docs}
+ */
+interface GoogleCacheCreateRequest {
+    /** Model to use with this cache (format: models/{model}) */
+    model: string;
+    /** Optional display name for the cache (max 128 chars) */
+    displayName?: string;
+    /** Content to cache (immutable after creation) */
+    contents?: GoogleContent[];
+    /** System instruction to cache (text-only, immutable after creation) */
+    systemInstruction?: {
+        role?: 'user';
+        parts: Array<{
+            text: string;
+        }>;
+    };
+    /** Tool declarations to cache (immutable after creation) */
+    tools?: GoogleTool[];
+    /** Tool configuration to cache (immutable after creation) */
+    toolConfig?: {
+        functionCallingConfig?: {
+            mode?: 'AUTO' | 'ANY' | 'NONE' | 'VALIDATED';
+            allowedFunctionNames?: string[];
+        };
+    };
+    /** Absolute expiration time (RFC 3339 format, mutually exclusive with ttl) */
+    expireTime?: string;
+    /** Time-to-live duration (e.g., "300s", "3600s", mutually exclusive with expireTime) */
+    ttl?: string;
+}
 /**
  * Response from creating or retrieving a cached content entry.
  */
@@ -232,6 +340,319 @@ interface GoogleCacheListResponse {
     /** Token for fetching the next page of results */
     nextPageToken?: string;
 }
+/**
+ * Google Gemini-specific HTTP headers for API requests.
+ *
+ * @example
+ * ```typescript
+ * const headers: GoogleHeaders = {
+ *   'x-goog-api-client': 'myapp/1.0.0',
+ * };
+ * ```
+ */
+interface GoogleHeaders {
+    /** Client identification header for partners and libraries. */
+    'x-goog-api-client'?: string;
+    /** Quota project ID for Vertex AI billing. */
+    'x-goog-user-project'?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Google Search grounding tool for real-time web information.
+ *
+ * Enables Gemini to search the web using Google Search for up-to-date information.
+ * Results are returned with grounding metadata including sources and citations.
+ *
+ * Pricing:
+ * - Gemini 2.x and earlier: $35 per 1,000 grounded prompts
+ * - Gemini 3.x: $14 per 1,000 search queries
+ *
+ * @example
+ * ```typescript
+ * const tool: GoogleSearchTool = {
+ *   googleSearch: {},
+ * };
+ * ```
+ */
+interface GoogleSearchTool {
+    /** Empty object to enable Google Search grounding */
+    googleSearch: Record<string, never>;
+}
+/**
+ * Code execution tool for running Python in a sandbox.
+ *
+ * Enables Gemini to write and execute Python code in a secure environment.
+ * Supports data analysis, calculations, and visualization.
+ *
+ * No additional cost - standard token pricing applies.
+ *
+ * @example
+ * ```typescript
+ * const tool: GoogleCodeExecutionTool = {
+ *   codeExecution: {},
+ * };
+ * ```
+ */
+interface GoogleCodeExecutionTool {
+    /** Empty object to enable code execution */
+    codeExecution: Record<string, never>;
+}
+/**
+ * URL context tool for fetching and processing URLs.
+ *
+ * Enables Gemini to fetch and analyze content from URLs.
+ * Supports text, images, and PDF documents.
+ *
+ * Limits:
+ * - Maximum 20 URLs per request
+ * - Maximum 34MB content per URL
+ *
+ * @example
+ * ```typescript
+ * const tool: GoogleUrlContextTool = {
+ *   urlContext: {},
+ * };
+ * ```
+ */
+interface GoogleUrlContextTool {
+    /** Empty object to enable URL context */
+    urlContext: Record<string, never>;
+}
+/**
+ * Google Maps grounding tool for location-based queries.
+ *
+ * Enables Gemini to search for places, businesses, and locations
+ * using Google Maps data.
+ *
+ * Pricing: $25 per 1,000 grounded prompts.
+ *
+ * Note: Not supported in Gemini 3 models.
+ *
+ * @example
+ * ```typescript
+ * const tool: GoogleMapsTool = {
+ *   googleMaps: {
+ *     enableWidget: true,
+ *   },
+ * };
+ * ```
+ */
+interface GoogleMapsTool {
+    /** Google Maps configuration */
+    googleMaps: {
+        /** Return widget context token for Places widget */
+        enableWidget?: boolean;
+    };
+}
+/**
+ * File search (RAG) tool for document retrieval.
+ *
+ * Enables Gemini to search through uploaded documents
+ * using semantic search on FileSearchStore.
+ *
+ * Pricing:
+ * - Embeddings at indexing: $0.15 per 1M tokens
+ * - Storage and query embeddings: Free
+ *
+ * Note: Cannot be combined with other built-in tools.
+ *
+ * @example
+ * ```typescript
+ * const tool: GoogleFileSearchTool = {
+ *   fileSearch: {
+ *     fileSearchStoreNames: ['fileSearchStores/abc123'],
+ *   },
+ * };
+ * ```
+ */
+interface GoogleFileSearchTool {
+    /** File search configuration */
+    fileSearch: {
+        /** FileSearchStore names to query */
+        fileSearchStoreNames: string[];
+        /** AIP-160 filter syntax for metadata filtering */
+        metadataFilter?: string;
+    };
+}
+/**
+ * Union type for all Google built-in tools.
+ *
+ * Note: Google's built-in tools use a different structure than function tools.
+ * They are passed directly in the tools array alongside functionDeclarations.
+ */
+type GoogleBuiltInTool = GoogleSearchTool | GoogleCodeExecutionTool | GoogleUrlContextTool | GoogleMapsTool | GoogleFileSearchTool;
+/**
+ * Tool configuration for retrieval (e.g., user location for Maps).
+ */
+interface GoogleToolConfig {
+    /** Retrieval configuration */
+    retrievalConfig?: {
+        /** User location for "near me" queries */
+        latLng?: {
+            /** User latitude */
+            latitude: number;
+            /** User longitude */
+            longitude: number;
+        };
+    };
+}
+/**
+ * Grounding metadata returned with search/maps results.
+ */
+interface GoogleGroundingMetadata {
+    /** Web search queries executed */
+    webSearchQueries?: string[];
+    /** Search entry point with rendered HTML */
+    searchEntryPoint?: {
+        renderedContent: string;
+    };
+    /** Grounding chunks (sources) */
+    groundingChunks?: Array<{
+        web?: {
+            uri: string;
+            title: string;
+        };
+        maps?: {
+            uri: string;
+            placeId: string;
+            title: string;
+        };
+    }>;
+    /** Grounding supports (citations) */
+    groundingSupports?: Array<{
+        segment: {
+            startIndex: number;
+            endIndex: number;
+            text: string;
+        };
+        groundingChunkIndices: number[];
+        confidenceScores: number[];
+    }>;
+    /** Google Maps widget context token */
+    googleMapsWidgetContextToken?: string;
+}
+/**
+ * Code execution result in response.
+ */
+interface GoogleCodeExecutionResult {
+    /** Execution outcome */
+    outcome: 'OUTCOME_OK' | 'OUTCOME_FAILED' | 'OUTCOME_DEADLINE_EXCEEDED';
+    /** Execution output (stdout) */
+    output: string;
+}
+/**
+ * Creates a Google Search grounding tool configuration.
+ *
+ * Enables Gemini to search the web using Google Search for up-to-date information.
+ *
+ * @returns A Google Search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const search = googleSearchTool();
+ * ```
+ */
+declare function googleSearchTool(): GoogleSearchTool;
+/**
+ * Creates a code execution tool configuration.
+ *
+ * Enables Gemini to write and execute Python code in a sandbox.
+ *
+ * @returns A code execution tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const codeExec = codeExecutionTool();
+ * ```
+ */
+declare function codeExecutionTool(): GoogleCodeExecutionTool;
+/**
+ * Creates a URL context tool configuration.
+ *
+ * Enables Gemini to fetch and analyze content from URLs.
+ *
+ * @returns A URL context tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const urlCtx = urlContextTool();
+ * ```
+ */
+declare function urlContextTool(): GoogleUrlContextTool;
+/**
+ * Creates a Google Maps grounding tool configuration.
+ *
+ * Enables Gemini to search for places using Google Maps data.
+ *
+ * Note: Not supported in Gemini 3 models.
+ *
+ * @param options - Optional configuration
+ * @returns A Google Maps tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const maps = googleMapsTool();
+ *
+ * // With widget enabled
+ * const mapsWithWidget = googleMapsTool({ enableWidget: true });
+ * ```
+ */
+declare function googleMapsTool(options?: {
+    enableWidget?: boolean;
+}): GoogleMapsTool;
+/**
+ * Creates a file search (RAG) tool configuration.
+ *
+ * Enables Gemini to search through uploaded documents.
+ *
+ * Note: Cannot be combined with other built-in tools.
+ *
+ * @param options - File search configuration
+ * @returns A file search tool configuration object
+ *
+ * @example
+ * ```typescript
+ * const fileSearch = fileSearchTool({
+ *   fileSearchStoreNames: ['fileSearchStores/abc123'],
+ * });
+ * ```
+ */
+declare function fileSearchTool(options: {
+    fileSearchStoreNames: string[];
+    metadataFilter?: string;
+}): GoogleFileSearchTool;
+/**
+ * Namespace object containing all Google tool helper constructors.
+ *
+ * Provides a convenient way to create built-in tool configurations.
+ *
+ * @example
+ * ```typescript
+ * import { google, tools } from 'provider-protocol/google';
+ *
+ * const model = llm({
+ *   model: google('gemini-2.5-flash'),
+ *   params: {
+ *     builtInTools: [
+ *       tools.googleSearch(),
+ *       tools.codeExecution(),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+declare const tools: {
+    /** Creates a Google Search grounding tool configuration */
+    googleSearch: typeof googleSearchTool;
+    /** Creates a code execution tool configuration */
+    codeExecution: typeof codeExecutionTool;
+    /** Creates a URL context tool configuration */
+    urlContext: typeof urlContextTool;
+    /** Creates a Google Maps grounding tool configuration */
+    googleMaps: typeof googleMapsTool;
+    /** Creates a file search (RAG) tool configuration */
+    fileSearch: typeof fileSearchTool;
+};
 
 /**
  * @fileoverview Google Gemini caching utilities.
@@ -250,7 +671,7 @@ interface GoogleCacheListResponse {
 interface CacheCreateOptions {
     /** API key for authentication */
     apiKey: string;
-    /** Model to associate with this cache (e.g., "gemini-1.5-flash-001") */
+    /** Model to associate with this cache (e.g., "gemini-3-flash-preview") */
     model: string;
     /** Optional display name for the cache (max 128 chars) */
     displayName?: string;
@@ -293,7 +714,7 @@ interface CacheListOptions {
  * // Create a cache with system instruction and large context
  * const cache = await google.cache.create({
  *   apiKey: process.env.GOOGLE_API_KEY,
- *   model: 'gemini-1.5-flash-001',
+ *   model: 'gemini-3-flash-preview',
  *   displayName: 'Code Review Context',
  *   systemInstruction: 'You are an expert code reviewer...',
  *   contents: [
@@ -365,6 +786,58 @@ declare function list(options: CacheListOptions): Promise<GoogleCacheListRespons
  * ```
  */
 declare function update(name: string, updateRequest: GoogleCacheUpdateRequest, apiKey: string): Promise<GoogleCacheResponse>;
+/**
+ * Deletes a cached content entry.
+ *
+ * @param name - The cache name (format: "cachedContents/{id}")
+ * @param apiKey - API key for authentication
+ *
+ * @example
+ * ```typescript
+ * await google.cache.delete('cachedContents/abc123', apiKey);
+ * ```
+ */
+declare function deleteCache(name: string, apiKey: string): Promise<void>;
+/**
+ * Cache utilities namespace.
+ *
+ * Provides functions for creating and managing Google Gemini cached content
+ * entries. Use cached content to reduce costs and latency when repeatedly
+ * sending the same context (system instructions, large documents, etc.)
+ * across multiple requests.
+ *
+ * @example
+ * ```typescript
+ * import { google } from '@anthropic/provider-protocol';
+ *
+ * // Create a cache
+ * const cache = await google.cache.create({
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   model: 'gemini-3-flash-preview',
+ *   systemInstruction: 'You are an expert assistant...',
+ *   contents: [{ role: 'user', parts: [{ text: largeDocument }] }],
+ *   ttl: '3600s',
+ * });
+ *
+ * // Use cache.name in requests via params.cachedContent
+ * const response = await model.complete({
+ *   messages: [userMessage('Summarize the document')],
+ *   params: { cachedContent: cache.name },
+ * });
+ *
+ * // Manage caches
+ * const caches = await google.cache.list({ apiKey });
+ * await google.cache.update(cache.name, { ttl: '7200s' }, apiKey);
+ * await google.cache.delete(cache.name, apiKey);
+ * ```
+ */
+declare const cache: {
+    create: typeof create;
+    get: typeof get;
+    list: typeof list;
+    update: typeof update;
+    delete: typeof deleteCache;
+};
 
 /**
  * Google Gemini provider for the Unified Provider Protocol (UPP).
@@ -404,7 +877,7 @@ declare function update(name: string, updateRequest: GoogleCacheUpdateRequest, a
  * // Create a cache for repeated context
  * const cacheEntry = await google.cache.create({
  *   apiKey: process.env.GOOGLE_API_KEY,
- *   model: 'gemini-1.5-flash-001',
+ *   model: 'gemini-3-flash-preview',
  *   systemInstruction: 'You are an expert code reviewer...',
  *   contents: [{ role: 'user', parts: [{ text: largeCodebase }] }],
  *   ttl: '3600s',
@@ -435,4 +908,4 @@ declare const google: Provider<unknown> & {
     };
 };
 
-export { type GoogleLLMParams, google };
+export { type CacheCreateOptions, type CacheListOptions, type GoogleBuiltInTool, type GoogleCacheCreateRequest, type GoogleCacheListResponse, type GoogleCacheResponse, type GoogleCacheUpdateRequest, type GoogleCodeExecutionResult, type GoogleCodeExecutionTool, type GoogleFileSearchTool, type GoogleGroundingMetadata, type GoogleHeaders, type GoogleLLMParams, type GoogleMapsTool, type GoogleSearchTool, type GoogleToolConfig, type GoogleUrlContextTool, cache, google, tools };