@juspay/neurolink 9.63.1 → 9.64.0

package/dist/lib/providers/googleVertex.d.ts

@@ -1,37 +1,28 @@
-import { type LanguageModel, type Schema } from "ai";
 import type { ZodType } from "zod";
-import { type AIProviderName } from "../constants/enums.js";
+import { type Schema, type LanguageModel } from "ai";
+import { AIProviderName } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
-import type { EnhancedGenerateResult, TextGenerationOptions, NeurolinkCredentials, StreamOptions, StreamResult } from "../types/index.js";
+import type { EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult } from "../types/index.js";
 /**
- * Resolve the correct Vertex AI location for a given model.
+ * Resolve the effective Vertex region for a given model.
  *
- * Google-published models (gemini-*) require the global endpoint
- * (`aiplatform.googleapis.com`), not regional endpoints like
- * `us-east5-aiplatform.googleapis.com`. Regional endpoints return
- * "model not found" for these models.
+ * Policy (matches the bugfixes-suite contract):
+ *  - Every Gemini model (`gemini-*`) is force-routed to the `global` endpoint
+ *    regardless of any caller-supplied region. Regional endpoints 404 for
+ *    Gemini 3.x previews and the regional/global behaviour for 2.x is
+ *    consistent enough that pinning all Gemini traffic to global is the
+ *    right safe default. The legacy `GLOBAL_LOCATION_MODELS` allowlist is
+ *    kept as a defence-in-depth fallback so any non-`gemini-` identifiers
+ *    that still need global (e.g. image-gen aliases) keep working.
+ *  - Non-Gemini models (Claude on Vertex, embeddings, custom models) keep
+ *    the caller-supplied region or fall back to env-derived defaults.
  *
- * Anthropic-on-Vertex models (claude-*) require regional endpoints
- * and are handled separately by `createVertexAnthropicSettings`.
- *
- * Embedding models and custom models use the configured location as-is.
+ * @param modelName - The target model identifier.
+ * @param configuredLocation - Caller-provided region (e.g. options.region).
+ *   Used as the fallback for non-Gemini models; ignored for Gemini.
+ * @returns The region string to pass to the @google/genai client.
  */
-export declare const resolveVertexLocation: (modelName: string | undefined, configuredLocation: string) => string;
-/**
- * Vertex Model Aliases
- *
- * Maps shorthand model names to their full versioned IDs required by the
- * Vertex AI API. This allows users to pass convenient names like
- * "claude-sonnet-4-5" instead of "claude-sonnet-4-5@20250929".
- *
- * Alias resolution runs at the very start of getModel() so that all
- * downstream code (isAnthropicModel, validateAnthropicModelName, etc.)
- * sees the canonical versioned name.
- *
- * To add a new model: simply add an entry mapping the shorthand to the
- * full versioned string. No other changes are needed.
- */
-export declare const VERTEX_MODEL_ALIASES: Record<string, string>;
+export declare const resolveVertexLocation: (modelName: string | undefined, configuredLocation?: string) => string;
 /**
  * Google Vertex AI Provider v2 - BaseProvider Implementation
  *
@@ -43,39 +34,38 @@ export declare const VERTEX_MODEL_ALIASES: Record<string, string>;
  * - Enhanced error handling with setup guidance
  * - Tool registration and context management
  *
- * @important Structured Output Limitation (Gemini Models Only)
- * Google Gemini models on Vertex AI cannot combine function calling (tools) with
- * structured output (JSON schema). When using schemas, you MUST set disableTools: true.
- *
- * Error without disableTools:
- * "Function calling with a response mime type: 'application/json' is unsupported"
+ * @important Tools + Schema Support (Fixed)
+ * Gemini models on Vertex AI now support combining function calling (tools) with
+ * structured output (JSON schema) simultaneously. The fix works by NOT setting
+ * `responseMimeType: "application/json"` when tools are present, which was
+ * causing the Google API error.
  *
- * This limitation ONLY affects Gemini models. Anthropic Claude models via Vertex
- * AI do NOT have this limitation and support both tools + schemas simultaneously.
+ * The `responseSchema` is still set to guide the output structure, allowing
+ * tools to execute AND the final output to follow the schema format.
  *
- * @example Gemini models with schemas
+ * @example Gemini models with tools + schemas
  * ```typescript
  * const provider = new GoogleVertexProvider("gemini-2.5-flash");
  * const result = await provider.generate({
- *   input: { text: "Analyze data" },
+ *   input: { text: "Analyze data using tools" },
  *   schema: MySchema,
  *   output: { format: "json" },
- *   disableTools: true  // Required for Gemini models
+ *   // No need for disableTools: true anymore!
  * });
  * ```
  *
- * @example Claude models (no limitation)
+ * @example Claude models (always supported both)
  * ```typescript
  * const provider = new GoogleVertexProvider("claude-3-5-sonnet-20241022");
  * const result = await provider.generate({
  *   input: { text: "Analyze data" },
  *   schema: MySchema,
  *   output: { format: "json" }
- *   // No disableTools needed - Claude supports both
  * });
  * ```
  *
- * @note Gemini 3 Pro Preview (November 2025) will support combining tools + schemas
+ * @note "Too many states for serving" errors can still occur with very complex schemas + tools.
+ *       Solution: Simplify schema or reduce number of tools if this occurs.
  * @see https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models
  */
 export declare class GoogleVertexProvider extends BaseProvider {
@@ -83,31 +73,20 @@ export declare class GoogleVertexProvider extends BaseProvider {
     private location;
     private registeredTools;
     private toolContext;
-    private credentials;
     private static modelConfigCache;
     private static modelConfigCacheTime;
     private static readonly CACHE_DURATION;
     private static readonly MAX_CACHE_SIZE;
     private static maxTokensCache;
     private static maxTokensCacheTime;
-    constructor(modelName?: string, _providerName?: string, sdk?: unknown, region?: string, credentials?: NeurolinkCredentials["vertex"]);
+    constructor(modelName?: string, _providerName?: string, sdk?: unknown, region?: string, credentials?: Record<string, unknown>);
     protected getProviderName(): AIProviderName;
     protected getDefaultModel(): string;
-    /**
-     * Get the default embedding model for Google Vertex
-     * @returns The default Vertex AI embedding model name
-     */
-    protected getDefaultEmbeddingModel(): string;
     /**
      * Returns the Vercel AI SDK model instance for Google Vertex
      * Creates fresh model instances for each request
      */
     protected getAISDKModel(): Promise<LanguageModel>;
-    /**
-     * Resolve a raw model name through the alias map.
-     * Used internally to normalize model names before any API calls.
-     */
-    private resolveAlias;
     /**
      * Initialize model creation tracking
      */
@@ -121,7 +100,7 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     private createGoogleVertexModel;
     /**
-     * Create Vertex AI instance and model with comprehensive logging
+     * @deprecated This method is no longer used. All models now use native SDKs.
      */
     private createVertexInstance;
     /**
@@ -134,43 +113,40 @@ export declare class GoogleVertexProvider extends BaseProvider {
      * Validate stream options
      */
     private validateStreamOptionsOnly;
-    protected executeStream(options: StreamOptions, analysisSchema?: ZodType | Schema<unknown>): Promise<StreamResult>;
-    private maybeExecuteNativeGemini3ToolStream;
-    private executeAISDKStream;
-    private resolveAISDKStreamTools;
-    private buildAISDKStreamOptions;
-    private captureAISDKStreamToolStep;
-    private startObservedAISDKStream;
-    private attachAISDKStreamObservers;
-    private observeAISDKStreamResult;
+    protected executeStream(options: StreamOptions, _analysisSchema?: ZodType<unknown> | Schema<unknown>): Promise<StreamResult>;
     /**
-     * Create @google/genai client configured for Vertex AI
+     * Emit `stream:end` so the Pipeline B observability listener creates a
+     * `model.generation` span for native Vertex stream traffic. Mirrors
+     * `emitGenerationEnd` (used by `generate()`).
      */
-    private createVertexGenAIClient;
+    private emitStreamEnd;
     /**
-     * Build multimodal content parts (user message) from input text, PDFs, and images.
-     * Shared by both stream and generate native Gemini 3 paths.
-     */
-    private buildNativeContentParts;
-    /**
-     * Convert conversationMessages from NeuroLink's ChatMessage format into
-     * the @google/genai contents format and prepend them before the current
-     * user message. This gives the native Gemini 3 path multi-turn context
-     * that was previously dropped (only the current prompt was sent).
+     * Create @google/genai client configured for Vertex AI
      */
-    private prependConversationHistory;
+    private createVertexGenAIClient;
     /**
      * Execute stream using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
      */
     private executeNativeGemini3Stream;
-    private executeNativeGemini3StreamWithSpan;
-    private runNativeGemini3StreamLoop;
     /**
      * Execute generate using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
      */
     private executeNativeGemini3Generate;
+    /**
+     * Create native AnthropicVertex client for Claude models
+     */
+    private createAnthropicVertexClient;
+    /**
+     * Execute stream using native @anthropic-ai/vertex-sdk for Claude models on Vertex AI
+     * This bypasses @ai-sdk/google-vertex completely and uses Anthropic's native SDK
+     */
+    private executeNativeAnthropicStream;
+    /**
+     * Execute generate using native @anthropic-ai/vertex-sdk for Claude models on Vertex AI
+     */
+    private executeNativeAnthropicGenerate;
     /**
      * Process CSV files and append content to options.input.text
      * This ensures CSV data is available in the prompt for native Gemini 3 SDK calls
@@ -178,9 +154,52 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     private processCSVFilesForNativeSDK;
     /**
-     * Override generate to route Gemini 3 models with tools to native SDK
+     * Override stream to handle image generation models
+     * Image models don't support streaming, so we fall back to generate
+     */
+    stream(optionsOrPrompt: StreamOptions | string): Promise<StreamResult>;
+    /**
+     * Override generate to route ALL models to native SDKs
+     * No more @ai-sdk/google-vertex dependency
      */
     generate(optionsOrPrompt: TextGenerationOptions | string): Promise<EnhancedGenerateResult | null>;
+    /**
+     * Invoke `options.onFinish` with the lifecycle payload shape consumers
+     * (and `test:middleware`) expect. Pulled out so generate / image-gen /
+     * Anthropic / Gemini code paths share one implementation. Errors thrown
+     * by the user's callback are swallowed so they cannot poison the
+     * primary generate path — same contract as the AI SDK middleware
+     * wrapGenerate uses.
+     */
+    private fireGenerateOnFinish;
+    /**
+     * Invoke `options.onError` with the lifecycle payload shape consumers
+     * (and `test:middleware`) expect. Mirrors {@link fireGenerateOnFinish}.
+     */
+    private fireGenerateOnError;
+    /**
+     * Wrap a {@link StreamResult} so each text chunk drives `options.onChunk`
+     * and the final yield drives `options.onFinish`. Pipeline A providers get
+     * this for free via the AI SDK `wrapStream` middleware; native @google/genai
+     * bypasses that wrapper, so native consumers need their lifecycle
+     * callbacks invoked from here.
+     */
+    private wrapStreamResultWithLifecycle;
+    /**
+     * Attach `gen_ai.usage.*` and `neurolink.cost` attributes to a span.
+     * Pulled out so the generate / stream / image-gen paths share one
+     * implementation, and so observability/tracing tests find consistent
+     * attributes regardless of which native sub-route fulfilled the request.
+     */
+    private attachUsageAndCostAttributes;
+    /**
+     * Emit `generation:end` so the Pipeline B observability listener creates
+     * the corresponding `model.generation` span. Vertex bypasses the AI SDK
+     * (and therefore the experimental_telemetry plumbing), so this hand-off
+     * is the only way native Vertex calls show up in Langfuse / Pipeline B
+     * exporters. Mirrors the Bedrock + Ollama pattern.
+     */
+    private emitGenerationEnd;
     protected formatProviderError(error: unknown): Error;
     /**
      * Memory-safe cache management for model configurations
@@ -208,27 +227,10 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     hasAnthropicSupport(): Promise<boolean>;
     /**
-     * Resolve a shorthand model name to its full versioned Vertex AI identifier.
-     * Returns the original name unchanged if no alias exists.
-     *
-     * @param modelName - A model name, possibly a shorthand alias
-     * @returns The resolved full versioned model name
-     *
-     * @example
-     * ```typescript
-     * provider.resolveModelAlias("claude-sonnet-4-5"); // "claude-sonnet-4-5@20250929"
-     * provider.resolveModelAlias("gemini-3-pro");      // "gemini-3.1-pro-preview"
-     * provider.resolveModelAlias("gemini-2.5-flash");  // "gemini-2.5-flash" (unchanged)
-     * ```
+     * @deprecated This method is no longer used. Claude models now use native @anthropic-ai/vertex-sdk
+     * via executeNativeAnthropicStream and executeNativeAnthropicGenerate.
      */
-    resolveModelAlias(modelName: string): string;
-    /**
-     * Create an Anthropic model instance using vertexAnthropic provider
-     * Uses fresh vertex settings for each request with comprehensive validation
-     * @param modelName Anthropic model name (e.g., 'claude-3-sonnet@20240229')
-     * @returns LanguageModel instance or null if not available
-     */
-    createAnthropicModel(modelName: string): Promise<LanguageModel | null>;
+    createAnthropicModel(_modelName: string): Promise<LanguageModel | null>;
     /**
      * Validate Vertex AI authentication configuration
      */
@@ -299,28 +301,12 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     private detectImageType;
     /**
-     * Estimate token count from text using centralized estimation with provider multipliers
+     * Estimate token count from text (simple character-based estimation)
      */
     private estimateTokenCount;
     /**
-     * Obtain a Google Auth access token for Vertex AI REST API calls.
+     * Build image parts for multimodal content
      */
-    private getImageGenerationAccessToken;
-    /**
-     * Build request parts for image generation from prompt, PDFs, and images.
-     */
-    private buildImageGenerationParts;
-    /**
-     * Parse the Vertex AI image generation REST API response.
-     *
-     * Dual-mode image models (gemini-3.1-flash-image-preview, gemini-2.5-flash-image,
-     * gemini-3-pro-image-preview) decide per-request whether to emit an image or text.
-     * When the response contains text parts but no image part, surface the text via
-     * `textFallback` so the caller can return a normal text result instead of throwing
-     * "model returned text instead of image data" and burning retries on a query that
-     * the model has already answered.
-     */
-    private parseImageGenerationResponse;
     /**
      * Overrides the BaseProvider's image generation method to implement it for Vertex AI.
      * Uses REST API approach with google-auth-library for authentication.
@@ -330,23 +316,24 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     protected executeImageGeneration(options: TextGenerationOptions): Promise<EnhancedGenerateResult>;
     /**
-     * Generate embeddings for text using Google Vertex AI text-embedding models
-     * @param text - The text to embed
-     * @param modelName - The embedding model to use (default: text-embedding-004)
-     * @returns Promise resolving to the embedding vector
+     * Get model suggestions when a model is not found
      */
-    embed(text: string, modelName?: string): Promise<number[]>;
+    private getModelSuggestions;
     /**
-     * Generate embeddings for multiple texts in a single batch
-     * @param texts - The texts to embed
-     * @param modelName - The embedding model to use (default: text-embedding-004)
-     * @returns Promise resolving to an array of embedding vectors
+     * Generate an embedding for `text` using Vertex via @google/genai.
+     *
+     * Replaces the previous `@ai-sdk/google-vertex` text embedding model
+     * path. Without this, RAG indexing falls through to BaseProvider.embed()
+     * which throws "Embedding generation is not supported by the vertex
+     * provider", and `neurolink rag index --provider=vertex` fails even
+     * though the SDK conceptually supports it.
      */
-    embedMany(texts: string[], modelName?: string): Promise<number[][]>;
+    embed(text: string, modelName?: string): Promise<number[]>;
     /**
-     * Get model suggestions when a model is not found
+     * Batch-embed an array of strings via Vertex @google/genai.
+     * Mirrors {@link embed} but returns one vector per input string.
      */
-    private getModelSuggestions;
+    embedMany(texts: string[], modelName?: string): Promise<number[][]>;
 }
 export default GoogleVertexProvider;
 export { GoogleVertexProvider as GoogleVertexAI };