@truefoundry/ai-gateway-sdk 0.0.0-stage → 0.0.2

package/dist/providers/google-vertex-ai/utils.d.ts

@@ -0,0 +1,654 @@
+import { BatchEndpoints } from '../../globals.js';
+import type { SessionContext } from '../../types/contracts.js';
+import { ContentType, JsonSchema, Tool } from '../../types/requestBody.js';
+import type { GoogleMessagePart } from '../google/chatComplete.js';
+import { ErrorResponse, FinetuneRequest, Logprobs } from '../types.js';
+import { GoogleBatchRecord, GoogleErrorResponse, GoogleFinetuneRecord, GoogleResponseCandidate, GoogleSearchRetrievalTool } from './types.js';
+/**
+ NOTE: Some JWT relatedutil functions have been moved src/utils/jwtUtils.ts instead
+ */
+export declare const getAccessToken: (serviceAccountInfo: Record<string, any>) => Promise<string>;
+/**
+ * Gets an access token using Application Default Credentials (ADC).
+ * This function uses Google Auth Library's ADC which automatically detects:
+ * - Workload Identity when running in GKE
+ * - Service account keys from GOOGLE_APPLICATION_CREDENTIALS env var
+ * - GCE metadata service when running on GCE
+ * - User credentials when running locally (gcloud auth application-default login)
+ *
+ * @param session - Per-call session (tenantName for cache segregation)
+ * @param vertexProjectId - GCP project ID to include in cache key for proper segregation
+ * @param vertexRegion - GCP region to include in cache key for proper segregation
+ * @param cacheSegment - Optional provider account FQN (or other id) so ADC tokens do not collide across accounts
+ * @returns Access token string
+ */
+export declare const getAccessTokenFromADC: (session: SessionContext, vertexProjectId: string, vertexRegion: string, cacheSegment?: string) => Promise<string>;
+export declare const getModelAndProvider: (modelString: string) => {
+    provider: string;
+    model: string;
+};
+export declare const getMimeType: (url: string) => string | undefined;
+/**
+ * Media resolution level for Gemini API.
+ * Only LOW and HIGH are supported via OpenAI's detail parameter.
+ * MEDIUM exists in the API but cannot be set from OpenAI's detail.
+ * UNSPECIFIED exists but we omit the field instead for "auto".
+ */
+export type MediaResolutionLevel = 'MEDIA_RESOLUTION_LOW' | 'MEDIA_RESOLUTION_HIGH';
+/**
+ * Media resolution object structure for Gemini API.
+ */
+export type MediaResolution = {
+    level: MediaResolutionLevel;
+};
+/**
+ * Maps OpenAI's "detail" parameter to Gemini's "mediaResolution" parameter.
+ *
+ * Translation mapping:
+ * - "low" → "MEDIA_RESOLUTION_LOW"
+ * - "high" → "MEDIA_RESOLUTION_HIGH"
+ * - "auto" or null/undefined → null (omit the field)
+ *
+ * @param detail - Optional string: "low", "high", "auto", or null/undefined
+ * @returns Optional MediaResolution object, or null (to omit the field)
+ */
+export declare const mapOpenAIDetailToMediaResolution: (detail?: string | null) => MediaResolution | null;
+export declare const GoogleErrorResponseTransform: (response: GoogleErrorResponse, provider?: string) => ErrorResponse | undefined;
+export declare const derefer: (schema: any, defs?: Record<string, any> | null, stack?: Set<string>, depth?: number, budget?: {
+    nodes: number;
+}) => any;
+/** Allowed output mime types for Imagen (gen and edit). */
+declare const IMAGEN_ALLOWED_MIME_TYPES: string[];
+/**
+ * Maps OpenAI-style output_format (png | jpeg) and/or mimeType to Vertex mimeType (image/png | image/jpeg).
+ * Prefers output_format when present; falls back to mimeType if allowed. No webp (not OpenAI-compatible).
+ */
+export declare function toVertexOutputMimeType(outputFormat?: string, mimeType?: string): (typeof IMAGEN_ALLOWED_MIME_TYPES)[number] | undefined;
+/**
+ * Builds Imagen predict "parameters" that are valid for both image generation and image edit.
+ * Single source of truth for shared params; used by imageGenerate transformParams and image edit transformParametersObject.
+ * Does NOT include gen-only (sampleImageSize, aspectRatio, sampleImageStyle, enhancePrompt) or edit-only (editMode, baseSteps, guidanceScale).
+ * @see https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api
+ * @see https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api-edit
+ */
+export declare function buildSharedImagenPredictParams(params: Record<string, unknown>): Record<string, unknown>;
+export declare const transformParametersObject: (params: any) => Record<string, any>;
+export declare const transformInstancesObject: (params: any) => Record<string, any>[];
+export declare const transformGeminiToolParameters: (parameters: JsonSchema) => JsonSchema;
+export declare const recursivelyDeleteUnsupportedParameters: (obj: any) => void;
+export declare const GoogleResponseHandler: (response: Response | string | Record<string, unknown>, status: number) => Response;
+export declare const googleBatchStatusToOpenAI: (status: GoogleBatchRecord["state"]) => "cancelled" | "failed" | "cancelling" | "in_progress" | "completed" | "expired" | "validating";
+export declare const googleFinetuneStatusToOpenAI: (status: GoogleFinetuneRecord["state"]) => "cancelled" | "queued" | "failed" | "running" | "succeeded";
+export declare const GoogleToOpenAIBatch: (response: GoogleBatchRecord) => {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at: number;
+    completed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    completed_at: number;
+    failed_at: number;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    cancelled_at: number;
+    failed_at: number;
+    completed_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at: number;
+    completed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at: number;
+    completed_at: number;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    completed_at: number;
+    failed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    cancelled_at: number;
+    failed_at?: undefined;
+    completed_at: number;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at?: undefined;
+    completed_at: number;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at: number;
+    completed_at?: undefined;
+    cancelled_at: number;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    completed_at: number;
+    failed_at?: undefined;
+    cancelled_at: number;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    cancelled_at: number;
+    failed_at?: undefined;
+    completed_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at?: undefined;
+    completed_at?: undefined;
+    cancelled_at: number;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at: number;
+    completed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    completed_at: number;
+    failed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    cancelled_at: number;
+    failed_at?: undefined;
+    completed_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+} | {
+    errors?: {
+        object: string;
+        data: {
+            code: string;
+            message: string;
+        }[];
+    } | undefined;
+    request_counts: {
+        total: number;
+        completed: string | undefined;
+        failed: string | undefined;
+    };
+    failed_at?: undefined;
+    completed_at?: undefined;
+    cancelled_at?: undefined;
+    in_progress_at: number;
+    id: string | undefined;
+    object: string;
+    endpoint: BatchEndpoints;
+    input_file_id: string;
+    completion_window: null;
+    status: string;
+    output_file_id: string;
+    error_file_id: string;
+    created_at: number;
+};
+export declare const transformVertexLogprobs: (generation: GoogleResponseCandidate) => Logprobs[] | null;
+export declare const transformVertexFinetune: (params: FinetuneRequest) => {
+    hyperParameters: {
+        epochCount: number | undefined;
+        learningRateMultiplier: number | undefined;
+        adapterSize: number | undefined;
+    };
+    validation_dataset_uri?: string | undefined;
+    training_dataset_uri: string;
+};
+export declare const getBucketAndFile: (uri: string) => {
+    bucket: string;
+    file: string;
+};
+export declare const GoogleToOpenAIFinetune: (response: GoogleFinetuneRecord) => {
+    suffix?: string | undefined;
+    validation_file?: string | undefined;
+    hyperparameters: {
+        batch_size: number;
+        learning_rate_multiplier: number;
+        n_epochs: number;
+    };
+    model: string;
+    trained_tokens: number | undefined;
+    training_file: string;
+    finished_at?: number | undefined;
+    id: string | undefined;
+    object: string;
+    status: string;
+    created_at: number;
+    error: string;
+    fine_tuned_model: string | undefined;
+};
+export declare const vertexRequestLineHandler: (purpose: string, vertexBatchEndpoint: BatchEndpoints, transformedBody: any, requestId: string) => any;
+export declare const isEmbeddingModel: (modelName: string) => boolean;
+export declare const generateSignedURL: (serviceAccountInfo: Record<string, any>, bucketName: string, objectName: string, expiration?: number, httpMethod?: string, queryParameters?: Record<string, string>, headers?: Record<string, string>) => Promise<string>;
+/**
+ * Transforms Gemini API request body to Vertex AI format
+ * Removes the 'id' field from functionResponse AND functionCall objects, as
+ * Vertex AI rejects it ("Unknown name \"id\" ... Cannot find field").
+ *
+ * Gemini API format: functionResponse: { id, name, response }, functionCall: { id, name, args }
+ * Vertex AI format:  functionResponse: { name, response },      functionCall: { name, args }
+ *
+ * @param inputParams The request parameters to transform
+ */
+export declare const transformGeminiToVertexRequestBody: (inputParams: any) => void;
+export declare const OPENAI_AUDIO_FORMAT_TO_VERTEX_MIME_TYPE_MAPPING: {
+    mp3: string;
+    wav: string;
+    opus: string;
+    flac: string;
+    pcm16: string;
+    'x-aac': string;
+    'x-m4a': string;
+    mpeg: string;
+    mpga: string;
+    mp4: string;
+    webm: string;
+};
+export declare const transformInputAudioPart: (c: ContentType) => GoogleMessagePart;
+export declare const googleTools: string[];
+/**
+ * Transforms an OpenAI-style `{ type: "computer_use", ... }` tool into the
+ * Gemini API format `{ computerUse: { environment, excludedPredefinedFunctions } }`.
+ */
+export declare function transformComputerUseToolFromOpenAI(tool: Record<string, any>): Record<string, unknown>;
+export declare const transformGoogleTools: (tool: Tool) => any;
+export declare const buildGoogleSearchRetrievalTool: (tool: Tool) => GoogleSearchRetrievalTool;
+/**
+ * Returns true when the model supports any form of thinking configuration
+ * (either `thinkingLevel` for Gemini 3+ or `thinkingBudget` for Gemini 2.5).
+ *
+ * Returns false for models that don't support thinking at all (most Gemini 2.0,
+ * Gemini 1.x, experimental models, gemma, learnlm).
+ * For these, `reasoning_effort` / `thinking` params should be silently dropped.
+ */
+export declare const supportsThinking: (modelName: string) => boolean;
+/**
+ * Returns true when the model uses the `thinkingLevel` enum API (Gemini 3+).
+ * Returns false for models that use `thinkingBudget` (Gemini 2.5, gemini-robotics)
+ * or don't support thinking at all.
+ *
+ * IMPORTANT: Only call this after confirming `supportsThinking()` is true,
+ * otherwise a non-thinking model will fall into the `thinkingBudget` path.
+ */
+export declare const supportsThinkingLevel: (modelName: string) => boolean;
+/**
+ * Returns the Google-recommended dummy thought signature for Gemini 3+ models.
+ *
+ * When a multi-turn conversation contains tool calls that have no `thoughtSignature`
+ * (e.g. they were generated by an older model or by a non-Gemini provider), Gemini 3+
+ * models require a placeholder to bypass their signature validator. Google explicitly
+ * documents `base64("skip_thought_signature_validator")` as the bypass value:
+ * https://ai.google.dev/gemini-api/docs/thought-signatures#faqs
+ *
+ * Only inject this for Gemini 3+ (check via `supportsThinkingLevel`). Older models do
+ * not need or understand `thoughtSignature` at all.
+ */
+export declare const getDummyThoughtSignature: () => string;
+/**
+ * Returns true if the model is a Gemini 3 Flash variant.
+ * Gemini 3 Flash supports `thinkingLevel: "minimal"` while other Gemini 3 models
+ * only support `"low"` and above.
+ */
+export declare const isGemini3Flash: (modelName: string) => boolean;
+/**
+ * Builds the thinkingConfig object for Gemini 3+ models that use thinkingLevel.
+ *
+ * Maps OpenAI-compatible `reasoning_effort` strings to the `thinkingLevel` values
+ * accepted by the Gemini API:
+ * - "minimal" → "minimal" for Flash, "low" for other Gemini 3 models (Gemini 3 Pro/Ultra
+ *   do not support the "minimal" level)
+ * - "low"     → "low"
+ * - "medium"  → "medium"
+ * - "high"    → "high"
+ * - "none" / "disable" → { thinkingLevel: "minimal"/"low", includeThoughts: false }
+ *
+ * Centralizes the contract so both Google AI Studio and Vertex AI providers stay in sync.
+ */
+export declare const buildGeminiThinkingConfig: (reasoningEffort: string, model?: string) => {
+    thinkingLevel: string;
+    includeThoughts: boolean;
+};
+/**
+ * Maps an Anthropic-style `budget_tokens` value to the nearest Gemini 3 `thinkingLevel`.
+ *
+ * Gemini 3 does not accept `thinkingBudget`; it uses a semantic level enum instead.
+ * There is no official Google mapping, so we derive reasonable thresholds from
+ * Gemini 2.5 Pro's documented budget range (128–32 768, default 8 192):
+ *
+ *   Flash models (minimal / low / high):
+ *     budget_tokens < 4 096   → "minimal"
+ *     budget_tokens < 16 000  → "low"
+ *     budget_tokens >= 16 000 → "high"
+ *
+ *   Non-Flash Gemini 3 models (low / high — "minimal" not supported):
+ *     budget_tokens < 8 192   → "low"
+ *     budget_tokens >= 8 192  → "high"
+ */
+export declare function budgetTokensToThinkingLevel(budgetTokens: number | undefined, model: string): string;
+/**
+ * Map voice to Vertex AI format
+ * Supports:
+ * 1. OpenAI voice names (alloy, echo, fable, etc.) - will be mapped
+ * 2. Vertex AI voice names (en-US-Studio-O, etc.) - used directly
+ * 3. Dict with languageCode and name - used as-is
+ */
+export declare function mapVoiceToVertexFormat(voice: string | {
+    name: string;
+    languageCode: string;
+} | undefined, voiceMappings?: Record<string, string>, defaultLanguageCode?: string): {
+    languageCode: string;
+    name: string;
+} | null;
+export {};