@juspay/neurolink 7.14.2 → 7.14.4

package/dist/core/baseProvider.js

@@ -1,11 +1,13 @@
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
-import { SYSTEM_LIMITS, DEFAULT_MAX_STEPS } from "../core/constants.js";
+import { DEFAULT_MAX_STEPS, STEP_LIMITS } from "../core/constants.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { getSafeMaxTokens } from "../utils/tokenLimits.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
+import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
+import { validateStreamOptions as validateStreamOpts, validateTextGenerationOptions, ValidationError, createValidationSummary, } from "../utils/parameterValidation.js";
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -141,8 +143,10 @@ export class BaseProvider {
      * Text generation method - implements AIProvider interface
      * Tools are always available unless explicitly disabled
      */
-    async generate(optionsOrPrompt, analysisSchema) {
+    async generate(optionsOrPrompt, _analysisSchema) {
         const options = this.normalizeTextOptions(optionsOrPrompt);
+        // Validate options before proceeding
+        this.validateOptions(options);
         const startTime = Date.now();
         try {
             // Import generateText dynamically to avoid circular dependencies
@@ -157,9 +161,12 @@ export class BaseProvider {
                 }
                 : {};
             logger.debug(`[BaseProvider.generate] Tools for ${this.providerName}:`, {
-                directTools: Object.keys(baseTools),
-                externalTools: Object.keys(options.tools || {}),
-                totalTools: Object.keys(tools),
+                directTools: getKeyCount(baseTools),
+                directToolNames: getKeysAsString(baseTools),
+                externalTools: getKeyCount(options.tools || {}),
+                externalToolNames: getKeysAsString(options.tools || {}),
+                totalTools: getKeyCount(tools),
+                totalToolNames: getKeysAsString(tools),
             });
             // EVERY provider uses Vercel AI SDK - no exceptions
             const model = await this.getAISDKModel(); // This method is now REQUIRED
@@ -292,12 +299,15 @@ export class BaseProvider {
                 toolResults: result.toolResults,
                 toolsUsed: uniqueToolsUsed,
                 toolExecutions, // ✅ Add extracted tool executions
-                availableTools: Object.keys(tools).map((name) => ({
-                    name,
-                    description: tools[name].description || "No description available",
-                    parameters: tools[name].parameters || {},
-                    server: tools[name].serverId || "direct",
-                })),
+                availableTools: Object.keys(tools).map((name) => {
+                    const tool = tools[name];
+                    return {
+                        name,
+                        description: tool.description || "No description available",
+                        parameters: tool.parameters || {},
+                        server: tool.serverId || "direct",
+                    };
+                }),
             };
             // Enhanced result with analytics and evaluation
             return await this.enhanceResult(enhancedResult, options, startTime);
@@ -313,6 +323,40 @@ export class BaseProvider {
     async gen(optionsOrPrompt, analysisSchema) {
         return this.generate(optionsOrPrompt, analysisSchema);
     }
+    /**
+     * BACKWARD COMPATIBILITY: Legacy generateText method
+     * Converts EnhancedGenerateResult to TextGenerationResult format
+     * Ensures existing scripts using createAIProvider().generateText() continue to work
+     */
+    async generateText(options) {
+        // Validate required parameters for backward compatibility
+        if (!options.prompt ||
+            typeof options.prompt !== "string" ||
+            options.prompt.trim() === "") {
+            throw new Error("GenerateText options must include prompt as a non-empty string");
+        }
+        // Call the main generate method
+        const result = await this.generate(options);
+        if (!result) {
+            throw new Error("Generation failed: No result returned");
+        }
+        // Convert EnhancedGenerateResult to TextGenerationResult format
+        return {
+            content: result.content || "",
+            provider: result.provider || this.providerName,
+            model: result.model || this.modelName,
+            usage: result.usage || {
+                promptTokens: 0,
+                completionTokens: 0,
+                totalTokens: 0,
+            },
+            responseTime: 0, // BaseProvider doesn't track response time directly
+            toolsUsed: result.toolsUsed || [],
+            enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
+            analytics: result.analytics,
+            evaluation: result.evaluation,
+        };
+    }
     // ===================
     // TOOL MANAGEMENT
     // ===================
@@ -327,9 +371,9 @@ export class BaseProvider {
         logger.debug(`[BaseProvider] getAllTools called for ${this.providerName}`, {
             neurolinkAvailable: !!this.neurolink,
             neurolinkType: typeof this.neurolink,
-            directToolsCount: Object.keys(this.directTools).length,
+            directToolsCount: getKeyCount(this.directTools),
         });
-        logger.debug(`[BaseProvider] Direct tools: ${Object.keys(this.directTools).join(", ")}`);
+        logger.debug(`[BaseProvider] Direct tools: ${getKeysAsString(this.directTools)}`);
         // Add custom tools from setupToolExecutor if available
         if (this.customTools && this.customTools.size > 0) {
             logger.debug(`[BaseProvider] Loading ${this.customTools.size} custom tools from setupToolExecutor`);
@@ -349,14 +393,14 @@ export class BaseProvider {
                         tools[toolName] = createAISDKTool({
                             description: typedToolDef.description || `Custom tool ${toolName}`,
                             parameters: z.object({}), // Use empty schema for custom tools
-                            execute: async (args) => {
-                                logger.debug(`[BaseProvider] Executing custom tool: ${toolName}`, { args });
+                            execute: async (params) => {
+                                logger.debug(`[BaseProvider] Executing custom tool: ${toolName}`, { params });
                                 // Use the tool executor if available (from setupToolExecutor)
                                 if (this.toolExecutor) {
-                                    return await this.toolExecutor(toolName, args);
+                                    return await this.toolExecutor(toolName, params);
                                 }
                                 else {
-                                    return await typedToolDef.execute(args);
+                                    return await typedToolDef.execute(params);
                                 }
                             },
                         });
@@ -388,7 +432,7 @@ export class BaseProvider {
                 logger.debug(`[BaseProvider] Loading custom tools from SDK, found ${inMemoryServers.size} servers`);
                 if (inMemoryServers && inMemoryServers.size > 0) {
                     // Convert in-memory server tools to AI SDK format
-                    for (const [serverId, serverConfig] of inMemoryServers) {
+                    for (const [_serverId, serverConfig] of inMemoryServers) {
                         if (serverConfig && serverConfig.tools) {
                             // Handle tools array from MCPServerInfo
                             const toolEntries = serverConfig.tools.map((tool) => [
@@ -401,13 +445,18 @@ export class BaseProvider {
                                     try {
                                         // Convert to AI SDK tool format
                                         const { tool: createAISDKTool } = await import("ai");
+                                        // Validate optional schemas if present (accept Zod or plain JSON schema objects)
+                                        const isZodSchema = (s) => typeof s === "object" &&
+                                            s !== null &&
+                                            // Most Zod schemas have an internal _def and a parse method
+                                            typeof s.parse === "function";
                                         tools[toolName] = createAISDKTool({
                                             description: toolInfo.description || `Tool ${toolName}`,
-                                            parameters: toolInfo.parameters instanceof z.ZodType
+                                            parameters: isZodSchema(toolInfo.parameters)
                                                 ? toolInfo.parameters
                                                 : z.object({}),
-                                            execute: async (args) => {
-                                                const result = await toolInfo.execute(args);
+                                            execute: async (params) => {
+                                                const result = await toolInfo.execute(params);
                                                 // Handle MCP-style results
                                                 if (result &&
                                                     typeof result === "object" &&
@@ -454,12 +503,12 @@ export class BaseProvider {
                         tools[tool.name] = createAISDKTool({
                             description: tool.description || `External MCP tool ${tool.name}`,
                             parameters: await this.convertMCPSchemaToZod(tool.inputSchema),
-                            execute: async (args) => {
-                                logger.debug(`[BaseProvider] Executing external MCP tool: ${tool.name}`, { args });
+                            execute: async (params) => {
+                                logger.debug(`[BaseProvider] Executing external MCP tool: ${tool.name}`, { params });
                                 // Execute via NeuroLink's direct tool execution
                                 if (this.neurolink &&
                                     typeof this.neurolink.executeExternalMCPTool === "function") {
-                                    return await this.neurolink.executeExternalMCPTool(tool.serverId || "unknown", tool.name, args);
+                                    return await this.neurolink.executeExternalMCPTool(tool.serverId || "unknown", tool.name, params);
                                 }
                                 else {
                                     throw new Error(`Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`);
@@ -497,7 +546,7 @@ export class BaseProvider {
         if (this.mcpTools) {
             Object.assign(tools, this.mcpTools);
         }
-        logger.debug(`[BaseProvider] getAllTools returning tools: ${Object.keys(tools).join(", ")}`);
+        logger.debug(`[BaseProvider] getAllTools returning tools: ${getKeysAsString(tools)}`);
         return tools;
     }
     /**
@@ -522,39 +571,39 @@ export class BaseProvider {
                     switch (prop.type) {
                         case "string":
                             zodType = z.string();
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                             break;
                         case "number":
                         case "integer":
                             zodType = z.number();
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                             break;
                         case "boolean":
                             zodType = z.boolean();
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                             break;
                         case "array":
                             zodType = z.array(z.unknown());
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                             break;
                         case "object":
                             zodType = z.object({});
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                             break;
                         default:
                             // Unknown type, use string as fallback
                             zodType = z.string();
-                            if (prop.description) {
+                            if (prop.description && typeof prop.description === "string") {
                                 zodType = zodType.describe(prop.description);
                             }
                     }
@@ -565,9 +614,7 @@ export class BaseProvider {
                     zodFields[propName] = zodType;
                 }
             }
-            return Object.keys(zodFields).length > 0
-                ? z.object(zodFields)
-                : z.object({});
+            return getKeyCount(zodFields) > 0 ? z.object(zodFields) : z.object({});
         }
         catch (error) {
             logger.warn(`Failed to convert MCP schema to Zod, using empty schema:`, error);
@@ -615,17 +662,22 @@ export class BaseProvider {
      * Validate stream options - consolidates validation from 7/10 providers
      */
     validateStreamOptions(options) {
-        if (!options.input?.text || options.input.text.trim().length === 0) {
-            throw new Error("Input text is required and cannot be empty");
-        }
-        if (options.temperature !== undefined) {
-            if (options.temperature < 0 || options.temperature > 2) {
-                throw new Error("temperature must be between 0 and 2");
-            }
-        }
-        if (options.maxTokens !== undefined) {
-            if (options.maxTokens < 1) {
-                throw new Error("maxTokens must be at least 1");
+        const validation = validateStreamOpts(options);
+        if (!validation.isValid) {
+            const summary = createValidationSummary(validation);
+            throw new ValidationError(`Stream options validation failed: ${summary}`, "options", "VALIDATION_FAILED", validation.suggestions);
+        }
+        // Log warnings if any
+        if (validation.warnings.length > 0) {
+            logger.warn("Stream options validation warnings:", validation.warnings);
+        }
+        // Additional BaseProvider-specific validation
+        if (options.maxSteps !== undefined) {
+            if (options.maxSteps < STEP_LIMITS.min ||
+                options.maxSteps > STEP_LIMITS.max) {
+                throw new ValidationError(`maxSteps must be between ${STEP_LIMITS.min} and ${STEP_LIMITS.max}`, "maxSteps", "OUT_OF_RANGE", [
+                    `Use a value between ${STEP_LIMITS.min} and ${STEP_LIMITS.max} for optimal performance`,
+                ]);
             }
         }
     }
@@ -656,7 +708,7 @@ export class BaseProvider {
     async createStreamAnalytics(result, startTime, options) {
         try {
             const { createAnalytics } = await import("./analytics.js");
-            const analytics = await createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
+            const analytics = createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
                 requestId: `${this.providerName}-stream-${Date.now()}`,
                 streamingMode: true,
                 ...options.context,
@@ -698,57 +750,17 @@ export class BaseProvider {
      * @param functionTag - Function name for logging
      */
     setupToolExecutor(sdk, functionTag) {
-        // Type guard to check for setToolExecutor method
-        function hasSetToolExecutor(obj) {
-            return (typeof obj === "object" &&
-                obj !== null &&
-                typeof obj.setToolExecutor ===
-                    "function");
-        }
-        if (!hasSetToolExecutor(this)) {
-            logger.warn(`[${functionTag}] Provider does not support setToolExecutor - tools will not be executed`, {
-                hasProvider: true,
-                providerType: this.constructor.name,
-                availableCustomTools: sdk.customTools.size,
-            });
-            return;
-        }
         // Store custom tools for use in getAllTools()
         this.customTools = sdk.customTools;
         this.toolExecutor = sdk.executeTool;
         logger.debug(`[${functionTag}] Setting up tool executor for provider`, {
             providerType: this.constructor.name,
             availableCustomTools: sdk.customTools.size,
+            customToolsStored: !!this.customTools,
+            toolExecutorStored: !!this.toolExecutor,
         });
-        // Set up tool executor to handle actual tool calls
-        this.setToolExecutor(async (toolName, params) => {
-            logger.debug(`[${functionTag}] AI provider requesting tool execution: ${toolName}`, {
-                toolName,
-                params,
-                availableCustomTools: sdk.customTools.size,
-                hasRequestedTool: sdk.customTools.has(toolName),
-            });
-            try {
-                // Execute the tool using NeuroLink's executeTool method
-                const result = await sdk.executeTool(toolName, params);
-                logger.debug(`[${functionTag}] Tool execution successful: ${toolName}`, {
-                    toolName,
-                    result: typeof result === "object"
-                        ? JSON.stringify(result).substring(0, 200)
-                        : result,
-                    resultType: typeof result,
-                });
-                return result;
-            }
-            catch (error) {
-                logger.error(`[${functionTag}] Tool execution failed: ${toolName}`, {
-                    toolName,
-                    error: error instanceof Error ? error.message : String(error),
-                    params,
-                });
-                throw error;
-            }
-        });
+        // Note: Tool execution will be handled through getAllTools() -> AI SDK tools
+        // The custom tools are converted to AI SDK format in getAllTools() method
     }
     // ===================
     // TEMPLATE METHODS - COMMON FUNCTIONALITY
@@ -833,43 +845,24 @@ export class BaseProvider {
         return evaluation;
     }
     validateOptions(options) {
-        // 🔧 EDGE CASE: Basic prompt validation
-        if (!options.prompt || options.prompt.trim().length === 0) {
-            throw new Error("Prompt is required and cannot be empty");
-        }
-        // 🔧 EDGE CASE: Handle very large prompts (>1M characters)
-        if (options.prompt.length > SYSTEM_LIMITS.MAX_PROMPT_LENGTH) {
-            throw new Error(`Prompt too large: ${options.prompt.length} characters (max: ${SYSTEM_LIMITS.MAX_PROMPT_LENGTH}). Consider breaking into smaller chunks. Use BaseProvider.chunkPrompt(prompt, maxSize, overlap) static method for chunking.`);
-        }
-        // 🔧 EDGE CASE: Validate token limits
-        if (options.maxTokens && options.maxTokens > 200000) {
-            throw new Error(`Max tokens too high: ${options.maxTokens} (recommended max: 200,000). This may cause timeouts or API errors.`);
-        }
-        if (options.maxTokens && options.maxTokens < 1) {
-            throw new Error("Max tokens must be at least 1");
-        }
-        // 🔧 EDGE CASE: Validate temperature range
-        if (options.temperature !== undefined) {
-            if (options.temperature < 0 || options.temperature > 2) {
-                throw new Error(`Temperature must be between 0 and 2, got: ${options.temperature}`);
-            }
-        }
-        // 🔧 EDGE CASE: Validate timeout values
-        if (options.timeout !== undefined) {
-            const timeoutMs = typeof options.timeout === "string"
-                ? parseInt(options.timeout, 10)
-                : options.timeout;
-            if (isNaN(timeoutMs) || timeoutMs < 1000) {
-                throw new Error(`Timeout must be at least 1000ms (1 second), got: ${options.timeout}`);
-            }
-            if (timeoutMs > SYSTEM_LIMITS.LONG_TIMEOUT_WARNING) {
-                logger.warn(`⚠️ Very long timeout: ${timeoutMs}ms. This may cause the CLI to hang.`);
+        const validation = validateTextGenerationOptions(options);
+        if (!validation.isValid) {
+            const summary = createValidationSummary(validation);
+            throw new ValidationError(`Text generation options validation failed: ${summary}`, "options", "VALIDATION_FAILED", validation.suggestions);
+        }
+        // Log warnings if any
+        if (validation.warnings.length > 0) {
+            logger.warn("Text generation options validation warnings:", validation.warnings);
+        }
+        // Additional BaseProvider-specific validation
+        if (options.maxSteps !== undefined) {
+            if (options.maxSteps < STEP_LIMITS.min ||
+                options.maxSteps > STEP_LIMITS.max) {
+                throw new ValidationError(`maxSteps must be between ${STEP_LIMITS.min} and ${STEP_LIMITS.max}`, "maxSteps", "OUT_OF_RANGE", [
+                    `Use a value between ${STEP_LIMITS.min} and ${STEP_LIMITS.max} for optimal performance`,
+                ]);
             }
         }
-        // 🔧 EDGE CASE: Validate maxSteps for tool execution
-        if (options.maxSteps !== undefined && options.maxSteps > 20) {
-            throw new Error(`Max steps too high: ${options.maxSteps} (recommended max: 20). This may cause long execution times.`);
-        }
     }
     getProviderInfo() {
         return {

package/dist/core/constants.d.ts

@@ -6,6 +6,11 @@ export declare const DEFAULT_MAX_TOKENS = 8192;
 export declare const DEFAULT_TEMPERATURE = 0.7;
 export declare const DEFAULT_TIMEOUT = 30000;
 export declare const DEFAULT_MAX_STEPS = 5;
+export declare const STEP_LIMITS: {
+    min: number;
+    max: number;
+    default: number;
+};
 export declare const DEFAULT_EVALUATION_MAX_TOKENS = 500;
 export declare const DEFAULT_ANALYSIS_MAX_TOKENS = 800;
 export declare const DEFAULT_DOCUMENTATION_MAX_TOKENS = 12000;

package/dist/core/constants.js

@@ -7,6 +7,12 @@ export const DEFAULT_MAX_TOKENS = 8192; // Changed from 10000 to fix Anthropic e
 export const DEFAULT_TEMPERATURE = 0.7;
 export const DEFAULT_TIMEOUT = 30000;
 export const DEFAULT_MAX_STEPS = 5; // Default multi-turn tool execution steps
+// Step execution limits
+export const STEP_LIMITS = {
+    min: 1,
+    max: 20,
+    default: DEFAULT_MAX_STEPS,
+};
 // Specialized Use Case Defaults
 export const DEFAULT_EVALUATION_MAX_TOKENS = 500; // Keep evaluation fast
 export const DEFAULT_ANALYSIS_MAX_TOKENS = 800; // For analysis tools

package/dist/core/dynamicModels.d.ts

@@ -88,8 +88,6 @@ declare const ModelRegistrySchema: z.ZodObject<{
     aliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    version: string;
-    lastUpdated: string;
     models: Record<string, Record<string, {
         capabilities: string[];
         id: string;
@@ -102,11 +100,11 @@ declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
+    version: string;
+    lastUpdated: string;
     defaults?: Record<string, string> | undefined;
     aliases?: Record<string, string> | undefined;
 }, {
-    version: string;
-    lastUpdated: string;
     models: Record<string, Record<string, {
         capabilities: string[];
         id: string;
@@ -119,6 +117,8 @@ declare const ModelRegistrySchema: z.ZodObject<{
         contextWindow: number;
         releaseDate: string;
     }>>;
+    version: string;
+    lastUpdated: string;
     defaults?: Record<string, string> | undefined;
     aliases?: Record<string, string> | undefined;
 }>;

package/dist/core/factory.d.ts

@@ -1,5 +1,6 @@
 import type { AIProvider, AIProviderName, SupportedModelName } from "./types.js";
 import type { UnknownRecord } from "../types/common.js";
+import type { ProviderPairResult } from "../types/typeAliases.js";
 declare const componentIdentifier = "aiProviderFactory";
 /**
  * Factory for creating AI provider instances with centralized configuration
@@ -45,9 +46,6 @@ export declare class AIProviderFactory {
      * @param enableMCP - Optional flag to enable MCP integration (default: true)
      * @returns Object with primary and fallback providers
      */
-    static createProviderWithFallback(primaryProvider: string, fallbackProvider: string, modelName?: string | null, enableMCP?: boolean): Promise<{
-        primary: AIProvider;
-        fallback: AIProvider;
-    }>;
+    static createProviderWithFallback(primaryProvider: string, fallbackProvider: string, modelName?: string | null, enableMCP?: boolean): Promise<ProviderPairResult<AIProvider>>;
 }
 export { componentIdentifier };

package/dist/core/types.d.ts

@@ -1,9 +1,10 @@
-import type { ZodType, ZodTypeDef } from "zod";
-import type { Schema, Tool } from "ai";
+import type { Tool, Schema } from "ai";
+import type { ZodUnknownSchema, ValidationSchema } from "../types/typeAliases.js";
 import type { GenerateResult } from "../types/generateTypes.js";
 import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
 import type { JsonValue } from "../types/common.js";
 import type { ChatMessage } from "../types/conversationTypes.js";
+import type { AnalyticsData } from "./analytics.js";
 export interface TextGenerationResult {
     content: string;
     provider?: string;
@@ -137,7 +138,7 @@ export interface TextGenerationOptions {
     temperature?: number;
     maxTokens?: number;
     systemPrompt?: string;
-    schema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>;
+    schema?: ZodUnknownSchema | Schema<unknown>;
     tools?: Record<string, Tool>;
     timeout?: number | string;
     disableTools?: boolean;
@@ -153,22 +154,7 @@ export interface TextGenerationOptions {
     }>;
     conversationMessages?: ChatMessage[];
 }
-/**
- * Analytics data for usage tracking
- */
-export interface AnalyticsData {
-    provider: string;
-    model: string;
-    tokens: {
-        input: number;
-        output: number;
-        total: number;
-    };
-    cost?: number;
-    responseTime: number;
-    timestamp: string;
-    context?: Record<string, JsonValue>;
-}
+export type { AnalyticsData };
 /**
  * Response quality evaluation scores
  * Comprehensive evaluation interface for response quality assessment
@@ -299,9 +285,9 @@ export type ProgressCallback = (progress: StreamingProgressData) => void;
  * AI Provider interface with flexible parameter support
  */
 export interface AIProvider {
-    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
-    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<EnhancedGenerateResult | null>;
-    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<EnhancedGenerateResult | null>;
+    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
+    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
     setupToolExecutor(sdk: {
         customTools: Map<string, unknown>;
         executeTool: (toolName: string, params: unknown) => Promise<unknown>;

package/dist/index.d.ts

@@ -41,10 +41,7 @@ export declare function createAIProvider(providerName?: string, modelName?: stri
  * const { primary, fallback } = await createAIProviderWithFallback('bedrock', 'vertex');
  * ```
  */
-export declare function createAIProviderWithFallback(primaryProvider?: string, fallbackProvider?: string, modelName?: string): Promise<{
-    primary: import("./core/types.js").AIProvider;
-    fallback: import("./core/types.js").AIProvider;
-}>;
+export declare function createAIProviderWithFallback(primaryProvider?: string, fallbackProvider?: string, modelName?: string): Promise<import("./types/typeAliases.js").ProviderPairResult<import("./core/types.js").AIProvider>>;
 /**
  * Create the best available provider based on configuration
  *

package/dist/lib/core/baseProvider.d.ts

@@ -1,7 +1,6 @@
-import type { ZodType, ZodTypeDef } from "zod";
-import type { Schema } from "ai";
+import type { ValidationSchema } from "../types/typeAliases.js";
 import type { Tool, LanguageModelV1 } from "ai";
-import type { AIProvider, TextGenerationOptions, EnhancedGenerateResult, AnalyticsData, AIProviderName, EvaluationData } from "../core/types.js";
+import type { AIProvider, TextGenerationOptions, TextGenerationResult, EnhancedGenerateResult, AnalyticsData, AIProviderName, EvaluationData } from "../core/types.js";
 import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
 import type { UnknownRecord } from "../types/common.js";
 import type { NeuroLink } from "../neurolink.js";
@@ -31,20 +30,26 @@ export declare abstract class BaseProvider implements AIProvider {
      * Primary streaming method - implements AIProvider interface
      * When tools are involved, falls back to generate() with synthetic streaming
      */
-    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ValidationSchema): Promise<StreamResult>;
     /**
      * Text generation method - implements AIProvider interface
      * Tools are always available unless explicitly disabled
      */
-    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<EnhancedGenerateResult | null>;
+    generate(optionsOrPrompt: TextGenerationOptions | string, _analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
     /**
      * Alias for generate method - implements AIProvider interface
      */
-    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<EnhancedGenerateResult | null>;
+    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
+    /**
+     * BACKWARD COMPATIBILITY: Legacy generateText method
+     * Converts EnhancedGenerateResult to TextGenerationResult format
+     * Ensures existing scripts using createAIProvider().generateText() continue to work
+     */
+    generateText(options: TextGenerationOptions): Promise<TextGenerationResult>;
     /**
      * Provider-specific streaming implementation (only used when tools are disabled)
      */
-    protected abstract executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    protected abstract executeStream(options: StreamOptions, analysisSchema?: ValidationSchema): Promise<StreamResult>;
     /**
      * Get the provider name
      */