@juspay/neurolink 7.53.3 → 7.53.5

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [7.53.5](https://github.com/juspay/neurolink/compare/v7.53.4...v7.53.5) (2025-11-06)
+
+## [7.53.4](https://github.com/juspay/neurolink/compare/v7.53.3...v7.53.4) (2025-11-05)
+
+### Bug Fixes
+
+- **(sdk):** structured object response in generate function ([f16d597](https://github.com/juspay/neurolink/commit/f16d597f8e9a64f24a7a6ad5344c93add524c23d))
+
 ## [7.53.3](https://github.com/juspay/neurolink/compare/v7.53.2...v7.53.3) (2025-11-03)
 
 ## [7.53.2](https://github.com/juspay/neurolink/compare/v7.53.1...v7.53.2) (2025-10-28)

package/README.md

@@ -25,6 +25,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 ## What's New (Q4 2025)
 
+- **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)
 - **LiteLLM Integration** – Access 100+ AI models from all major providers through unified interface. → [Setup Guide](docs/LITELLM-INTEGRATION.md)

package/dist/cli/commands/config.d.ts

@@ -18,9 +18,9 @@ declare const ConfigSchema: z.ZodObject<{
             apiKey?: string | undefined;
             baseURL?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
             baseURL?: string | undefined;
+            model?: string | undefined;
         }>>;
         bedrock: z.ZodOptional<z.ZodObject<{
             region: z.ZodOptional<z.ZodString>;
@@ -73,8 +73,8 @@ declare const ConfigSchema: z.ZodObject<{
             model: string;
             apiKey?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         }>>;
         azure: z.ZodOptional<z.ZodObject<{
             apiKey: z.ZodOptional<z.ZodString>;
@@ -87,8 +87,8 @@ declare const ConfigSchema: z.ZodObject<{
             endpoint?: string | undefined;
             deploymentId?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
             endpoint?: string | undefined;
             deploymentId?: string | undefined;
         }>>;
@@ -99,8 +99,8 @@ declare const ConfigSchema: z.ZodObject<{
             model: string;
             apiKey?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         }>>;
         huggingface: z.ZodOptional<z.ZodObject<{
             apiKey: z.ZodOptional<z.ZodString>;
@@ -109,8 +109,8 @@ declare const ConfigSchema: z.ZodObject<{
             model: string;
             apiKey?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         }>>;
         ollama: z.ZodOptional<z.ZodObject<{
             baseUrl: z.ZodDefault<z.ZodString>;
@@ -132,8 +132,8 @@ declare const ConfigSchema: z.ZodObject<{
             model: string;
             apiKey?: string | undefined;
         }, {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         bedrock?: {
@@ -193,9 +193,9 @@ declare const ConfigSchema: z.ZodObject<{
             sessionToken?: string | undefined;
         } | undefined;
         openai?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
             baseURL?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         vertex?: {
             model?: string | undefined;
@@ -207,22 +207,22 @@ declare const ConfigSchema: z.ZodObject<{
             privateKey?: string | undefined;
         } | undefined;
         anthropic?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         azure?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
             endpoint?: string | undefined;
             deploymentId?: string | undefined;
         } | undefined;
         "google-ai"?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         huggingface?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         ollama?: {
             timeout?: number | undefined;
@@ -230,8 +230,8 @@ declare const ConfigSchema: z.ZodObject<{
             baseUrl?: string | undefined;
         } | undefined;
         mistral?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
     }>>;
     profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -562,9 +562,9 @@ declare const ConfigSchema: z.ZodObject<{
             sessionToken?: string | undefined;
         } | undefined;
         openai?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
             baseURL?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         vertex?: {
             model?: string | undefined;
@@ -576,22 +576,22 @@ declare const ConfigSchema: z.ZodObject<{
             privateKey?: string | undefined;
         } | undefined;
         anthropic?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         azure?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
             endpoint?: string | undefined;
             deploymentId?: string | undefined;
         } | undefined;
         "google-ai"?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         huggingface?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
         ollama?: {
             timeout?: number | undefined;
@@ -599,8 +599,8 @@ declare const ConfigSchema: z.ZodObject<{
             baseUrl?: string | undefined;
         } | undefined;
         mistral?: {
-            model?: string | undefined;
             apiKey?: string | undefined;
+            model?: string | undefined;
         } | undefined;
     } | undefined;
     defaultProvider?: "bedrock" | "openai" | "vertex" | "anthropic" | "azure" | "google-ai" | "huggingface" | "ollama" | "mistral" | "auto" | undefined;

package/dist/cli/loop/optionsSchema.js

@@ -24,6 +24,11 @@ export const textGenerationOptionsSchema = {
         type: "number",
         description: "The maximum number of tokens to generate.",
     },
+    output: {
+        type: "string",
+        description: "AI response format - specify just the format value (e.g., 'json', 'structured'). Note: This is automatically transformed to { format: value } for the API.",
+        allowedValues: ["text", "json", "structured", "none"],
+    },
     systemPrompt: {
         type: "string",
         description: "The system prompt to guide the AI's behavior.",

package/dist/core/baseProvider.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { generateText, tool as createAISDKTool, jsonSchema } from "ai";
+import { generateText, tool as createAISDKTool, jsonSchema, Output } from "ai";
 import { AIProviderName } from "../constants/enums.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { logger } from "../utils/logger.js";
@@ -301,6 +301,9 @@ export class BaseProvider {
      */
     async executeGeneration(model, messages, tools, options) {
         const shouldUseTools = !options.disableTools && this.supportsTools();
+        const useStructuredOutput = !!options.schema &&
+            (options.output?.format === "json" ||
+                options.output?.format === "structured");
         return await generateText({
             model,
             messages,
@@ -309,6 +312,10 @@ export class BaseProvider {
             toolChoice: shouldUseTools ? "auto" : "none",
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            ...(useStructuredOutput &&
+                options.schema && {
+                experimental_output: Output.object({ schema: options.schema }),
+            }),
             experimental_telemetry: this.getStreamTelemetryConfig(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
                 logger.info("Tool execution completed", { toolResults, toolCalls });
@@ -439,9 +446,17 @@ export class BaseProvider {
     /**
      * Format the enhanced result
      */
-    formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions) {
+    formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options) {
+        // Only access experimental_output if we set a schema
+        // (accessing it when not set throws an error)
+        const useStructuredOutput = !!options.schema &&
+            (options.output?.format === "json" ||
+                options.output?.format === "structured");
+        const content = useStructuredOutput
+            ? JSON.stringify(generateResult.experimental_output)
+            : generateResult.text;
         return {
-            content: generateResult.text,
+            content,
             usage: {
                 input: generateResult.usage?.promptTokens || 0,
                 output: generateResult.usage?.completionTokens || 0,
@@ -579,7 +594,7 @@ export class BaseProvider {
             const responseTime = Date.now() - startTime;
             await this.recordPerformanceMetrics(generateResult.usage, responseTime);
             const { toolsUsed, toolExecutions } = this.extractToolInformation(generateResult);
-            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions);
+            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
             return await this.enhanceResult(enhancedResult, options, startTime);
         }
         catch (error) {

package/dist/index.d.ts

@@ -86,7 +86,7 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
 export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
 export type { McpMetadata, DiscoveredMcp } from "./types/mcpTypes.js";
 export type { ExecutionContext, ToolInfo, ToolExecutionResult, } from "./types/tools.js";
-export type { LogLevel } from "./utils/logger.js";
+export type { LogLevel } from "./types/utilities.js";
 export declare function initializeTelemetry(): Promise<boolean>;
 export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;

package/dist/lib/agent/directTools.d.ts

@@ -352,13 +352,13 @@ export declare const directAgentTools: {
         column: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         maxRows: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
+        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
         maxRows: number;
         filePath: string;
-        operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
         column: string;
     }, {
-        filePath: string;
         operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+        filePath: string;
         maxRows?: number | undefined;
         column?: string | undefined;
     }>, {
@@ -379,9 +379,9 @@ export declare const directAgentTools: {
         column: string;
     }> & {
         execute: (args: {
+            operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
             maxRows: number;
             filePath: string;
-            operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
             column: string;
         }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
             success: boolean;

package/dist/lib/core/baseProvider.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { generateText, tool as createAISDKTool, jsonSchema } from "ai";
+import { generateText, tool as createAISDKTool, jsonSchema, Output } from "ai";
 import { AIProviderName } from "../constants/enums.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { logger } from "../utils/logger.js";
@@ -301,6 +301,9 @@ export class BaseProvider {
      */
     async executeGeneration(model, messages, tools, options) {
         const shouldUseTools = !options.disableTools && this.supportsTools();
+        const useStructuredOutput = !!options.schema &&
+            (options.output?.format === "json" ||
+                options.output?.format === "structured");
         return await generateText({
             model,
             messages,
@@ -309,6 +312,10 @@ export class BaseProvider {
             toolChoice: shouldUseTools ? "auto" : "none",
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            ...(useStructuredOutput &&
+                options.schema && {
+                experimental_output: Output.object({ schema: options.schema }),
+            }),
             experimental_telemetry: this.getStreamTelemetryConfig(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
                 logger.info("Tool execution completed", { toolResults, toolCalls });
@@ -439,9 +446,17 @@ export class BaseProvider {
     /**
      * Format the enhanced result
      */
-    formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions) {
+    formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options) {
+        // Only access experimental_output if we set a schema
+        // (accessing it when not set throws an error)
+        const useStructuredOutput = !!options.schema &&
+            (options.output?.format === "json" ||
+                options.output?.format === "structured");
+        const content = useStructuredOutput
+            ? JSON.stringify(generateResult.experimental_output)
+            : generateResult.text;
         return {
-            content: generateResult.text,
+            content,
             usage: {
                 input: generateResult.usage?.promptTokens || 0,
                 output: generateResult.usage?.completionTokens || 0,
@@ -579,7 +594,7 @@ export class BaseProvider {
             const responseTime = Date.now() - startTime;
             await this.recordPerformanceMetrics(generateResult.usage, responseTime);
             const { toolsUsed, toolExecutions } = this.extractToolInformation(generateResult);
-            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions);
+            const enhancedResult = this.formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options);
             return await this.enhanceResult(enhancedResult, options, startTime);
         }
         catch (error) {

package/dist/lib/index.d.ts

@@ -86,7 +86,7 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
 export { initializeMCPEcosystem, listMCPs, executeMCP, getMCPStats, mcpLogger, } from "./mcp/index.js";
 export type { McpMetadata, DiscoveredMcp } from "./types/mcpTypes.js";
 export type { ExecutionContext, ToolInfo, ToolExecutionResult, } from "./types/tools.js";
-export type { LogLevel } from "./utils/logger.js";
+export type { LogLevel } from "./types/utilities.js";
 export declare function initializeTelemetry(): Promise<boolean>;
 export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;

package/dist/lib/neurolink.js

@@ -1221,6 +1221,8 @@ export class NeuroLink {
             temperature: options.temperature,
             maxTokens: options.maxTokens,
             systemPrompt: options.systemPrompt,
+            schema: options.schema,
+            output: options.output,
             disableTools: options.disableTools,
             enableAnalytics: options.enableAnalytics,
             enableEvaluation: options.enableEvaluation,

package/dist/lib/providers/sagemaker/language-model.d.ts

@@ -131,7 +131,7 @@ export declare class SageMakerLanguageModel implements LanguageModelV1 {
         provider: string;
         specificationVersion: string;
         endpointName: string;
-        modelType: "custom" | "huggingface" | "mistral" | "claude" | "llama" | "jumpstart" | undefined;
+        modelType: "huggingface" | "mistral" | "llama" | "claude" | "jumpstart" | "custom" | undefined;
         region: string;
     };
     /**
@@ -178,7 +178,7 @@ export declare class SageMakerLanguageModel implements LanguageModelV1 {
         provider: string;
         specificationVersion: string;
         endpointName: string;
-        modelType: "custom" | "huggingface" | "mistral" | "claude" | "llama" | "jumpstart" | undefined;
+        modelType: "huggingface" | "mistral" | "llama" | "claude" | "jumpstart" | "custom" | undefined;
         region: string;
     };
 }

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

@@ -120,11 +120,11 @@ export type NeuroLinkEvents = {
  * TypeScript utility for typed EventEmitter
  * Flexible interface to support both typed and legacy event patterns
  */
-export interface TypedEventEmitter<TEvents extends Record<string, unknown>> {
-    on<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): this;
+export type TypedEventEmitter<TEvents extends Record<string, unknown>> = {
+    on<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
     emit<K extends keyof TEvents>(event: K, ...args: unknown[]): boolean;
-    off<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): this;
-    removeAllListeners<K extends keyof TEvents>(event?: K): this;
+    off<K extends keyof TEvents>(event: K, listener: (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    removeAllListeners<K extends keyof TEvents>(event?: K): TypedEventEmitter<TEvents>;
     listenerCount<K extends keyof TEvents>(event: K): number;
     listeners<K extends keyof TEvents>(event: K): Array<(...args: unknown[]) => void>;
-}
+};

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

@@ -157,6 +157,9 @@ export type TextGenerationOptions = {
     maxTokens?: number;
     systemPrompt?: string;
     schema?: ZodUnknownSchema | Schema<unknown>;
+    output?: {
+        format?: "text" | "structured" | "json";
+    };
     tools?: Record<string, Tool>;
     timeout?: number | string;
     disableTools?: boolean;

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

@@ -5,6 +5,7 @@
 import { z } from "zod";
 import type { JsonValue } from "./common.js";
 import { AIProviderName } from "../constants/enums.js";
+import type { TaskType } from "./taskClassificationTypes.js";
 /**
  * Model performance tier definition
  */
@@ -87,10 +88,10 @@ export declare const ModelConfigSchema: z.ZodObject<{
     contextWindow: z.ZodNumber;
     releaseDate: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    id: string;
-    displayName: string;
     capabilities: string[];
+    id: string;
     deprecated: boolean;
+    displayName: string;
     pricing: {
         input: number;
         output: number;
@@ -98,10 +99,10 @@ export declare const ModelConfigSchema: z.ZodObject<{
     contextWindow: number;
     releaseDate: string;
 }, {
-    id: string;
-    displayName: string;
     capabilities: string[];
+    id: string;
     deprecated: boolean;
+    displayName: string;
     pricing: {
         input: number;
         output: number;
@@ -133,10 +134,10 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: z.ZodNumber;
         releaseDate: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        id: string;
-        displayName: string;
         capabilities: string[];
+        id: string;
         deprecated: boolean;
+        displayName: string;
         pricing: {
             input: number;
             output: number;
@@ -144,10 +145,10 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }, {
-        id: string;
-        displayName: string;
         capabilities: string[];
+        id: string;
         deprecated: boolean;
+        displayName: string;
         pricing: {
             input: number;
             output: number;
@@ -159,11 +160,12 @@ export declare const ModelRegistrySchema: z.ZodObject<{
     defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
-        id: string;
-        displayName: string;
         capabilities: string[];
+        id: string;
         deprecated: boolean;
+        displayName: string;
         pricing: {
             input: number;
             output: number;
@@ -171,16 +173,16 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }, {
     version: string;
+    lastUpdated: string;
     models: Record<string, Record<string, {
-        id: string;
-        displayName: string;
         capabilities: string[];
+        id: string;
         deprecated: boolean;
+        displayName: string;
         pricing: {
             input: number;
             output: number;
@@ -188,7 +190,6 @@ export declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
-    lastUpdated: string;
     aliases?: Record<string, string> | undefined;
     defaults?: Record<string, string> | undefined;
 }>;
@@ -328,3 +329,19 @@ export type ModelComparison = {
         };
     };
 };
+export type ModelRoute = {
+    provider: string;
+    model: string;
+    reasoning: string;
+    confidence: number;
+};
+export type ModelRoutingOptions = {
+    /** Override the task classification */
+    forceTaskType?: TaskType;
+    /** Require specific performance characteristics */
+    requireFast?: boolean;
+    /** Require specific capability (reasoning, creativity, etc.) */
+    requireCapability?: string;
+    /** Fallback strategy if primary choice fails */
+    fallbackStrategy?: "fast" | "reasoning" | "auto";
+};

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

@@ -4,7 +4,8 @@
  */
 import { z } from "zod";
 import type { ErrorInfo, JsonObject, JsonValue, Result, UnknownRecord } from "./common.js";
-import type { StandardRecord, ZodUnknownSchema } from "./typeAliases.js";
+import type { StandardRecord, StringArray, ZodUnknownSchema } from "./typeAliases.js";
+import type { ValidationError } from "../utils/parameterValidation.js";
 /**
  * Commonly used Zod schema type aliases for cleaner type declarations
  */
@@ -336,6 +337,20 @@ export type ToolCallResult = {
     result: ToolResult;
     formattedForAI: string;
 };
+/**
+ * Result of a validation operation
+ * Contains validation status, errors, warnings, and suggestions for improvement
+ */
+export type EnhancedValidationResult = {
+    /** Whether the validation passed without errors */
+    isValid: boolean;
+    /** Array of validation errors that must be fixed */
+    errors: ValidationError[];
+    /** Array of warning messages that should be addressed */
+    warnings: string[];
+    /** Array of suggestions to improve the validated object */
+    suggestions: StringArray;
+};
 /**
  * Type guard for tool result
  */