@juspay/neurolink 9.9.0 → 9.10.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [9.10.1](https://github.com/juspay/neurolink/compare/v9.10.0...v9.10.1) (2026-02-21)
+
+### Bug Fixes
+
+- **(video-analysis):** add stream support for video analysis ([938aeef](https://github.com/juspay/neurolink/commit/938aeef876277360700d2a7192155af1f1316f28))
+
+## [9.10.0](https://github.com/juspay/neurolink/compare/v9.9.0...v9.10.0) (2026-02-20)
+
+### Features
+
+- **(generateText):** add prepareStep and toolChoice passthrough support for multi-step agentic generation ([4cd340a](https://github.com/juspay/neurolink/commit/4cd340af7d39f72006d09fe86569232d751dcd8d))
+
 ## [9.9.0](https://github.com/juspay/neurolink/compare/v9.8.0...v9.9.0) (2026-02-17)
 
 ### Features

package/README.md

@@ -35,17 +35,18 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 ## What's New (Q1 2026)
 
-| Feature                             | Version | Description                                                                                                                                                   | Guide                                                           |
-| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| **Context Window Management**       | v9.2.0  | 4-stage compaction pipeline with auto-detection, budget gate at 80% usage, per-provider token estimation                                                      | [Context Compaction Guide](docs/features/context-compaction.md) |
-| **File Processor System**           | v9.1.0  | 17+ file type processors with ProcessorRegistry, security sanitization, SVG text injection                                                                    | [File Processors Guide](docs/features/file-processors.md)       |
-| **RAG with generate()/stream()**    | v9.2.0  | Pass `rag: { files }` to generate/stream for automatic document chunking, embedding, and AI-powered search. 10 chunking strategies, hybrid search, reranking. | [RAG Guide](docs/features/rag.md)                               |
-| **External TracerProvider Support** | v8.43.0 | Integrate NeuroLink with existing OpenTelemetry instrumentation. Prevents duplicate registration conflicts.                                                   | [Observability Guide](docs/features/observability.md)           |
-| **Server Adapters**                 | v8.43.0 | Multi-framework HTTP server with Hono, Express, Fastify, Koa support. Full CLI for server management with foreground/background modes.                        | [Server Adapters Guide](docs/guides/server-adapters/index.md)   |
-| **Title Generation Events**         | v8.38.0 | Emit `conversation:titleGenerated` event when conversation title is generated. Supports custom title prompts via `NEUROLINK_TITLE_PROMPT`.                    | [Conversation Memory Guide](docs/conversation-memory.md)        |
-| **Video Generation with Veo**       | v8.32.0 | Video generation using Veo 3.1 (`veo-3.1`). Realistic video generation with many parameter options                                                            | [Video Generation Guide](docs/features/video-generation.md)     |
-| **Image Generation with Gemini**    | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI.                | [Image Generation Guide](docs/image-generation-streaming.md)    |
-| **HTTP/Streamable HTTP Transport**  | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.                 | [HTTP Transport Guide](docs/mcp-http-transport.md)              |
+| Feature                             | Version | Description                                                                                                                                                   | Guide                                                                 |
+| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **Context Window Management**       | v9.2.0  | 4-stage compaction pipeline with auto-detection, budget gate at 80% usage, per-provider token estimation                                                      | [Context Compaction Guide](docs/features/context-compaction.md)       |
+| **Tool Execution Control**          | v9.3.0  | `prepareStep` and `toolChoice` support for per-step tool enforcement in multi-step agentic loops. API-level control over tool calls.                          | [API Reference](docs/api/type-aliases/GenerateOptions.md#preparestep) |
+| **File Processor System**           | v9.1.0  | 17+ file type processors with ProcessorRegistry, security sanitization, SVG text injection                                                                    | [File Processors Guide](docs/features/file-processors.md)             |
+| **RAG with generate()/stream()**    | v9.2.0  | Pass `rag: { files }` to generate/stream for automatic document chunking, embedding, and AI-powered search. 10 chunking strategies, hybrid search, reranking. | [RAG Guide](docs/features/rag.md)                                     |
+| **External TracerProvider Support** | v8.43.0 | Integrate NeuroLink with existing OpenTelemetry instrumentation. Prevents duplicate registration conflicts.                                                   | [Observability Guide](docs/features/observability.md)                 |
+| **Server Adapters**                 | v8.43.0 | Multi-framework HTTP server with Hono, Express, Fastify, Koa support. Full CLI for server management with foreground/background modes.                        | [Server Adapters Guide](docs/guides/server-adapters/index.md)         |
+| **Title Generation Events**         | v8.38.0 | Emit `conversation:titleGenerated` event when conversation title is generated. Supports custom title prompts via `NEUROLINK_TITLE_PROMPT`.                    | [Conversation Memory Guide](docs/conversation-memory.md)              |
+| **Video Generation with Veo**       | v8.32.0 | Video generation using Veo 3.1 (`veo-3.1`). Realistic video generation with many parameter options                                                            | [Video Generation Guide](docs/features/video-generation.md)           |
+| **Image Generation with Gemini**    | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI.                | [Image Generation Guide](docs/image-generation-streaming.md)          |
+| **HTTP/Streamable HTTP Transport**  | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.                 | [HTTP Transport Guide](docs/mcp-http-transport.md)                    |
 
 - **External TracerProvider Support** – Integrate NeuroLink with applications that already have OpenTelemetry instrumentation. Supports auto-detection and manual configuration. → [Observability Guide](docs/features/observability.md)
 - **Server Adapters** – Deploy NeuroLink as an HTTP API server with your framework of choice (Hono, Express, Fastify, Koa). Full CLI support with `serve` and `server` commands for foreground/background modes, route management, and OpenAPI generation. → [Server Adapters Guide](docs/guides/server-adapters/index.md)
@@ -56,6 +57,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 - **RAG with generate()/stream()** – Just pass `rag: { files: ["./docs/guide.md"] }` to `generate()` or `stream()`. NeuroLink auto-chunks, embeds, and creates a search tool the AI can invoke. 10 chunking strategies, hybrid search, 5 reranker types. → [RAG Guide](docs/features/rag.md)
 - **HTTP/Streamable HTTP Transport for MCP** – Connect to remote MCP servers via HTTP with authentication headers, retry logic, and rate limiting. → [HTTP Transport Guide](docs/mcp-http-transport.md)
 - 🧠 **Gemini 3 Preview Support** - Full support for gemini-3-flash-preview and gemini-3-pro-preview with extended thinking capabilities
+- 🎯 **Tool Execution Control** – Use `prepareStep` to enforce specific tool calls, change the LLM models per step in multi-step agentic executions. Prevents LLMs from skipping required tools. Use `toolChoice` for static control, or `prepareStep` for dynamic per-step logic. → [GenerateOptions Reference](docs/api/type-aliases/GenerateOptions.md#preparestep)
 - **Structured Output with Zod Schemas** – Type-safe JSON generation with automatic validation using `schema` + `output.format: "json"` in `generate()`. → [Structured Output Guide](docs/features/structured-output.md)
 - **CSV File Support** – Attach CSV files to prompts for AI-powered data analysis with auto-detection. → [CSV Guide](docs/features/multimodal-chat.md#csv-file-support)
 - **PDF File Support** – Process PDF documents with native visual analysis for Vertex AI, Anthropic, Bedrock, AI Studio. → [PDF Guide](docs/features/pdf-support.md)

package/dist/adapters/video/videoAnalyzer.d.ts

@@ -8,16 +8,16 @@
  */
 import { AIProviderName } from "../../constants/enums.js";
 import type { CoreMessage } from "ai";
-export declare function analyzeVideoWithVertexAI(frames: CoreMessage, options?: {
+export declare function analyzeVideoWithVertexAI(messages: CoreMessage[], options?: {
     project?: string;
     location?: string;
     model?: string;
 }): Promise<string>;
-export declare function analyzeVideoWithGeminiAPI(frames: CoreMessage, options?: {
+export declare function analyzeVideoWithGeminiAPI(messages: CoreMessage[], options?: {
     apiKey?: string;
     model?: string;
 }): Promise<string>;
-export declare function analyzeVideo(frames: CoreMessage, options?: {
+export declare function analyzeVideo(messages: CoreMessage[], options?: {
     provider?: AIProviderName;
     project?: string;
     location?: string;

package/dist/adapters/video/videoAnalyzer.js

@@ -9,23 +9,35 @@
 import { AIProviderName, ErrorSeverity, ErrorCategory, } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
 import { readFile } from "node:fs/promises";
-import { NeuroLinkError } from "../../utils/errorHandling.js";
+import { NeuroLinkError, ErrorFactory } from "../../utils/errorHandling.js";
 // ---------------------------------------------------------------------------
 // Shared config
 // ---------------------------------------------------------------------------
 const DEFAULT_MODEL = "gemini-2.0-flash";
 const DEFAULT_LOCATION = "us-central1";
+/**
+ * Extract content items from user messages
+ *
+ * @param messages - Array of CoreMessage objects
+ * @returns Flattened array of content items from user messages
+ */
+function extractUserContent(messages) {
+    const userMessages = messages.filter((msg) => msg.role === "user");
+    return userMessages.flatMap((msg) => Array.isArray(msg.content) ? msg.content : []);
+}
 /**
  * Convert CoreMessage content array to Gemini parts format
  *
- * @param contentArray - Array of content items from CoreMessage
+ * @param messages - Array of CoreMessage objects
  * @returns Array of parts in Gemini API format
  */
-function buildContentParts(frames) {
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    return contentArray.map((item) => {
-        if (item.type === "text" && item.text) {
-            return { text: item.text };
+function buildContentParts(messages) {
+    const allContent = extractUserContent(messages);
+    return allContent
+        .map((item) => {
+        if (item.type === "text") {
+            // Accept text parts regardless of whether text is empty
+            return { text: item.text || "" };
         }
         else if (item.type === "image" && item.image) {
             let base64Data;
@@ -38,7 +50,7 @@ function buildContentParts(frames) {
                 base64Data = item.image.replace(/^data:image\/[a-z]+;base64,/, "");
             }
             else {
-                throw new Error(`Invalid image data type: expected string, Buffer, or Uint8Array, got ${typeof item.image}`);
+                throw ErrorFactory.invalidConfiguration("image data type", `expected string, Buffer, or Uint8Array, got ${typeof item.image}`, { itemType: item.type, dataType: typeof item.image });
             }
             return {
                 inlineData: {
@@ -47,8 +59,14 @@ function buildContentParts(frames) {
                 },
             };
         }
-        throw new Error(`Invalid content type: ${item.type}`);
-    });
+        else if (item.type === "file") {
+            // Skip file parts - not supported in Gemini parts format
+            return null;
+        }
+        // Return null for unsupported types
+        return null;
+    })
+        .filter((part) => part !== null);
 }
 /**
  * Configuration for video frame analysis.
@@ -88,7 +106,7 @@ Ensure the final response is fully self-sufficient and does not reference extern
 // ---------------------------------------------------------------------------
 // Vertex AI
 // ---------------------------------------------------------------------------
-export async function analyzeVideoWithVertexAI(frames, options = {}) {
+export async function analyzeVideoWithVertexAI(messages, options = {}) {
     const startTime = Date.now();
     const { GoogleGenAI } = await import("@google/genai");
     // Get default config and merge with provided options
@@ -96,9 +114,9 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
     const project = options.project ?? config.project;
     const location = options.location ?? config.location;
     const model = options.model || DEFAULT_MODEL;
-    // Extract content array from CoreMessage
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    const frameCount = contentArray.filter((item) => item.type === "image").length;
+    // Convert frames content to parts array for Gemini
+    const parts = buildContentParts(messages);
+    const frameCount = parts.filter((part) => "inlineData" in part && part.inlineData).length;
     logger.debug("[GeminiVideoAnalyzer] Analyzing video with Vertex AI", {
         project,
         location,
@@ -106,8 +124,6 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
         frameCount,
     });
     const ai = new GoogleGenAI({ vertexai: true, project, location });
-    // Convert frames content to parts array for Gemini
-    const parts = buildContentParts(frames);
     const response = await ai.models.generateContent({
         model,
         config: buildConfig(),
@@ -129,7 +145,7 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
 // ---------------------------------------------------------------------------
 // Gemini API (Google AI)
 // ---------------------------------------------------------------------------
-export async function analyzeVideoWithGeminiAPI(frames, options = {}) {
+export async function analyzeVideoWithGeminiAPI(messages, options = {}) {
     const startTime = Date.now();
     const { GoogleGenAI } = await import("@google/genai");
     const apiKey = options.apiKey || process.env.GOOGLE_AI_API_KEY;
@@ -137,16 +153,14 @@ export async function analyzeVideoWithGeminiAPI(frames, options = {}) {
     if (!apiKey) {
         throw new Error("GOOGLE_AI_API_KEY environment variable is required for Gemini API video analysis");
     }
-    // Extract content array from CoreMessage
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    const frameCount = contentArray.filter((item) => item.type === "image").length;
+    // Convert frames content to parts array for Gemini
+    const parts = buildContentParts(messages);
+    const frameCount = parts.filter((part) => "inlineData" in part && part.inlineData).length;
     logger.debug("[GeminiVideoAnalyzer] Analyzing video with Gemini API", {
         model,
         frameCount,
     });
     const ai = new GoogleGenAI({ apiKey });
-    // Convert frames content to parts array for Gemini
-    const parts = buildContentParts(frames);
     logger.debug("[GeminiVideoAnalyzer] Generating analysis with frames");
     const response = await ai.models.generateContent({
         model,
@@ -207,15 +221,15 @@ async function getVertexConfig() {
     }
     return { project, location };
 }
-export async function analyzeVideo(frames, options = {}) {
+export async function analyzeVideo(messages, options = {}) {
     const provider = options.provider || AIProviderName.AUTO;
     // Vertex — only when GOOGLE_VERTEX_PROJECT is explicitly set
     if (provider === AIProviderName.VERTEX || provider === AIProviderName.AUTO) {
-        return analyzeVideoWithVertexAI(frames, options);
+        return analyzeVideoWithVertexAI(messages, options);
     }
     // Gemini API — when GOOGLE_AI_API_KEY is set
     if (provider === AIProviderName.GOOGLE_AI && process.env.GOOGLE_AI_API_KEY) {
-        return analyzeVideoWithGeminiAPI(frames, options);
+        return analyzeVideoWithGeminiAPI(messages, options);
     }
     throw new Error("No valid provider configuration found. " +
         "Set GOOGLE_VERTEX_PROJECT for Vertex AI or GOOGLE_AI_API_KEY for Gemini API.");

package/dist/cli/loop/optionsSchema.d.ts

@@ -5,4 +5,4 @@ import type { TextGenerationOptions } from "../../lib/types/generateTypes.js";
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "tts" | "thinkingConfig" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "tts" | "thinkingConfig" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep">, OptionSchema>;

package/dist/core/baseProvider.js

@@ -86,6 +86,20 @@ export class BaseProvider {
             temperature: options.temperature,
             timestamp: Date.now(),
         });
+        // ===== EARLY MULTIMODAL DETECTION =====
+        const hasFileInput = !!options.input?.files?.length || !!options.input?.videoFiles?.length;
+        if (hasFileInput) {
+            // ===== VIDEO ANALYSIS DETECTION =====
+            // Check if video frames are present and handle with fake streaming
+            const messages = await this.buildMessagesForStream(options);
+            if (hasVideoFrames(messages)) {
+                logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
+                    provider: this.providerName,
+                    model: this.modelName,
+                });
+                return await this.executeFakeStreaming(options, analysisSchema);
+            }
+        }
         // 🔧 CRITICAL: Image generation models don't support real streaming
         // Force fake streaming for image models to ensure image output is yielded
         const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));

package/dist/core/modules/GenerationHandler.js

@@ -49,8 +49,12 @@ export class GenerationHandler {
             model,
             messages,
             ...(shouldUseTools && Object.keys(tools).length > 0 && { tools }),
-            maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
-            ...(shouldUseTools && { toolChoice: "auto" }),
+            maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
+            ...(shouldUseTools &&
+                options.toolChoice && { toolChoice: options.toolChoice }),
+            ...(options.prepareStep && {
+                experimental_prepareStep: options.prepareStep,
+            }),
             temperature: options.temperature,
             maxTokens: options.maxTokens,
             abortSignal: options.abortSignal,

package/dist/lib/adapters/video/videoAnalyzer.d.ts

@@ -8,16 +8,16 @@
  */
 import { AIProviderName } from "../../constants/enums.js";
 import type { CoreMessage } from "ai";
-export declare function analyzeVideoWithVertexAI(frames: CoreMessage, options?: {
+export declare function analyzeVideoWithVertexAI(messages: CoreMessage[], options?: {
     project?: string;
     location?: string;
     model?: string;
 }): Promise<string>;
-export declare function analyzeVideoWithGeminiAPI(frames: CoreMessage, options?: {
+export declare function analyzeVideoWithGeminiAPI(messages: CoreMessage[], options?: {
     apiKey?: string;
     model?: string;
 }): Promise<string>;
-export declare function analyzeVideo(frames: CoreMessage, options?: {
+export declare function analyzeVideo(messages: CoreMessage[], options?: {
     provider?: AIProviderName;
     project?: string;
     location?: string;

package/dist/lib/adapters/video/videoAnalyzer.js

@@ -9,23 +9,35 @@
 import { AIProviderName, ErrorSeverity, ErrorCategory, } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
 import { readFile } from "node:fs/promises";
-import { NeuroLinkError } from "../../utils/errorHandling.js";
+import { NeuroLinkError, ErrorFactory } from "../../utils/errorHandling.js";
 // ---------------------------------------------------------------------------
 // Shared config
 // ---------------------------------------------------------------------------
 const DEFAULT_MODEL = "gemini-2.0-flash";
 const DEFAULT_LOCATION = "us-central1";
+/**
+ * Extract content items from user messages
+ *
+ * @param messages - Array of CoreMessage objects
+ * @returns Flattened array of content items from user messages
+ */
+function extractUserContent(messages) {
+    const userMessages = messages.filter((msg) => msg.role === "user");
+    return userMessages.flatMap((msg) => Array.isArray(msg.content) ? msg.content : []);
+}
 /**
  * Convert CoreMessage content array to Gemini parts format
  *
- * @param contentArray - Array of content items from CoreMessage
+ * @param messages - Array of CoreMessage objects
  * @returns Array of parts in Gemini API format
  */
-function buildContentParts(frames) {
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    return contentArray.map((item) => {
-        if (item.type === "text" && item.text) {
-            return { text: item.text };
+function buildContentParts(messages) {
+    const allContent = extractUserContent(messages);
+    return allContent
+        .map((item) => {
+        if (item.type === "text") {
+            // Accept text parts regardless of whether text is empty
+            return { text: item.text || "" };
         }
         else if (item.type === "image" && item.image) {
             let base64Data;
@@ -38,7 +50,7 @@ function buildContentParts(frames) {
                 base64Data = item.image.replace(/^data:image\/[a-z]+;base64,/, "");
             }
             else {
-                throw new Error(`Invalid image data type: expected string, Buffer, or Uint8Array, got ${typeof item.image}`);
+                throw ErrorFactory.invalidConfiguration("image data type", `expected string, Buffer, or Uint8Array, got ${typeof item.image}`, { itemType: item.type, dataType: typeof item.image });
             }
             return {
                 inlineData: {
@@ -47,8 +59,14 @@ function buildContentParts(frames) {
                 },
             };
         }
-        throw new Error(`Invalid content type: ${item.type}`);
-    });
+        else if (item.type === "file") {
+            // Skip file parts - not supported in Gemini parts format
+            return null;
+        }
+        // Return null for unsupported types
+        return null;
+    })
+        .filter((part) => part !== null);
 }
 /**
  * Configuration for video frame analysis.
@@ -88,7 +106,7 @@ Ensure the final response is fully self-sufficient and does not reference extern
 // ---------------------------------------------------------------------------
 // Vertex AI
 // ---------------------------------------------------------------------------
-export async function analyzeVideoWithVertexAI(frames, options = {}) {
+export async function analyzeVideoWithVertexAI(messages, options = {}) {
     const startTime = Date.now();
     const { GoogleGenAI } = await import("@google/genai");
     // Get default config and merge with provided options
@@ -96,9 +114,9 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
     const project = options.project ?? config.project;
     const location = options.location ?? config.location;
     const model = options.model || DEFAULT_MODEL;
-    // Extract content array from CoreMessage
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    const frameCount = contentArray.filter((item) => item.type === "image").length;
+    // Convert frames content to parts array for Gemini
+    const parts = buildContentParts(messages);
+    const frameCount = parts.filter((part) => "inlineData" in part && part.inlineData).length;
     logger.debug("[GeminiVideoAnalyzer] Analyzing video with Vertex AI", {
         project,
         location,
@@ -106,8 +124,6 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
         frameCount,
     });
     const ai = new GoogleGenAI({ vertexai: true, project, location });
-    // Convert frames content to parts array for Gemini
-    const parts = buildContentParts(frames);
     const response = await ai.models.generateContent({
         model,
         config: buildConfig(),
@@ -129,7 +145,7 @@ export async function analyzeVideoWithVertexAI(frames, options = {}) {
 // ---------------------------------------------------------------------------
 // Gemini API (Google AI)
 // ---------------------------------------------------------------------------
-export async function analyzeVideoWithGeminiAPI(frames, options = {}) {
+export async function analyzeVideoWithGeminiAPI(messages, options = {}) {
     const startTime = Date.now();
     const { GoogleGenAI } = await import("@google/genai");
     const apiKey = options.apiKey || process.env.GOOGLE_AI_API_KEY;
@@ -137,16 +153,14 @@ export async function analyzeVideoWithGeminiAPI(frames, options = {}) {
     if (!apiKey) {
         throw new Error("GOOGLE_AI_API_KEY environment variable is required for Gemini API video analysis");
     }
-    // Extract content array from CoreMessage
-    const contentArray = Array.isArray(frames.content) ? frames.content : [];
-    const frameCount = contentArray.filter((item) => item.type === "image").length;
+    // Convert frames content to parts array for Gemini
+    const parts = buildContentParts(messages);
+    const frameCount = parts.filter((part) => "inlineData" in part && part.inlineData).length;
     logger.debug("[GeminiVideoAnalyzer] Analyzing video with Gemini API", {
         model,
         frameCount,
     });
     const ai = new GoogleGenAI({ apiKey });
-    // Convert frames content to parts array for Gemini
-    const parts = buildContentParts(frames);
     logger.debug("[GeminiVideoAnalyzer] Generating analysis with frames");
     const response = await ai.models.generateContent({
         model,
@@ -207,15 +221,15 @@ async function getVertexConfig() {
     }
     return { project, location };
 }
-export async function analyzeVideo(frames, options = {}) {
+export async function analyzeVideo(messages, options = {}) {
     const provider = options.provider || AIProviderName.AUTO;
     // Vertex — only when GOOGLE_VERTEX_PROJECT is explicitly set
     if (provider === AIProviderName.VERTEX || provider === AIProviderName.AUTO) {
-        return analyzeVideoWithVertexAI(frames, options);
+        return analyzeVideoWithVertexAI(messages, options);
     }
     // Gemini API — when GOOGLE_AI_API_KEY is set
     if (provider === AIProviderName.GOOGLE_AI && process.env.GOOGLE_AI_API_KEY) {
-        return analyzeVideoWithGeminiAPI(frames, options);
+        return analyzeVideoWithGeminiAPI(messages, options);
     }
     throw new Error("No valid provider configuration found. " +
         "Set GOOGLE_VERTEX_PROJECT for Vertex AI or GOOGLE_AI_API_KEY for Gemini API.");

package/dist/lib/core/baseProvider.js

@@ -86,6 +86,20 @@ export class BaseProvider {
             temperature: options.temperature,
             timestamp: Date.now(),
         });
+        // ===== EARLY MULTIMODAL DETECTION =====
+        const hasFileInput = !!options.input?.files?.length || !!options.input?.videoFiles?.length;
+        if (hasFileInput) {
+            // ===== VIDEO ANALYSIS DETECTION =====
+            // Check if video frames are present and handle with fake streaming
+            const messages = await this.buildMessagesForStream(options);
+            if (hasVideoFrames(messages)) {
+                logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
+                    provider: this.providerName,
+                    model: this.modelName,
+                });
+                return await this.executeFakeStreaming(options, analysisSchema);
+            }
+        }
         // 🔧 CRITICAL: Image generation models don't support real streaming
         // Force fake streaming for image models to ensure image output is yielded
         const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));

package/dist/lib/core/modules/GenerationHandler.js

@@ -49,8 +49,12 @@ export class GenerationHandler {
             model,
             messages,
             ...(shouldUseTools && Object.keys(tools).length > 0 && { tools }),
-            maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
-            ...(shouldUseTools && { toolChoice: "auto" }),
+            maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
+            ...(shouldUseTools &&
+                options.toolChoice && { toolChoice: options.toolChoice }),
+            ...(options.prepareStep && {
+                experimental_prepareStep: options.prepareStep,
+            }),
             temperature: options.temperature,
             maxTokens: options.maxTokens,
             abortSignal: options.abortSignal,

package/dist/lib/neurolink.js

@@ -1570,6 +1570,9 @@ Current user's request: ${currentInput}`;
                 disableTools: options.disableTools,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
+                maxSteps: options.maxSteps,
+                toolChoice: options.toolChoice,
+                prepareStep: options.prepareStep,
                 enableAnalytics: options.enableAnalytics,
                 enableEvaluation: options.enableEvaluation,
                 context: options.context,

package/dist/lib/types/generateTypes.d.ts

@@ -1,4 +1,4 @@
-import type { Schema, Tool } from "ai";
+import type { Schema, Tool, ToolChoice, StepResult, LanguageModel } from "ai";
 import type { AIProviderName } from "../constants/enums.js";
 import type { RAGConfig } from "../rag/types.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
@@ -248,6 +248,55 @@ export type GenerateOptions = {
      * Default: false (backward compatible — tool schemas are injected into system prompt).
      */
     skipToolPromptInjection?: boolean;
+    /** Maximum number of tool execution steps (default: 200) */
+    maxSteps?: number;
+    /**
+     * Tool choice configuration for the generation.
+     * Controls whether and which tools the model must call.
+     *
+     * - `"auto"` (default): the model can choose whether and which tools to call
+     * - `"none"`: no tool calls allowed
+     * - `"required"`: the model must call at least one tool
+     * - `{ type: "tool", toolName: string }`: the model must call the specified tool
+     *
+     * Note: When used without `prepareStep`, this applies to **every step** in the
+     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
+     * will cause infinite tool calls until `maxSteps` is exhausted.
+     */
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * Optional callback that runs before each step in a multi-step generation.
+     * Allows dynamically changing `toolChoice` and available tools per step.
+     *
+     * This is the recommended way to enforce specific tool calls on certain steps
+     * while allowing the model freedom on others.
+     *
+     * Maps to Vercel AI SDK's `experimental_prepareStep`.
+     *
+     * @example Force a specific tool on step 0, then switch to auto:
+     * ```typescript
+     * prepareStep: ({ stepNumber, steps }) => {
+     *   if (stepNumber === 0) {
+     *     return {
+     *       toolChoice: { type: 'tool', toolName: 'myTool' }
+     *     };
+     *   }
+     *   return { toolChoice: 'auto' };
+     * }
+     * ```
+     *
+     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
+     */
+    prepareStep?: (options: {
+        steps: StepResult<Record<string, Tool>>[];
+        stepNumber: number;
+        maxSteps: number;
+        model: LanguageModel;
+    }) => PromiseLike<{
+        model?: LanguageModel;
+        toolChoice?: ToolChoice<Record<string, Tool>>;
+        experimental_activeTools?: string[];
+    } | undefined>;
     enableEvaluation?: boolean;
     enableAnalytics?: boolean;
     context?: StandardRecord;
@@ -569,6 +618,53 @@ export type TextGenerationOptions = {
     toolFilter?: string[];
     /** Exclude these tools by name (blacklist). Applied after toolFilter. */
     excludeTools?: string[];
+    /**
+     * Tool choice configuration for the generation.
+     * Controls whether and which tools the model must call.
+     *
+     * - `"auto"` (default): the model can choose whether and which tools to call
+     * - `"none"`: no tool calls allowed
+     * - `"required"`: the model must call at least one tool
+     * - `{ type: "tool", toolName: string }`: the model must call the specified tool
+     *
+     * Note: When used without `prepareStep`, this applies to **every step** in the
+     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
+     * will cause infinite tool calls until `maxSteps` is exhausted.
+     */
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * Optional callback that runs before each step in a multi-step generation.
+     * Allows dynamically changing `toolChoice` and available tools per step.
+     *
+     * This is the recommended way to enforce specific tool calls on certain steps
+     * while allowing the model freedom on others.
+     *
+     * Maps to Vercel AI SDK's `experimental_prepareStep`.
+     *
+     * @example Force a specific tool on step 0, then switch to auto:
+     * ```typescript
+     * prepareStep: ({ stepNumber, steps }) => {
+     *   if (stepNumber === 0) {
+     *     return {
+     *       toolChoice: { type: 'tool', toolName: 'myTool' }
+     *     };
+     *   }
+     *   return { toolChoice: 'auto' };
+     * }
+     * ```
+     *
+     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
+     */
+    prepareStep?: (options: {
+        steps: StepResult<Record<string, Tool>>[];
+        stepNumber: number;
+        maxSteps: number;
+        model: LanguageModel;
+    }) => PromiseLike<{
+        model?: LanguageModel;
+        toolChoice?: ToolChoice<Record<string, Tool>>;
+        experimental_activeTools?: string[];
+    } | undefined>;
     /**
      * Text-to-Speech (TTS) configuration
      *

package/dist/lib/utils/videoAnalysisProcessor.d.ts

@@ -9,9 +9,10 @@ import type { CoreMessage } from "ai";
 import { AIProviderName } from "../constants/enums.js";
 /**
  * Check if messages contain video frames (images)
+ * Only checks user messages to match buildContentParts behavior
  *
  * @param messages - Array of CoreMessage objects
- * @returns true if video frames are present
+ * @returns true if video frames are present in user messages
  */
 export declare function hasVideoFrames(messages: CoreMessage[]): boolean;
 /**

package/dist/lib/utils/videoAnalysisProcessor.js

@@ -9,12 +9,17 @@ import { AIProviderName } from "../constants/enums.js";
 import { logger } from "./logger.js";
 /**
  * Check if messages contain video frames (images)
+ * Only checks user messages to match buildContentParts behavior
  *
  * @param messages - Array of CoreMessage objects
- * @returns true if video frames are present
+ * @returns true if video frames are present in user messages
  */
 export function hasVideoFrames(messages) {
     return messages.some((msg) => {
+        // Only check user messages to match buildContentParts behavior
+        if (msg.role !== "user") {
+            return false;
+        }
         if (Array.isArray(msg.content)) {
             return msg.content.some((part) => typeof part === "object" &&
                 part !== null &&
@@ -42,7 +47,7 @@ export async function executeVideoAnalysis(messages, options) {
             options.providerName === AIProviderName.VERTEX
             ? AIProviderName.VERTEX
             : AIProviderName.AUTO;
-    const videoAnalysisText = await analyzeVideo(messages[0], {
+    const videoAnalysisText = await analyzeVideo(messages, {
         provider: provider,
         project: options.region
             ? undefined

package/dist/neurolink.js

@@ -1570,6 +1570,9 @@ Current user's request: ${currentInput}`;
                 disableTools: options.disableTools,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
+                maxSteps: options.maxSteps,
+                toolChoice: options.toolChoice,
+                prepareStep: options.prepareStep,
                 enableAnalytics: options.enableAnalytics,
                 enableEvaluation: options.enableEvaluation,
                 context: options.context,

package/dist/types/generateTypes.d.ts

@@ -1,4 +1,4 @@
-import type { Schema, Tool } from "ai";
+import type { Schema, Tool, ToolChoice, StepResult, LanguageModel } from "ai";
 import type { AIProviderName } from "../constants/enums.js";
 import type { RAGConfig } from "../rag/types.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
@@ -248,6 +248,55 @@ export type GenerateOptions = {
      * Default: false (backward compatible — tool schemas are injected into system prompt).
      */
     skipToolPromptInjection?: boolean;
+    /** Maximum number of tool execution steps (default: 200) */
+    maxSteps?: number;
+    /**
+     * Tool choice configuration for the generation.
+     * Controls whether and which tools the model must call.
+     *
+     * - `"auto"` (default): the model can choose whether and which tools to call
+     * - `"none"`: no tool calls allowed
+     * - `"required"`: the model must call at least one tool
+     * - `{ type: "tool", toolName: string }`: the model must call the specified tool
+     *
+     * Note: When used without `prepareStep`, this applies to **every step** in the
+     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
+     * will cause infinite tool calls until `maxSteps` is exhausted.
+     */
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * Optional callback that runs before each step in a multi-step generation.
+     * Allows dynamically changing `toolChoice` and available tools per step.
+     *
+     * This is the recommended way to enforce specific tool calls on certain steps
+     * while allowing the model freedom on others.
+     *
+     * Maps to Vercel AI SDK's `experimental_prepareStep`.
+     *
+     * @example Force a specific tool on step 0, then switch to auto:
+     * ```typescript
+     * prepareStep: ({ stepNumber, steps }) => {
+     *   if (stepNumber === 0) {
+     *     return {
+     *       toolChoice: { type: 'tool', toolName: 'myTool' }
+     *     };
+     *   }
+     *   return { toolChoice: 'auto' };
+     * }
+     * ```
+     *
+     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
+     */
+    prepareStep?: (options: {
+        steps: StepResult<Record<string, Tool>>[];
+        stepNumber: number;
+        maxSteps: number;
+        model: LanguageModel;
+    }) => PromiseLike<{
+        model?: LanguageModel;
+        toolChoice?: ToolChoice<Record<string, Tool>>;
+        experimental_activeTools?: string[];
+    } | undefined>;
     enableEvaluation?: boolean;
     enableAnalytics?: boolean;
     context?: StandardRecord;
@@ -569,6 +618,53 @@ export type TextGenerationOptions = {
     toolFilter?: string[];
     /** Exclude these tools by name (blacklist). Applied after toolFilter. */
     excludeTools?: string[];
+    /**
+     * Tool choice configuration for the generation.
+     * Controls whether and which tools the model must call.
+     *
+     * - `"auto"` (default): the model can choose whether and which tools to call
+     * - `"none"`: no tool calls allowed
+     * - `"required"`: the model must call at least one tool
+     * - `{ type: "tool", toolName: string }`: the model must call the specified tool
+     *
+     * Note: When used without `prepareStep`, this applies to **every step** in the
+     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
+     * will cause infinite tool calls until `maxSteps` is exhausted.
+     */
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * Optional callback that runs before each step in a multi-step generation.
+     * Allows dynamically changing `toolChoice` and available tools per step.
+     *
+     * This is the recommended way to enforce specific tool calls on certain steps
+     * while allowing the model freedom on others.
+     *
+     * Maps to Vercel AI SDK's `experimental_prepareStep`.
+     *
+     * @example Force a specific tool on step 0, then switch to auto:
+     * ```typescript
+     * prepareStep: ({ stepNumber, steps }) => {
+     *   if (stepNumber === 0) {
+     *     return {
+     *       toolChoice: { type: 'tool', toolName: 'myTool' }
+     *     };
+     *   }
+     *   return { toolChoice: 'auto' };
+     * }
+     * ```
+     *
+     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
+     */
+    prepareStep?: (options: {
+        steps: StepResult<Record<string, Tool>>[];
+        stepNumber: number;
+        maxSteps: number;
+        model: LanguageModel;
+    }) => PromiseLike<{
+        model?: LanguageModel;
+        toolChoice?: ToolChoice<Record<string, Tool>>;
+        experimental_activeTools?: string[];
+    } | undefined>;
     /**
      * Text-to-Speech (TTS) configuration
      *

package/dist/utils/videoAnalysisProcessor.d.ts

@@ -9,9 +9,10 @@ import type { CoreMessage } from "ai";
 import { AIProviderName } from "../constants/enums.js";
 /**
  * Check if messages contain video frames (images)
+ * Only checks user messages to match buildContentParts behavior
  *
  * @param messages - Array of CoreMessage objects
- * @returns true if video frames are present
+ * @returns true if video frames are present in user messages
  */
 export declare function hasVideoFrames(messages: CoreMessage[]): boolean;
 /**

package/dist/utils/videoAnalysisProcessor.js

@@ -9,12 +9,17 @@ import { AIProviderName } from "../constants/enums.js";
 import { logger } from "./logger.js";
 /**
  * Check if messages contain video frames (images)
+ * Only checks user messages to match buildContentParts behavior
  *
  * @param messages - Array of CoreMessage objects
- * @returns true if video frames are present
+ * @returns true if video frames are present in user messages
  */
 export function hasVideoFrames(messages) {
     return messages.some((msg) => {
+        // Only check user messages to match buildContentParts behavior
+        if (msg.role !== "user") {
+            return false;
+        }
         if (Array.isArray(msg.content)) {
             return msg.content.some((part) => typeof part === "object" &&
                 part !== null &&
@@ -42,7 +47,7 @@ export async function executeVideoAnalysis(messages, options) {
             options.providerName === AIProviderName.VERTEX
             ? AIProviderName.VERTEX
             : AIProviderName.AUTO;
-    const videoAnalysisText = await analyzeVideo(messages[0], {
+    const videoAnalysisText = await analyzeVideo(messages, {
         provider: provider,
         project: options.region
             ? undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.9.0",
+  "version": "9.10.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",