@providerprotocol/ai 0.0.12 → 0.0.13

package/dist/google/index.d.ts

@@ -1,7 +1,29 @@
-import { b as Provider } from '../provider-CUJWjgNl.js';
+import { b as Provider } from '../provider-mKkz7Q9U.js';
 
 /**
- * Google Gemini-specific LLM parameters
+ * Provider-specific parameters for Google Gemini API requests.
+ *
+ * These parameters are passed through to the Google `generationConfig` field
+ * and control model behavior such as output length, randomness, and sampling
+ * strategies. All fields are optional and will use Google's defaults if omitted.
+ *
+ * @example
+ * ```typescript
+ * const params: GoogleLLMParams = {
+ *   maxOutputTokens: 2048,
+ *   temperature: 0.7,
+ *   topP: 0.9,
+ *   stopSequences: ['\n\n'],
+ * };
+ *
+ * const response = await model.complete({
+ *   messages: [...],
+ *   config: { apiKey: '...' },
+ *   params,
+ * });
+ * ```
+ *
+ * @see {@link https://ai.google.dev/api/rest/v1beta/GenerationConfig Google GenerationConfig docs}
  */
 interface GoogleLLMParams {
     /** Maximum number of tokens to generate */
@@ -51,19 +73,366 @@ interface GoogleLLMParams {
      * Thinking/reasoning configuration for Gemini 3+ models
      */
     thinkingConfig?: GoogleThinkingConfig;
+    /**
+     * Cached content name to use for this request.
+     * Format: "cachedContents/{id}" as returned from cache creation.
+     * When set, the cached content is prepended to the request.
+     */
+    cachedContent?: string;
 }
 /**
- * Thinking configuration for Gemini 3+ models
+ * Configuration for extended thinking/reasoning in Gemini 3+ models.
+ *
+ * Enables models to spend additional compute on reasoning before
+ * generating a response, improving quality for complex tasks.
  */
 interface GoogleThinkingConfig {
-    /** Whether thinking is enabled */
+    /** Token budget allocated for model thinking/reasoning before response generation. */
     thinkingBudget?: number;
 }
+/**
+ * A single content turn in the Google conversation format.
+ *
+ * Represents either a user message or model response, containing
+ * one or more parts that can be text, images, or function calls/responses.
+ */
+interface GoogleContent {
+    /** Role indicating message source: 'user' for user input, 'model' for assistant responses. */
+    role: 'user' | 'model';
+    /** Array of content parts within this message turn. */
+    parts: GooglePart[];
+}
+/**
+ * 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).
+ */
+type GooglePart = GoogleTextPart | GoogleImagePart | GoogleFunctionCallPart | GoogleFunctionResponsePart;
+/**
+ * Text content part.
+ */
+interface GoogleTextPart {
+    /** The text content. */
+    text: string;
+}
+/**
+ * Inline image content part with base64-encoded data.
+ */
+interface GoogleImagePart {
+    /** Inline image data container. */
+    inlineData: {
+        /** MIME type of the image (e.g., 'image/png', 'image/jpeg'). */
+        mimeType: string;
+        /** Base64-encoded image data. */
+        data: string;
+    };
+}
+/**
+ * Function call part generated by the model.
+ *
+ * Represents the model's request to invoke a declared function with
+ * specific arguments.
+ */
+interface GoogleFunctionCallPart {
+    /** Function call details. */
+    functionCall: {
+        /** Name of the function to call. */
+        name: string;
+        /** Arguments to pass to the function. */
+        args: Record<string, unknown>;
+    };
+    /** Thought signature for Gemini 3+ models to maintain context across multi-turn tool calls. */
+    thoughtSignature?: string;
+}
+/**
+ * Function response part provided by the user.
+ *
+ * Contains the result of executing a function call, sent back to
+ * the model to continue the conversation.
+ */
+interface GoogleFunctionResponsePart {
+    /** Function response details. */
+    functionResponse: {
+        /** Name of the function that was called. */
+        name: string;
+        /** Response data from the function execution. */
+        response: Record<string, unknown>;
+    };
+}
+/**
+ * Tool definition containing function declarations.
+ *
+ * Google groups function declarations within a tools array, where each
+ * tool object contains an array of function declarations.
+ */
+interface GoogleTool {
+    /** Array of function declarations available for the model to call. */
+    functionDeclarations: GoogleFunctionDeclaration[];
+}
+/**
+ * Declaration of a callable function/tool for the model.
+ *
+ * Describes the function signature including its name, purpose,
+ * and expected parameters in JSON Schema format.
+ */
+interface GoogleFunctionDeclaration {
+    /** Unique name of the function. */
+    name: string;
+    /** Human-readable description of what the function does. */
+    description: string;
+    /** JSON Schema describing the function parameters. */
+    parameters: {
+        /** Schema type, always 'object' for function parameters. */
+        type: 'object';
+        /** Map of parameter names to their JSON Schema definitions. */
+        properties: Record<string, unknown>;
+        /** Array of required parameter names. */
+        required?: string[];
+    };
+}
+/**
+ * Response from creating or retrieving a cached content entry.
+ */
+interface GoogleCacheResponse {
+    /** Cache identifier in format "cachedContents/{id}" - use this in requests */
+    name: string;
+    /** Model this cache is associated with */
+    model: string;
+    /** Display name for the cache */
+    displayName?: string;
+    /** When the cache was created (RFC 3339 format) */
+    createTime: string;
+    /** When the cache was last updated (RFC 3339 format) */
+    updateTime: string;
+    /** When the cache expires (RFC 3339 format) */
+    expireTime: string;
+    /** Token usage metadata */
+    usageMetadata?: {
+        /** Total tokens in the cached content */
+        totalTokenCount: number;
+    };
+}
+/**
+ * Request body for updating a cached content entry.
+ * Only expiration can be updated; all other fields are immutable.
+ */
+interface GoogleCacheUpdateRequest {
+    /** New absolute expiration time (RFC 3339 format, mutually exclusive with ttl) */
+    expireTime?: string;
+    /** New time-to-live duration (e.g., "3600s", mutually exclusive with expireTime) */
+    ttl?: string;
+}
+/**
+ * Response from listing cached content entries.
+ */
+interface GoogleCacheListResponse {
+    /** Array of cached content entries */
+    cachedContents?: GoogleCacheResponse[];
+    /** Token for fetching the next page of results */
+    nextPageToken?: string;
+}
+
+/**
+ * @fileoverview Google Gemini caching utilities.
+ *
+ * Provides functions for creating and managing cached content entries
+ * that can be reused across multiple Gemini API requests to reduce
+ * costs and latency for repeated context.
+ *
+ * @see {@link https://ai.google.dev/api/caching Google Caching API docs}
+ * @module providers/google/cache
+ */
+
+/**
+ * Options for creating a cached content entry.
+ */
+interface CacheCreateOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Model to associate with this cache (e.g., "gemini-1.5-flash-001") */
+    model: string;
+    /** Optional display name for the cache (max 128 chars) */
+    displayName?: string;
+    /** Content messages to cache */
+    contents?: GoogleContent[];
+    /** System instruction text to cache */
+    systemInstruction?: string;
+    /** Tool declarations to cache */
+    tools?: GoogleTool[];
+    /** Time-to-live duration (e.g., "3600s" for 1 hour) */
+    ttl?: string;
+    /** Absolute expiration time (RFC 3339 format, alternative to ttl) */
+    expireTime?: string;
+}
+/**
+ * Options for listing cached content entries.
+ */
+interface CacheListOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Maximum number of caches to return per page */
+    pageSize?: number;
+    /** Token for fetching the next page of results */
+    pageToken?: string;
+}
+/**
+ * Creates a new cached content entry.
+ *
+ * Caches can contain system instructions, conversation content, and tool
+ * declarations that are reused across multiple requests. This reduces
+ * token costs and processing time for repeated context.
+ *
+ * @param options - Cache creation options
+ * @returns The created cache entry with its name/ID for use in requests
+ *
+ * @example
+ * ```typescript
+ * import { google } from '@anthropic/provider-protocol';
+ *
+ * // 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',
+ *   displayName: 'Code Review Context',
+ *   systemInstruction: 'You are an expert code reviewer...',
+ *   contents: [
+ *     { role: 'user', parts: [{ text: largeCodebaseContent }] }
+ *   ],
+ *   ttl: '3600s', // 1 hour
+ * });
+ *
+ * // Use the cache in subsequent requests
+ * const response = await model.complete({
+ *   messages: [userMessage('Review this function')],
+ *   params: { cachedContent: cache.name },
+ * });
+ * ```
+ */
+declare function create(options: CacheCreateOptions): Promise<GoogleCacheResponse>;
+/**
+ * Retrieves a cached content entry by name.
+ *
+ * @param name - The cache name (format: "cachedContents/{id}")
+ * @param apiKey - API key for authentication
+ * @returns The cache entry details
+ *
+ * @example
+ * ```typescript
+ * const cache = await google.cache.get('cachedContents/abc123', apiKey);
+ * console.log(`Cache expires at: ${cache.expireTime}`);
+ * ```
+ */
+declare function get(name: string, apiKey: string): Promise<GoogleCacheResponse>;
+/**
+ * Lists all cached content entries.
+ *
+ * @param options - List options including API key and pagination
+ * @returns Array of cache entries and optional next page token
+ *
+ * @example
+ * ```typescript
+ * const { cachedContents, nextPageToken } = await google.cache.list({
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   pageSize: 10,
+ * });
+ *
+ * for (const cache of cachedContents ?? []) {
+ *   console.log(`${cache.displayName}: ${cache.name}`);
+ * }
+ * ```
+ */
+declare function list(options: CacheListOptions): Promise<GoogleCacheListResponse>;
+/**
+ * Updates a cached content entry's expiration time.
+ *
+ * Only the expiration time can be updated; all other fields
+ * (contents, systemInstruction, tools) are immutable after creation.
+ *
+ * @param name - The cache name (format: "cachedContents/{id}")
+ * @param update - The update to apply (ttl or expireTime)
+ * @param apiKey - API key for authentication
+ * @returns The updated cache entry
+ *
+ * @example
+ * ```typescript
+ * // Extend cache expiration by 2 hours
+ * const updated = await google.cache.update(
+ *   'cachedContents/abc123',
+ *   { ttl: '7200s' },
+ *   apiKey
+ * );
+ * ```
+ */
+declare function update(name: string, updateRequest: GoogleCacheUpdateRequest, apiKey: string): Promise<GoogleCacheResponse>;
 
 /**
- * Google Gemini provider
- * Supports LLM modality with Gemini models
+ * Google Gemini provider for the Unified Provider Protocol (UPP).
+ *
+ * Provides access to Google's Gemini family of large language models through
+ * a standardized interface. Supports text generation, multimodal inputs
+ * (images, video, audio), tool/function calling, and structured output.
+ *
+ * @example
+ * ```typescript
+ * import { google } from './providers/google';
+ *
+ * // Create a model instance
+ * const gemini = google.llm.bind('gemini-1.5-pro');
+ *
+ * // Simple completion
+ * const response = await gemini.complete({
+ *   messages: [{ role: 'user', content: [{ type: 'text', text: 'Hello!' }] }],
+ *   config: { apiKey: process.env.GOOGLE_API_KEY },
+ * });
+ *
+ * // Streaming completion
+ * const stream = gemini.stream({
+ *   messages: [{ role: 'user', content: [{ type: 'text', text: 'Tell me a story' }] }],
+ *   config: { apiKey: process.env.GOOGLE_API_KEY },
+ * });
+ *
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta.text);
+ *   }
+ * }
+ * ```
+ *
+ * @example Caching
+ * ```typescript
+ * // Create a cache for repeated context
+ * const cacheEntry = await google.cache.create({
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   model: 'gemini-1.5-flash-001',
+ *   systemInstruction: 'You are an expert code reviewer...',
+ *   contents: [{ role: 'user', parts: [{ text: largeCodebase }] }],
+ *   ttl: '3600s',
+ * });
+ *
+ * // Use cache in requests
+ * const response = await gemini.complete({
+ *   messages: [userMessage('Review this function')],
+ *   config: { apiKey: process.env.GOOGLE_API_KEY },
+ *   params: { cachedContent: cacheEntry.name },
+ * });
+ *
+ * // Manage caches
+ * await google.cache.update(cacheEntry.name, { ttl: '7200s' }, apiKey);
+ * await google.cache.delete(cacheEntry.name, apiKey);
+ * ```
+ *
+ * @see {@link GoogleLLMParams} for provider-specific configuration options
+ * @see {@link cache} for caching utilities
  */
-declare const google: Provider<unknown>;
+declare const google: Provider<unknown> & {
+    cache: {
+        create: typeof create;
+        get: typeof get;
+        list: typeof list;
+        update: typeof update;
+        delete: (name: string, apiKey: string) => Promise<void>;
+    };
+};
 
 export { type GoogleLLMParams, google };

package/dist/google/index.js

@@ -1,36 +1,43 @@
 import {
   createProvider
-} from "../chunk-Y6Q7JCNP.js";
+} from "../chunk-MSR5P65T.js";
 import {
   AssistantMessage,
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-W4BB4BG2.js";
+} from "../chunk-SVYROCLD.js";
 import {
   parseSSEStream
-} from "../chunk-X5G4EHL7.js";
+} from "../chunk-Z7RBRCRN.js";
 import {
   UPPError,
   doFetch,
   doStreamFetch,
   normalizeHttpError,
   resolveApiKey
-} from "../chunk-SUNYWHTH.js";
+} from "../chunk-MOU4U3PO.js";
 
 // src/providers/google/transform.ts
 function transformRequest(request, modelId) {
   const params = request.params ?? {};
+  const { cachedContent, ...generationParams } = params;
   const googleRequest = {
     contents: transformMessages(request.messages)
   };
   if (request.system) {
-    googleRequest.systemInstruction = {
-      parts: [{ text: request.system }]
-    };
+    if (typeof request.system === "string") {
+      googleRequest.systemInstruction = {
+        parts: [{ text: request.system }]
+      };
+    } else {
+      googleRequest.systemInstruction = {
+        parts: request.system
+      };
+    }
   }
   const generationConfig = {
-    ...params
+    ...generationParams
   };
   if (request.structure) {
     generationConfig.responseMimeType = "application/json";
@@ -46,6 +53,9 @@ function transformRequest(request, modelId) {
       }
     ];
   }
+  if (cachedContent) {
+    googleRequest.cachedContent = cachedContent;
+  }
   return googleRequest;
 }
 function filterValidContent(content) {
@@ -104,7 +114,6 @@ function transformMessages(messages) {
         parts: msg.results.map((result) => ({
           functionResponse: {
             name: result.toolCallId,
-            // Google uses the function name, but we store it in toolCallId
             response: typeof result.result === "object" ? result.result : { result: result.result }
           }
         }))
@@ -173,7 +182,6 @@ function transformResponse(data) {
       const fc = part;
       toolCalls.push({
         toolCallId: fc.functionCall.name,
-        // Google doesn't have call IDs, use name
         toolName: fc.functionCall.name,
         arguments: fc.functionCall.args
       });
@@ -192,7 +200,6 @@ function transformResponse(data) {
         google: {
           finishReason: candidate.finishReason,
           safetyRatings: candidate.safetyRatings,
-          // Store function call parts with thought signatures for multi-turn
           functionCallParts: functionCallParts.length > 0 ? functionCallParts : void 0
         }
       }
@@ -201,7 +208,9 @@ function transformResponse(data) {
   const usage = {
     inputTokens: data.usageMetadata?.promptTokenCount ?? 0,
     outputTokens: data.usageMetadata?.candidatesTokenCount ?? 0,
-    totalTokens: data.usageMetadata?.totalTokenCount ?? 0
+    totalTokens: data.usageMetadata?.totalTokenCount ?? 0,
+    cacheReadTokens: data.usageMetadata?.cachedContentTokenCount ?? 0,
+    cacheWriteTokens: 0
   };
   return {
     message,
@@ -217,6 +226,7 @@ function createStreamState() {
     finishReason: null,
     inputTokens: 0,
     outputTokens: 0,
+    cacheReadTokens: 0,
     isFirstChunk: true
   };
 }
@@ -229,6 +239,7 @@ function transformStreamChunk(chunk, state) {
   if (chunk.usageMetadata) {
     state.inputTokens = chunk.usageMetadata.promptTokenCount;
     state.outputTokens = chunk.usageMetadata.candidatesTokenCount;
+    state.cacheReadTokens = chunk.usageMetadata.cachedContentTokenCount ?? 0;
   }
   const candidate = chunk.candidates?.[0];
   if (!candidate) {
@@ -297,7 +308,6 @@ function buildResponseFromState(state) {
       metadata: {
         google: {
           finishReason: state.finishReason,
-          // Store function call parts with thought signatures for multi-turn
           functionCallParts: functionCallParts.length > 0 ? functionCallParts : void 0
         }
       }
@@ -306,7 +316,9 @@ function buildResponseFromState(state) {
   const usage = {
     inputTokens: state.inputTokens,
     outputTokens: state.outputTokens,
-    totalTokens: state.inputTokens + state.outputTokens
+    totalTokens: state.inputTokens + state.outputTokens,
+    cacheReadTokens: state.cacheReadTokens,
+    cacheWriteTokens: 0
   };
   return {
     message,
@@ -462,14 +474,114 @@ function createLLMHandler() {
   };
 }
 
+// src/providers/google/cache.ts
+var CACHE_API_BASE = "https://generativelanguage.googleapis.com/v1beta/cachedContents";
+async function create(options) {
+  const {
+    apiKey,
+    model,
+    displayName,
+    contents,
+    systemInstruction,
+    tools,
+    ttl,
+    expireTime
+  } = options;
+  const requestBody = {
+    model: model.startsWith("models/") ? model : `models/${model}`
+  };
+  if (displayName) {
+    requestBody.displayName = displayName;
+  }
+  if (contents && contents.length > 0) {
+    requestBody.contents = contents;
+  }
+  if (systemInstruction) {
+    requestBody.systemInstruction = {
+      parts: [{ text: systemInstruction }]
+    };
+  }
+  if (tools && tools.length > 0) {
+    requestBody.tools = tools;
+  }
+  if (ttl) {
+    requestBody.ttl = ttl;
+  } else if (expireTime) {
+    requestBody.expireTime = expireTime;
+  }
+  const response = await fetch(`${CACHE_API_BASE}?key=${apiKey}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(requestBody)
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create cache: ${response.status} ${error}`);
+  }
+  return response.json();
+}
+async function get(name, apiKey) {
+  const cacheName = name.startsWith("cachedContents/") ? name : `cachedContents/${name}`;
+  const url = `https://generativelanguage.googleapis.com/v1beta/${cacheName}?key=${apiKey}`;
+  const response = await fetch(url, { method: "GET" });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get cache: ${response.status} ${error}`);
+  }
+  return response.json();
+}
+async function list(options) {
+  const { apiKey, pageSize, pageToken } = options;
+  const params = new URLSearchParams({ key: apiKey });
+  if (pageSize) params.set("pageSize", String(pageSize));
+  if (pageToken) params.set("pageToken", pageToken);
+  const response = await fetch(`${CACHE_API_BASE}?${params}`, { method: "GET" });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to list caches: ${response.status} ${error}`);
+  }
+  return response.json();
+}
+async function update(name, updateRequest, apiKey) {
+  const cacheName = name.startsWith("cachedContents/") ? name : `cachedContents/${name}`;
+  const url = `https://generativelanguage.googleapis.com/v1beta/${cacheName}?key=${apiKey}`;
+  const response = await fetch(url, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(updateRequest)
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to update cache: ${response.status} ${error}`);
+  }
+  return response.json();
+}
+async function deleteCache(name, apiKey) {
+  const cacheName = name.startsWith("cachedContents/") ? name : `cachedContents/${name}`;
+  const url = `https://generativelanguage.googleapis.com/v1beta/${cacheName}?key=${apiKey}`;
+  const response = await fetch(url, { method: "DELETE" });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to delete cache: ${response.status} ${error}`);
+  }
+}
+var cache = {
+  create,
+  get,
+  list,
+  update,
+  delete: deleteCache
+};
+
 // src/providers/google/index.ts
-var google = createProvider({
+var baseProvider = createProvider({
   name: "google",
   version: "1.0.0",
   modalities: {
     llm: createLLMHandler()
   }
 });
+var google = Object.assign(baseProvider, { cache });
 export {
   google
 };