@juspay/neurolink 11.13.0 → 11.13.2

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

@@ -1,500 +0,0 @@
-import type { AIProviderName } from "../constants/enums.js";
-import type { EvaluationData } from "../index.js";
-import type { NeuroLink } from "../neurolink.js";
-import type { UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema } from "../types/index.js";
-import { TelemetryHandler } from "./modules/TelemetryHandler.js";
-import type { LanguageModel, ModelMessage, Tool, ToolCallRepairFunction, ToolSet } from "../types/index.js";
-/**
- * Abstract base class for all AI providers
- * Tools are integrated as first-class citizens - always available by default
- */
-export declare abstract class BaseProvider implements AIProvider {
-    protected modelName: string;
-    protected readonly providerName: AIProviderName;
-    protected readonly defaultTimeout: number;
-    protected middlewareOptions?: MiddlewareFactoryOptions;
-    protected readonly directTools: {};
-    protected mcpTools?: Record<string, Tool>;
-    protected customTools?: Map<string, unknown>;
-    protected toolExecutor?: (toolName: string, params: unknown) => Promise<unknown>;
-    protected sessionId?: string;
-    protected userId?: string;
-    protected neurolink?: NeuroLink;
-    setTraceContext(ctx: {
-        traceId: string;
-        parentSpanId: string;
-    } | null): void;
-    private messageBuilder;
-    private streamHandler;
-    private generationHandler;
-    protected telemetryHandler: TelemetryHandler;
-    private utilities;
-    private readonly toolsManager;
-    constructor(modelName?: string, providerName?: AIProviderName, neurolink?: NeuroLink, middleware?: MiddlewareFactoryOptions);
-    /**
-     * Update modelName and rebuild composition handlers with the new value.
-     *
-     * Auto-discovery providers (lm-studio, llamacpp) call this once they have
-     * resolved the loaded model from `/v1/models`. Without this, handlers
-     * (TelemetryHandler, MessageBuilder, ...) keep the pre-discovery name and
-     * pricing / span / log metadata reports the stale value.
-     */
-    protected refreshHandlersForModel(model: string): void;
-    /**
-     * Check if this provider supports tool/function calling
-     * Override in subclasses to disable tools for specific providers or models
-     * @returns the current model's registered capability, or true when unknown
-     */
-    supportsTools(): boolean;
-    /**
-     * Apply the shared tool gate and optionally report registry-backed
-     * suppression at the request entry point.
-     */
-    private shouldUseTools;
-    /**
-     * Primary streaming method - implements AIProvider interface
-     * When tools are involved, falls back to generate() with synthetic streaming
-     */
-    stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ValidationSchema): Promise<StreamResult>;
-    /**
-     * Wrap a StreamResult with consumer-facing lifecycle callbacks.
-     *
-     * `options.onChunk`, `options.onFinish`, `options.onError` are translated
-     * by NeuroLink.applyStreamLifecycleMiddleware() into
-     * `options.middleware.middlewareConfig.lifecycle.config`. The AI SDK's
-     * lifecycle middleware only sees these via the wrapped LanguageModel —
-     * which is bypassed by providers that stream via raw HTTP fetch (Ollama
-     * over /api/chat, custom OpenAI-compatible servers, etc). Wrapping the
-     * user-facing stream here ensures the callbacks fire regardless of the
-     * underlying transport.
-     */
-    private wrapStreamWithLifecycleCallbacks;
-    /**
-     * Fire the consumer-supplied onError callback before throwing. Used in
-     * error branches inside stream() that re-throw without emitting any
-     * stream chunks (which would otherwise hide the failure from a caller
-     * that supplied `onError`).
-     */
-    private fireLifecycleErrorCallback;
-    /**
-     * Execute fake streaming - extracted method for reusability
-     */
-    private executeFakeStreaming;
-    /**
-     * Apply per-call tool filtering (whitelist/blacklist) to a tools record.
-     *
-     * All filtering surfaces are merged into one ResolvedToolPolicy by
-     * `resolveToolPolicy()` — per-call `toolFilter` (whitelist),
-     * `enabledToolNames` (merged into the whitelist, as its docs always
-     * promised), `excludeTools` (denylist, applied after the whitelist), and
-     * the instance-level `tools` config (enabled/include/exclude, `*` globs) —
-     * then applied by `applyToolGate()`. This is the single filter semantics
-     * for every generate/stream path.
-     */
-    private getToolPolicy;
-    private applyToolFiltering;
-    /**
-     * Deterministic name-sorted key order. External MCP servers connect and
-     * discover in parallel, so insertion order varies across process restarts;
-     * providers serialize this record in key order (and Anthropic pins its
-     * cache_control breakpoint to the LAST tool), so an unstable order silently
-     * busts provider prompt caches. Runs AFTER the dedup pass — dedup's
-     * keep-first policy must see phase order (built-ins first) so duplicate
-     * winners don't flip when an MCP tool name sorts earlier.
-     */
-    private sortToolRecord;
-    /**
-     * On-demand discovery (`tools.discovery: true`): defer external MCP tool
-     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
-     * tools, explicitly whitelisted tools, and session-pinned (previously
-     * discovered) tools always stay hot. No-op when discovery is off — with a
-     * one-time WARN when the catalog is large enough that selection accuracy
-     * measurably degrades.
-     */
-    private applyToolDiscovery;
-    private static warnedLargeCatalog;
-    private warnLargeCatalogOnce;
-    /**
-     * Opt-in signature dedup — runs AFTER whitelist/blacklist filtering and
-     * BEFORE the tool set reaches the provider call.  Fails open: any error
-     * inside dedupeTools returns the original filtered set unchanged.
-     */
-    private applyDedupPass;
-    /**
-     * Prepare generation context including tools and model
-     */
-    private prepareGenerationContext;
-    /**
-     * Get merged tools for streaming: combines base tools (MCP/built-in) with
-     * user-provided tools (e.g., RAG tools passed via options.tools).
-     *
-     * This is the canonical tool-merge pattern for executeStream() implementations.
-     * All providers should call this instead of getAllTools() directly.
-     */
-    protected getToolsForStream(options: StreamOptions | TextGenerationOptions): Promise<Record<string, Tool>>;
-    /**
-     * Create (or reuse) the per-call ToolExecutionRecorder and wrap the final
-     * tool record with it. The recorder rides on the options object so provider
-     * loops and result assembly observe the same capture state; wrapping is
-     * idempotent, so paths that re-enter (stream→generate fallback) never
-     * double-record.
-     */
-    protected wrapToolsForExecutionCapture(tools: Record<string, Tool>, options: StreamOptions | TextGenerationOptions): Record<string, Tool>;
-    /**
-     * Build messages array for generation - delegated to MessageBuilder
-     */
-    private buildMessages;
-    /**
-     * Build messages array for streaming operations - delegated to MessageBuilder
-     * This is a protected helper method that providers can use to build messages
-     * with automatic multimodal detection, eliminating code duplication
-     *
-     * @param options - Stream options or text generation options
-     * @returns Promise resolving to ModelMessage array ready for AI SDK
-     */
-    protected buildMessagesForStream(options: StreamOptions | TextGenerationOptions): Promise<ModelMessage[]>;
-    /**
-     * Execute the generation with AI SDK - delegated to GenerationHandler
-     */
-    private executeGeneration;
-    /**
-     * Log generation completion information - delegated to GenerationHandler
-     */
-    private logGenerationComplete;
-    /**
-     * Record performance metrics - delegated to TelemetryHandler
-     */
-    private recordPerformanceMetrics;
-    /**
-     * Extract tool information from generation result - delegated to GenerationHandler
-     */
-    private extractToolInformation;
-    /**
-     * Format the enhanced result - delegated to GenerationHandler
-     */
-    private formatEnhancedResult;
-    /**
-     * Analyze AI response structure and log detailed debugging information - delegated to GenerationHandler
-     */
-    private analyzeAIResponse;
-    /**
-     * Text generation method - implements AIProvider interface
-     * Tools are always available unless explicitly disabled
-     *
-     * Supports Text-to-Speech (TTS) audio generation in two modes:
-     * 1. Direct synthesis (default): TTS synthesizes the input text without AI generation
-     * 2. AI response synthesis: TTS synthesizes the AI-generated response after generation
-     *
-     * When TTS is enabled with useAiResponse=false (default), the method returns early with
-     * only the audio result, skipping AI generation entirely for optimal performance.
-     *
-     * When TTS is enabled with useAiResponse=true, the method performs full AI generation
-     * and then synthesizes the AI response to audio.
-     *
-     * @param optionsOrPrompt - Generation options or prompt string
-     * @param _analysisSchema - Optional analysis schema (not used)
-     * @returns Enhanced result with optional audio field containing TTSResult
-     *
-     * IMPLEMENTATION NOTE: Uses streamText() under the hood and accumulates results
-     * for consistency and better performance
-     */
-    /**
-     * Ensure runtime-discovered model limits (context window, output-token
-     * ceiling) are registered before any budget math runs. Generation
-     * pipelines await this BEFORE `checkContextBudget`, and generate()/stream()
-     * await it before options normalization so `getSafeMaxTokens` sees the
-     * discovered output ceiling.
-     *
-     * Default no-op. Providers with a runtime discovery source override it
-     * (e.g. LiteLLM's `/model/info`). Implementations must NEVER reject —
-     * discovery failure degrades to the static defaults.
-     */
-    ensureModelLimits(): Promise<void>;
-    generate(optionsOrPrompt: TextGenerationOptions | string, _analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
-    /**
-     * Alias for generate method - implements AIProvider interface
-     */
-    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
-    private runGenerateInActiveContext;
-    protected handleDirectTTSSynthesis(options: TextGenerationOptions, startTime: number): Promise<EnhancedGenerateResult>;
-    private handleVideoFrameGeneration;
-    private executeStandardGenerateFlow;
-    protected synthesizeAIResponseIfNeeded(enhancedResult: EnhancedGenerateResult, options: TextGenerationOptions): Promise<EnhancedGenerateResult>;
-    private getTTSErrorDetails;
-    /**
-     * BACKWARD COMPATIBILITY: Legacy generateText method
-     * Converts EnhancedGenerateResult to TextGenerationResult format
-     * Ensures existing scripts using createAIProvider().generateText() continue to work
-     */
-    generateText(options: TextGenerationOptions): Promise<TextGenerationResult>;
-    /**
-     * Generate embeddings for text
-     *
-     * This is a default implementation that throws an error.
-     * Providers that support embeddings (OpenAI, Google Vertex, Amazon Bedrock)
-     * should override this method with their specific implementation.
-     *
-     * @param text - The text to embed
-     * @param _modelName - Optional embedding model name (provider-specific)
-     * @returns Promise resolving to the embedding vector (array of numbers)
-     * @throws Error if the provider does not support embeddings
-     *
-     * @example
-     * ```typescript
-     * const provider = await ProviderFactory.createProvider('openai', 'text-embedding-3-small');
-     * const embedding = await provider.embed('Hello world');
-     * console.log(embedding); // [0.123, -0.456, ...]
-     * ```
-     */
-    embed(text: string, _modelName?: string): Promise<number[]>;
-    /**
-     * Generate embeddings for multiple texts in a single batch
-     *
-     * This is a default implementation that throws an error.
-     * Providers that support embeddings should override this method.
-     * The AI SDK's embedMany automatically handles chunking for models with batch limits.
-     *
-     * @param texts - The texts to embed
-     * @param _modelName - Optional embedding model name (provider-specific)
-     * @returns Promise resolving to an array of embedding vectors
-     * @throws Error if the provider does not support embeddings
-     */
-    embedMany(texts: string[], _modelName?: string): Promise<number[][]>;
-    /**
-     * Get the default embedding model for this provider
-     *
-     * Override in subclasses to provide provider-specific defaults.
-     * Returns undefined for providers that don't support embeddings.
-     *
-     * @returns The default embedding model name, or undefined if not supported
-     */
-    protected getDefaultEmbeddingModel(): string | undefined;
-    /**
-     * Create an `experimental_repairToolCall` handler for streamText/generateText.
-     * Dynamically reads the tool's JSON schema to repair wrong names and params.
-     * Returns undefined when repair is disabled via options.
-     */
-    protected getToolCallRepairFn(options?: StreamOptions | TextGenerationOptions): ToolCallRepairFunction<ToolSet> | undefined;
-    /**
-     * Opt-in streaming hook. A provider that produces an async iterable of text
-     * chunks plus promises for how the turn ended implements this and gets a
-     * working `executeStream` for free.
-     *
-     * Deliberately optional rather than abstract: every provider that already
-     * overrides `executeStream` directly — the older and still perfectly valid
-     * pattern — never needs it.
-     *
-     * `finishReason` and `usage` are promises because both are only knowable
-     * once the underlying stream has finished. Resolve them when it does; the
-     * default `executeStream` chains off them rather than waiting for a
-     * consumer, so they must settle even if nobody drains the stream.
-     */
-    protected doStream?(options: StreamOptions): Promise<{
-        stream: AsyncIterable<{
-            content: string;
-        }>;
-        finishReason: Promise<string>;
-        usage: Promise<{
-            inputTokens: number;
-            outputTokens: number;
-        }>;
-        warnings?: string[];
-    }>;
-    /**
-     * Provider-specific streaming implementation (only used when tools are
-     * disabled).
-     *
-     * This used to be `protected abstract`, which meant a provider had exactly
-     * two options: write the whole adapter by hand, or not stream at all. The
-     * failure mode that produced was SageMaker's — a complete, working
-     * `doStream` sitting one property access away from an `executeStream` that
-     * unconditionally threw "not yet fully implemented". Providers that
-     * implement `doStream` now inherit a correct implementation, and providers
-     * that override this method are unaffected.
-     */
-    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
-    /**
-     * Get the provider name
-     */
-    protected abstract getProviderName(): AIProviderName;
-    /**
-     * Get the default model for this provider
-     */
-    protected abstract getDefaultModel(): string;
-    /**
-     * REQUIRED: Every provider MUST implement this method
-     * Returns the Vercel AI SDK model instance for this provider
-     */
-    protected abstract getAISDKModel(): LanguageModel | Promise<LanguageModel>;
-    /**
-     * Get AI SDK model with middleware applied
-     * This method wraps the base model with any configured middleware
-     * TODO(#1179): Implement global level middlewares that can be used
-     */
-    protected getAISDKModelWithMiddleware(options?: TextGenerationOptions | StreamOptions): Promise<LanguageModel>;
-    /**
-     * Extract middleware options - delegated to Utilities
-     */
-    private extractMiddlewareOptions;
-    /**
-     * Check if a schema is a Zod schema - delegated to Utilities
-     */
-    private isZodSchema;
-    /**
-     * Convert tool execution result - delegated to Utilities
-     */
-    private convertToolResult;
-    /**
-     * Fix JSON Schema for OpenAI strict mode - delegated to Utilities
-     */
-    private fixSchemaForOpenAIStrictMode;
-    /**
-     * Get all available tools - delegated to ToolsManager
-     */
-    protected getAllTools(): Promise<Record<string, Tool>>;
-    /**
-     * Calculate actual cost - delegated to TelemetryHandler
-     */
-    private calculateActualCost;
-    /**
-     * Create a permissive Zod schema - delegated to Utilities
-     */
-    private createPermissiveZodSchema;
-    /**
-     * Set session context for MCP tools - delegated to ToolsManager
-     */
-    setSessionContext(sessionId?: string, userId?: string): void;
-    /**
-     * Provider-specific error formatting.
-     * Subclasses implement this to produce human-readable error messages
-     * (e.g., "❌ Google Vertex AI Provider Error\n\n...").
-     */
-    protected abstract formatProviderError(error: unknown): Error;
-    /**
-     * Handle provider errors with abort passthrough.
-     * AbortErrors are never wrapped — they must propagate with their
-     * original identity so that isAbortError() can detect them in
-     * retry/fallback loops (directProviderGeneration, performMCPGenerationRetries).
-     */
-    protected handleProviderError(error: unknown): Error;
-    /**
-     * Image generation method. Providers that support it should override this.
-     * By default, it throws an error indicating that the functionality is not supported.
-     * @param _options The generation options.
-     * @returns A promise that resolves to the generation result.
-     */
-    protected executeImageGeneration(_options: TextGenerationOptions): Promise<EnhancedGenerateResult>;
-    /**
-     * Execute operation with timeout and proper cleanup
-     * Consolidates identical timeout handling from 8/10 providers
-     */
-    protected executeWithTimeout<T>(operation: () => Promise<T>, options: {
-        timeout?: number | string;
-        operationType?: string;
-    }): Promise<T>;
-    /**
-     * Validate stream options - delegated to StreamHandler
-     */
-    protected validateStreamOptions(options: StreamOptions): void;
-    /**
-     * Create text stream transformation - delegated to StreamHandler.
-     * Reviewer follow-up: forwards the optional `getUnderlyingError`
-     * callback so providers can capture upstream errors via
-     * `streamText`'s `onError` and have them flow into the
-     * NoOutputGeneratedError sentinel's `providerError` /
-     * `modelResponseRaw`.
-     */
-    protected createTextStream(result: {
-        textStream: AsyncIterable<string>;
-        finishReason?: Promise<unknown> | unknown;
-        totalUsage?: Promise<unknown> | unknown;
-    }, getUnderlyingError?: () => unknown): AsyncGenerator<{
-        content: string;
-    } | import("../types/index.js").StreamNoOutputSentinel>;
-    /**
-     * Create standardized stream result - delegated to StreamHandler
-     */
-    protected createStreamResult(stream: AsyncGenerator<{
-        content: string;
-    }>, additionalProps?: Partial<StreamResult>): StreamResult;
-    /**
-     * Create stream analytics - delegated to StreamHandler
-     */
-    protected createStreamAnalytics(result: UnknownRecord, startTime: number, options: StreamOptions): Promise<UnknownRecord | undefined>;
-    /**
-     * Handle common error patterns - delegated to Utilities
-     */
-    protected handleCommonErrors(error: unknown): Error | null;
-    /**
-     * Set up tool executor - delegated to ToolsManager
-     * @param sdk - The NeuroLinkSDK instance for tool execution
-     * @param functionTag - Function name for logging
-     */
-    setupToolExecutor(sdk: {
-        customTools: Map<string, unknown>;
-        executeTool: (toolName: string, params: unknown) => Promise<unknown>;
-    }, functionTag: string): void;
-    /**
-     * Normalize text generation options - delegated to Utilities
-     */
-    protected normalizeTextOptions(optionsOrPrompt: TextGenerationOptions | string): TextGenerationOptions;
-    /**
-     * Normalize stream options - delegated to Utilities
-     */
-    protected normalizeStreamOptions(optionsOrPrompt: StreamOptions | string): StreamOptions;
-    protected enhanceResult(result: EnhancedGenerateResult, options: TextGenerationOptions, startTime: number): Promise<EnhancedGenerateResult>;
-    /**
-     * Handle video generation mode
-     *
-     * Generates video from input image + text prompt using Vertex AI Veo 3.1.
-     *
-     * @param options - Text generation options with video configuration
-     * @param startTime - Generation start timestamp for metrics
-     * @returns Enhanced result with video data
-     *
-     * @example
-     * ```typescript
-     * const result = await provider.generate({
-     *   input: { text: "Product showcase", images: [imageBuffer] },
-     *   output: { mode: "video", video: { resolution: "1080p" } }
-     * });
-     * // result.video contains the generated video
-     * ```
-     */
-    protected handleVideoGeneration(options: TextGenerationOptions, startTime: number): Promise<EnhancedGenerateResult>;
-    /**
-     * Create analytics - delegated to TelemetryHandler
-     */
-    protected createAnalytics(result: EnhancedGenerateResult, responseTime: number, options: TextGenerationOptions): Promise<AnalyticsData>;
-    /**
-     * Create evaluation - delegated to TelemetryHandler
-     */
-    protected createEvaluation(result: EnhancedGenerateResult, options: TextGenerationOptions): Promise<EvaluationData>;
-    /**
-     * Validate text generation options - delegated to Utilities
-     */
-    protected validateOptions(options: TextGenerationOptions): void;
-    /**
-     * Get provider information - delegated to Utilities
-     */
-    protected getProviderInfo(): {
-        provider: string;
-        model: string;
-    };
-    /**
-     * Get timeout value in milliseconds - delegated to Utilities
-     */
-    getTimeout(options: TextGenerationOptions | StreamOptions): number;
-    /**
-     * Check if tool executions should be stored and handle storage
-     */
-    protected handleToolExecutionStorage(toolCalls: unknown[], toolResults: unknown[], options: TextGenerationOptions | StreamOptions, currentTime: Date): Promise<void>;
-    /**
-     * Utility method to chunk large prompts into smaller pieces
-     * @param prompt The prompt to chunk
-     * @param maxChunkSize Maximum size per chunk (default: 900,000 characters)
-     * @param overlap Overlap between chunks to maintain context (default: 100 characters)
-     * @returns Array of prompt chunks
-     */
-    static chunkPrompt(prompt: string, maxChunkSize?: number, overlap?: number): string[];
-}