@juspay/neurolink 9.9.0 → 9.10.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.9.0",
+  "version": "9.10.0",
   "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",