@juspay/neurolink 8.32.0 → 8.34.0

package/dist/lib/action/githubIntegration.js

@@ -0,0 +1,188 @@
+// src/lib/action/githubIntegration.ts
+/**
+ * GitHub API integration for comments, outputs, and job summary
+ * @module action/githubIntegration
+ */
+import * as core from "@actions/core";
+import * as github from "@actions/github";
+/**
+ * Build comment body for PR/issue
+ */
+function buildCommentBody(inputs, result) {
+    const commentTag = `<!-- ${inputs.commentTag} -->`;
+    const parts = [commentTag];
+    parts.push("## 🤖 NeuroLink AI Response\n");
+    parts.push(result.response);
+    parts.push("\n---");
+    // Build metadata line
+    const metaParts = [];
+    if (result.model) {
+        metaParts.push(`\`${result.model}\``);
+    }
+    if (result.provider) {
+        metaParts.push(`via ${result.provider}`);
+    }
+    if (result.cost) {
+        metaParts.push(`$${result.cost.toFixed(6)}`);
+    }
+    if (result.usage?.totalTokens) {
+        metaParts.push(`${result.usage.totalTokens} tokens`);
+    }
+    parts.push(`<sub>Generated by [NeuroLink](https://github.com/juspay/neurolink)${metaParts.length ? ` using ${metaParts.join(" | ")}` : ""}</sub>`);
+    return parts.join("\n");
+}
+/**
+ * Find existing comment by tag
+ */
+async function findExistingComment(octokit, owner, repo, issueNumber, commentTag) {
+    const { data: comments } = await octokit.rest.issues.listComments({
+        owner,
+        repo,
+        issue_number: issueNumber,
+    });
+    const existing = comments.find((c) => c.body?.includes(`<!-- ${commentTag} -->`));
+    return existing?.id;
+}
+/**
+ * Post result as comment on PR or issue
+ */
+export async function postResultComment(inputs, result) {
+    if (!inputs.postComment) {
+        return { success: true };
+    }
+    const token = inputs.githubToken;
+    if (!token) {
+        core.warning("post_comment enabled but no github_token provided");
+        return { success: false, error: "No GitHub token" };
+    }
+    const context = github.context;
+    const issueNumber = context.payload.pull_request?.number || context.payload.issue?.number;
+    if (!issueNumber) {
+        core.warning("post_comment enabled but not in PR or issue context");
+        return { success: false, error: "Not in PR or issue context" };
+    }
+    const octokit = github.getOctokit(token);
+    const body = buildCommentBody(inputs, result);
+    try {
+        // Check for existing comment if update mode is enabled
+        if (inputs.updateExistingComment) {
+            const existingId = await findExistingComment(octokit, context.repo.owner, context.repo.repo, issueNumber, inputs.commentTag);
+            if (existingId) {
+                const { data } = await octokit.rest.issues.updateComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    comment_id: existingId,
+                    body,
+                });
+                core.info(`Updated existing comment #${existingId}`);
+                return { success: true, commentId: data.id, commentUrl: data.html_url };
+            }
+        }
+        // Create new comment
+        const { data } = await octokit.rest.issues.createComment({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: issueNumber,
+            body,
+        });
+        core.info(`Created comment #${data.id}`);
+        return { success: true, commentId: data.id, commentUrl: data.html_url };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        core.warning(`Failed to post comment: ${message}`);
+        return { success: false, error: message };
+    }
+}
+/**
+ * Write job summary
+ */
+export async function writeJobSummary(inputs, result) {
+    const summary = core.summary
+        .addHeading("NeuroLink Execution Summary", 2)
+        .addTable([
+        [
+            { data: "Metric", header: true },
+            { data: "Value", header: true },
+        ],
+        ["Provider", result.provider || "auto"],
+        ["Model", result.model || "auto"],
+        ["Input Tokens", String(result.usage?.promptTokens || "N/A")],
+        ["Output Tokens", String(result.usage?.completionTokens || "N/A")],
+        ["Total Tokens", String(result.usage?.totalTokens || "N/A")],
+        ["Cost", result.cost ? `$${result.cost.toFixed(6)}` : "N/A"],
+        [
+            "Execution Time",
+            result.executionTime ? `${result.executionTime}ms` : "N/A",
+        ],
+    ]);
+    if (result.evaluation) {
+        summary.addHeading("Quality Evaluation", 3);
+        summary.addRaw(`Score: ${result.evaluation.overallScore}/100`);
+    }
+    summary.addHeading("Response", 3);
+    const truncatedResponse = result.response.length > 5000
+        ? result.response.substring(0, 5000) + "..."
+        : result.response;
+    summary.addRaw(truncatedResponse);
+    try {
+        await summary.write();
+    }
+    catch (error) {
+        // Job summary may not be available in all environments (e.g., local testing)
+        core.warning(`Unable to write job summary: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Set all action outputs
+ */
+export function setActionOutputs(result, commentResult) {
+    core.setOutput("response", result.response);
+    core.setOutput("response_json", JSON.stringify(result.responseJson || {}));
+    if (result.provider) {
+        core.setOutput("provider", result.provider);
+    }
+    if (result.model) {
+        core.setOutput("model", result.model);
+    }
+    if (result.usage?.totalTokens) {
+        core.setOutput("tokens_used", result.usage.totalTokens.toString());
+    }
+    if (result.usage?.promptTokens) {
+        core.setOutput("prompt_tokens", result.usage.promptTokens.toString());
+    }
+    if (result.usage?.completionTokens) {
+        core.setOutput("completion_tokens", result.usage.completionTokens.toString());
+    }
+    if (result.cost) {
+        core.setOutput("cost", result.cost.toString());
+    }
+    if (result.executionTime) {
+        core.setOutput("execution_time", result.executionTime.toString());
+    }
+    if (result.evaluation?.overallScore) {
+        core.setOutput("evaluation_score", result.evaluation.overallScore.toString());
+    }
+    if (commentResult?.commentId) {
+        core.setOutput("comment_id", commentResult.commentId.toString());
+    }
+}
+/**
+ * Get all outputs as typed object (snake_case to match action.yml outputs)
+ */
+export function getActionOutputs(result, commentResult) {
+    return {
+        response: result.response,
+        response_json: JSON.stringify(result.responseJson || {}),
+        provider: result.provider,
+        model: result.model,
+        tokens_used: result.usage?.totalTokens?.toString(),
+        prompt_tokens: result.usage?.promptTokens?.toString(),
+        completion_tokens: result.usage?.completionTokens?.toString(),
+        cost: result.cost?.toString(),
+        execution_time: result.executionTime?.toString(),
+        evaluation_score: result.evaluation?.overallScore?.toString(),
+        comment_id: commentResult?.commentId?.toString(),
+    };
+}
+//# sourceMappingURL=githubIntegration.js.map

package/dist/lib/action/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * GitHub Action module exports
+ * @module action
+ */
+export { parseActionInputs, validateProviderKey, buildEnvironmentVariables, validateActionInputs, maskSecrets, } from "./actionInputs.js";
+export { buildCliArgs, installNeurolink, executeNeurolink, runNeurolink, transformCliResponse, } from "./actionExecutor.js";
+export { postResultComment, writeJobSummary, setActionOutputs, getActionOutputs, } from "./githubIntegration.js";
+export type { ActionInputs, ActionExecutionResult, ActionCommentResult, ActionOutput, ActionProviderKeys, ActionAWSConfig, ActionGoogleCloudConfig, ActionThinkingConfig, ActionMultimodalInputs, ActionTokenUsage, ActionEvaluation, ActionInputValidation, CliResponse, CliTokenUsage, } from "../types/actionTypes.js";

package/dist/lib/action/index.js

@@ -0,0 +1,12 @@
+// src/lib/action/index.ts
+/**
+ * GitHub Action module exports
+ * @module action
+ */
+// Input handling
+export { parseActionInputs, validateProviderKey, buildEnvironmentVariables, validateActionInputs, maskSecrets, } from "./actionInputs.js";
+// Execution
+export { buildCliArgs, installNeurolink, executeNeurolink, runNeurolink, transformCliResponse, } from "./actionExecutor.js";
+// GitHub integration
+export { postResultComment, writeJobSummary, setActionOutputs, getActionOutputs, } from "./githubIntegration.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/index.d.ts

@@ -1,10 +1,35 @@
 /**
  * NeuroLink AI Toolkit
  *
- * A unified AI provider interface with support for multiple providers,
- * automatic fallback, streaming, and tool integration.
+ * A unified AI provider interface with support for 13+ providers,
+ * automatic fallback, streaming, MCP tool integration, HITL security,
+ * Redis persistence, and enterprise-grade middleware.
  *
- * Provides comprehensive AI functionality with proven patterns.
+ * NeuroLink provides comprehensive AI functionality with battle-tested
+ * patterns extracted from production systems at Juspay.
+ *
+ * @packageDocumentation
+ * @module @juspay/neurolink
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * import { NeuroLink } from '@juspay/neurolink';
+ *
+ * // Create NeuroLink instance
+ * const neurolink = new NeuroLink();
+ *
+ * // Generate with any provider
+ * const result = await neurolink.generate({
+ *   input: { text: 'Explain quantum computing' },
+ *   provider: 'vertex',
+ *   model: 'gemini-3-flash'
+ * });
+ *
+ * console.log(result.content);
+ * ```
+ *
+ * @since 1.0.0
  */
 import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
@@ -29,37 +54,117 @@ export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions,
 export { MiddlewareFactory } from "./middleware/factory.js";
 export declare const VERSION = "1.0.0";
 /**
- * Quick start factory function
+ * Quick start factory function for creating AI provider instances.
  *
- * @example
+ * Creates a configured AI provider instance ready for immediate use.
+ * Supports all 13 providers: OpenAI, Anthropic, Google AI Studio,
+ * Google Vertex, AWS Bedrock, AWS SageMaker, Azure OpenAI, Hugging Face,
+ * LiteLLM, Mistral, Ollama, OpenAI Compatible, and OpenRouter.
+ *
+ * @category Factory
+ *
+ * @param providerName - The AI provider name (e.g., 'bedrock', 'vertex', 'openai')
+ * @param modelName - Optional model name to override provider default
+ * @returns Promise resolving to configured AI provider instance
+ *
+ * @example Basic usage
  * ```typescript
  * import { createAIProvider } from '@juspay/neurolink';
  *
  * const provider = await createAIProvider('bedrock');
  * const result = await provider.stream({ input: { text: 'Hello, AI!' } });
  * ```
+ *
+ * @example With custom model
+ * ```typescript
+ * const provider = await createAIProvider('vertex', 'gemini-3-flash');
+ * ```
+ *
+ * @see {@link AIProviderFactory.createProvider}
+ * @see {@link NeuroLink} for the main SDK class
+ * @since 1.0.0
  */
 export declare function createAIProvider(providerName?: string, modelName?: string): Promise<import("./types/providers.js").AIProvider>;
 /**
- * Create provider with automatic fallback
+ * Create provider with automatic fallback for production resilience.
  *
- * @example
+ * Creates both primary and fallback provider instances for high-availability
+ * deployments. Automatically switches to fallback on primary provider failure.
+ *
+ * @category Factory
+ *
+ * @param primaryProvider - Primary AI provider name (default: 'bedrock')
+ * @param fallbackProvider - Fallback AI provider name (default: 'vertex')
+ * @param modelName - Optional model name for both providers
+ * @returns Promise resolving to object with primary and fallback providers
+ *
+ * @example Production failover setup
  * ```typescript
  * import { createAIProviderWithFallback } from '@juspay/neurolink';
  *
  * const { primary, fallback } = await createAIProviderWithFallback('bedrock', 'vertex');
+ *
+ * try {
+ *   const result = await primary.generate({ input: { text: 'Hello!' } });
+ * } catch (error) {
+ *   // Automatically use fallback
+ *   const result = await fallback.generate({ input: { text: 'Hello!' } });
+ * }
  * ```
+ *
+ * @example Multi-region setup
+ * ```typescript
+ * const { primary, fallback } = await createAIProviderWithFallback(
+ *   'vertex',      // Primary: US region
+ *   'bedrock',     // Fallback: Global
+ *   'claude-3-sonnet'
+ * );
+ * ```
+ *
+ * @see {@link AIProviderFactory.createProviderWithFallback}
+ * @since 1.0.0
  */
 export declare function createAIProviderWithFallback(primaryProvider?: string, fallbackProvider?: string, modelName?: string): Promise<import("./types/typeAliases.js").ProviderPairResult<import("./types/providers.js").AIProvider>>;
 /**
- * Create the best available provider based on configuration
+ * Create the best available provider based on environment configuration.
  *
- * @example
+ * Intelligently selects the best provider based on available API keys
+ * in environment variables. Automatically detects and configures the
+ * optimal provider without manual configuration.
+ *
+ * @category Factory
+ *
+ * @param requestedProvider - Optional preferred provider name
+ * @param modelName - Optional model name
+ * @returns Promise resolving to the best configured provider
+ *
+ * @example Automatic provider selection
  * ```typescript
  * import { createBestAIProvider } from '@juspay/neurolink';
  *
+ * // Automatically uses provider with configured API key
  * const provider = await createBestAIProvider();
+ * const result = await provider.generate({ input: { text: 'Hello!' } });
+ * ```
+ *
+ * @example With provider preference
+ * ```typescript
+ * // Tries to use OpenAI, falls back to available provider
+ * const provider = await createBestAIProvider('openai');
  * ```
+ *
+ * @remarks
+ * Environment variables checked (in order):
+ * - OPENAI_API_KEY
+ * - ANTHROPIC_API_KEY
+ * - GOOGLE_API_KEY
+ * - VERTEX_PROJECT_ID + credentials
+ * - AWS credentials for Bedrock
+ * - And more...
+ *
+ * @see {@link AIProviderFactory.createBestProvider}
+ * @see {@link getBestProvider} for provider detection utility
+ * @since 1.0.0
  */
 export declare function createBestAIProvider(requestedProvider?: string, modelName?: string): Promise<import("./types/providers.js").AIProvider>;
 /**
@@ -97,19 +202,46 @@ export declare function getTelemetryStatus(): Promise<{
 }>;
 export type { TextGenerationOptions, TextGenerationResult, AnalyticsData, EvaluationData, } from "./types/index.js";
 /**
- * BACKWARD COMPATIBILITY: Legacy generateText function
- * Provides standalone generateText function for existing code that uses it
+ * Legacy generateText function for backward compatibility.
  *
- * @example
+ * Provides standalone text generation function for existing code.
+ * For new code, use {@link NeuroLink.generate} instead which provides
+ * more features including streaming, tools, and structured output.
+ *
+ * @category Legacy
+ * @deprecated Use {@link NeuroLink.generate} for new code
+ *
+ * @param options - Text generation options
+ * @param options.prompt - Input prompt text
+ * @param options.provider - AI provider name (e.g., 'bedrock', 'openai')
+ * @param options.model - Model name to use
+ * @param options.temperature - Sampling temperature (0-2)
+ * @param options.maxTokens - Maximum tokens to generate
+ * @returns Promise resolving to text generation result with content and metadata
+ *
+ * @example Basic text generation
  * ```typescript
  * import { generateText } from '@juspay/neurolink';
  *
  * const result = await generateText({
- *   prompt: 'Hello, AI!',
+ *   prompt: 'Explain quantum computing in simple terms',
  *   provider: 'bedrock',
  *   model: 'claude-3-sonnet'
  * });
  * console.log(result.content);
  * ```
+ *
+ * @example With temperature control
+ * ```typescript
+ * const result = await generateText({
+ *   prompt: 'Write a creative story',
+ *   provider: 'openai',
+ *   temperature: 1.5,
+ *   maxTokens: 500
+ * });
+ * ```
+ *
+ * @see {@link NeuroLink.generate} for modern API with more features
+ * @since 1.0.0
  */
 export declare function generateText(options: import("./types/index.js").TextGenerationOptions): Promise<import("./types/index.js").TextGenerationResult>;

package/dist/lib/index.js

@@ -1,10 +1,35 @@
 /**
  * NeuroLink AI Toolkit
  *
- * A unified AI provider interface with support for multiple providers,
- * automatic fallback, streaming, and tool integration.
+ * A unified AI provider interface with support for 13+ providers,
+ * automatic fallback, streaming, MCP tool integration, HITL security,
+ * Redis persistence, and enterprise-grade middleware.
  *
- * Provides comprehensive AI functionality with proven patterns.
+ * NeuroLink provides comprehensive AI functionality with battle-tested
+ * patterns extracted from production systems at Juspay.
+ *
+ * @packageDocumentation
+ * @module @juspay/neurolink
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * import { NeuroLink } from '@juspay/neurolink';
+ *
+ * // Create NeuroLink instance
+ * const neurolink = new NeuroLink();
+ *
+ * // Generate with any provider
+ * const result = await neurolink.generate({
+ *   input: { text: 'Explain quantum computing' },
+ *   provider: 'vertex',
+ *   model: 'gemini-3-flash'
+ * });
+ *
+ * console.log(result.content);
+ * ```
+ *
+ * @since 1.0.0
  */
 // Core exports
 import { AIProviderFactory } from "./core/factory.js";
@@ -28,41 +53,121 @@ export { MiddlewareFactory } from "./middleware/factory.js";
 // Version
 export const VERSION = "1.0.0";
 /**
- * Quick start factory function
+ * Quick start factory function for creating AI provider instances.
  *
- * @example
+ * Creates a configured AI provider instance ready for immediate use.
+ * Supports all 13 providers: OpenAI, Anthropic, Google AI Studio,
+ * Google Vertex, AWS Bedrock, AWS SageMaker, Azure OpenAI, Hugging Face,
+ * LiteLLM, Mistral, Ollama, OpenAI Compatible, and OpenRouter.
+ *
+ * @category Factory
+ *
+ * @param providerName - The AI provider name (e.g., 'bedrock', 'vertex', 'openai')
+ * @param modelName - Optional model name to override provider default
+ * @returns Promise resolving to configured AI provider instance
+ *
+ * @example Basic usage
  * ```typescript
  * import { createAIProvider } from '@juspay/neurolink';
  *
  * const provider = await createAIProvider('bedrock');
  * const result = await provider.stream({ input: { text: 'Hello, AI!' } });
  * ```
+ *
+ * @example With custom model
+ * ```typescript
+ * const provider = await createAIProvider('vertex', 'gemini-3-flash');
+ * ```
+ *
+ * @see {@link AIProviderFactory.createProvider}
+ * @see {@link NeuroLink} for the main SDK class
+ * @since 1.0.0
  */
 export async function createAIProvider(providerName, modelName) {
     return await AIProviderFactory.createProvider(providerName || "bedrock", modelName);
 }
 /**
- * Create provider with automatic fallback
+ * Create provider with automatic fallback for production resilience.
  *
- * @example
+ * Creates both primary and fallback provider instances for high-availability
+ * deployments. Automatically switches to fallback on primary provider failure.
+ *
+ * @category Factory
+ *
+ * @param primaryProvider - Primary AI provider name (default: 'bedrock')
+ * @param fallbackProvider - Fallback AI provider name (default: 'vertex')
+ * @param modelName - Optional model name for both providers
+ * @returns Promise resolving to object with primary and fallback providers
+ *
+ * @example Production failover setup
  * ```typescript
  * import { createAIProviderWithFallback } from '@juspay/neurolink';
  *
  * const { primary, fallback } = await createAIProviderWithFallback('bedrock', 'vertex');
+ *
+ * try {
+ *   const result = await primary.generate({ input: { text: 'Hello!' } });
+ * } catch (error) {
+ *   // Automatically use fallback
+ *   const result = await fallback.generate({ input: { text: 'Hello!' } });
+ * }
  * ```
+ *
+ * @example Multi-region setup
+ * ```typescript
+ * const { primary, fallback } = await createAIProviderWithFallback(
+ *   'vertex',      // Primary: US region
+ *   'bedrock',     // Fallback: Global
+ *   'claude-3-sonnet'
+ * );
+ * ```
+ *
+ * @see {@link AIProviderFactory.createProviderWithFallback}
+ * @since 1.0.0
  */
 export async function createAIProviderWithFallback(primaryProvider, fallbackProvider, modelName) {
     return await AIProviderFactory.createProviderWithFallback(primaryProvider || "bedrock", fallbackProvider || "vertex", modelName);
 }
 /**
- * Create the best available provider based on configuration
+ * Create the best available provider based on environment configuration.
  *
- * @example
+ * Intelligently selects the best provider based on available API keys
+ * in environment variables. Automatically detects and configures the
+ * optimal provider without manual configuration.
+ *
+ * @category Factory
+ *
+ * @param requestedProvider - Optional preferred provider name
+ * @param modelName - Optional model name
+ * @returns Promise resolving to the best configured provider
+ *
+ * @example Automatic provider selection
  * ```typescript
  * import { createBestAIProvider } from '@juspay/neurolink';
  *
+ * // Automatically uses provider with configured API key
  * const provider = await createBestAIProvider();
+ * const result = await provider.generate({ input: { text: 'Hello!' } });
+ * ```
+ *
+ * @example With provider preference
+ * ```typescript
+ * // Tries to use OpenAI, falls back to available provider
+ * const provider = await createBestAIProvider('openai');
  * ```
+ *
+ * @remarks
+ * Environment variables checked (in order):
+ * - OPENAI_API_KEY
+ * - ANTHROPIC_API_KEY
+ * - GOOGLE_API_KEY
+ * - VERTEX_PROJECT_ID + credentials
+ * - AWS credentials for Bedrock
+ * - And more...
+ *
+ * @see {@link AIProviderFactory.createBestProvider}
+ * @see {@link getBestProvider} for provider detection utility
+ * @since 1.0.0
  */
 export async function createBestAIProvider(requestedProvider, modelName) {
     return await AIProviderFactory.createBestProvider(requestedProvider, modelName);
@@ -121,20 +226,47 @@ export async function getTelemetryStatus() {
     return getStatus();
 }
 /**
- * BACKWARD COMPATIBILITY: Legacy generateText function
- * Provides standalone generateText function for existing code that uses it
+ * Legacy generateText function for backward compatibility.
  *
- * @example
+ * Provides standalone text generation function for existing code.
+ * For new code, use {@link NeuroLink.generate} instead which provides
+ * more features including streaming, tools, and structured output.
+ *
+ * @category Legacy
+ * @deprecated Use {@link NeuroLink.generate} for new code
+ *
+ * @param options - Text generation options
+ * @param options.prompt - Input prompt text
+ * @param options.provider - AI provider name (e.g., 'bedrock', 'openai')
+ * @param options.model - Model name to use
+ * @param options.temperature - Sampling temperature (0-2)
+ * @param options.maxTokens - Maximum tokens to generate
+ * @returns Promise resolving to text generation result with content and metadata
+ *
+ * @example Basic text generation
  * ```typescript
  * import { generateText } from '@juspay/neurolink';
  *
  * const result = await generateText({
- *   prompt: 'Hello, AI!',
+ *   prompt: 'Explain quantum computing in simple terms',
  *   provider: 'bedrock',
  *   model: 'claude-3-sonnet'
  * });
  * console.log(result.content);
  * ```
+ *
+ * @example With temperature control
+ * ```typescript
+ * const result = await generateText({
+ *   prompt: 'Write a creative story',
+ *   provider: 'openai',
+ *   temperature: 1.5,
+ *   maxTokens: 500
+ * });
+ * ```
+ *
+ * @see {@link NeuroLink.generate} for modern API with more features
+ * @since 1.0.0
  */
 export async function generateText(options) {
     // Create instance on-demand without auto-instantiation