@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/server/openapi/templates.js

@@ -0,0 +1,374 @@
+/**
+ * OpenAPI Templates
+ * Reusable OpenAPI path and operation templates
+ */
+// ============================================
+// Response Templates
+// ============================================
+/**
+ * Create a success response template
+ */
+export function createSuccessResponse(description, schemaRef, contentType = "application/json") {
+    return {
+        description,
+        content: {
+            [contentType]: {
+                schema: {
+                    $ref: `#/components/schemas/${schemaRef}`,
+                },
+            },
+        },
+    };
+}
+/**
+ * Create an error response template
+ */
+export function createErrorResponse(description, _statusCode = 400) {
+    return {
+        description,
+        content: {
+            "application/json": {
+                schema: {
+                    $ref: "#/components/schemas/ErrorResponse",
+                },
+            },
+        },
+    };
+}
+/**
+ * Create a streaming response template
+ */
+export function createStreamingResponse(description) {
+    return {
+        description,
+        content: {
+            "text/event-stream": {
+                schema: {
+                    type: "string",
+                    description: "Server-Sent Events stream",
+                },
+            },
+        },
+    };
+}
+/**
+ * Standard error responses for common HTTP status codes
+ */
+export const StandardErrorResponses = {
+    "400": createErrorResponse("Bad Request - Invalid input"),
+    "401": createErrorResponse("Unauthorized - Authentication required"),
+    "403": createErrorResponse("Forbidden - Insufficient permissions"),
+    "404": createErrorResponse("Not Found - Resource does not exist"),
+    "429": createErrorResponse("Too Many Requests - Rate limit exceeded"),
+    "500": createErrorResponse("Internal Server Error"),
+};
+// ============================================
+// Parameter Templates
+// ============================================
+/**
+ * Create a path parameter template
+ */
+export function createPathParameter(name, description, schema = { type: "string" }) {
+    return {
+        name,
+        in: "path",
+        required: true,
+        description,
+        schema,
+    };
+}
+/**
+ * Create a query parameter template
+ */
+export function createQueryParameter(name, description, schema = { type: "string" }, required = false) {
+    return {
+        name,
+        in: "query",
+        required,
+        description,
+        schema,
+    };
+}
+/**
+ * Create a header parameter template
+ */
+export function createHeaderParameter(name, description, required = false) {
+    return {
+        name,
+        in: "header",
+        required,
+        description,
+        schema: {
+            type: "string",
+        },
+    };
+}
+/**
+ * Common parameters
+ */
+export const CommonParameters = {
+    sessionId: createPathParameter("sessionId", "Session identifier"),
+    serverName: createPathParameter("name", "MCP server name"),
+    toolName: createPathParameter("name", "Tool name"),
+    limitQuery: createQueryParameter("limit", "Maximum number of items to return", { type: "integer", minimum: 1, maximum: 100, default: 25 }),
+    offsetQuery: createQueryParameter("offset", "Number of items to skip", {
+        type: "integer",
+        minimum: 0,
+        default: 0,
+    }),
+    searchQuery: createQueryParameter("q", "Search query string", {
+        type: "string",
+    }),
+    requestIdHeader: createHeaderParameter("X-Request-ID", "Unique request identifier for tracing"),
+    authorizationHeader: createHeaderParameter("Authorization", "Bearer token or API key", true),
+};
+// ============================================
+// Operation Templates
+// ============================================
+/**
+ * Create a standard GET operation
+ */
+export function createGetOperation(summary, description, tags, responseSchema, parameters) {
+    return {
+        summary,
+        description,
+        tags,
+        parameters: parameters ?? [],
+        responses: {
+            "200": createSuccessResponse("Success", responseSchema),
+            ...StandardErrorResponses,
+        },
+    };
+}
+/**
+ * Create a standard POST operation
+ */
+export function createPostOperation(summary, description, tags, requestSchema, responseSchema, parameters) {
+    return {
+        summary,
+        description,
+        tags,
+        parameters: parameters ?? [],
+        requestBody: {
+            required: true,
+            content: {
+                "application/json": {
+                    schema: {
+                        $ref: `#/components/schemas/${requestSchema}`,
+                    },
+                },
+            },
+        },
+        responses: {
+            "200": createSuccessResponse("Success", responseSchema),
+            ...StandardErrorResponses,
+        },
+    };
+}
+/**
+ * Create a streaming POST operation
+ */
+export function createStreamingPostOperation(summary, description, tags, requestSchema, parameters) {
+    return {
+        summary,
+        description,
+        tags,
+        parameters: parameters ?? [],
+        requestBody: {
+            required: true,
+            content: {
+                "application/json": {
+                    schema: {
+                        $ref: `#/components/schemas/${requestSchema}`,
+                    },
+                },
+            },
+        },
+        responses: {
+            "200": createStreamingResponse("Streaming response"),
+            ...StandardErrorResponses,
+        },
+    };
+}
+/**
+ * Create a DELETE operation
+ */
+export function createDeleteOperation(summary, description, tags, parameters) {
+    return {
+        summary,
+        description,
+        tags,
+        parameters,
+        responses: {
+            "204": {
+                description: "Successfully deleted",
+            },
+            ...StandardErrorResponses,
+        },
+    };
+}
+// ============================================
+// Security Scheme Templates
+// ============================================
+/**
+ * Bearer token security scheme
+ */
+export const BearerSecurityScheme = {
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "JWT",
+    description: "JWT Bearer token authentication",
+};
+/**
+ * API key security scheme (header)
+ */
+export const ApiKeySecurityScheme = {
+    type: "apiKey",
+    in: "header",
+    name: "X-API-Key",
+    description: "API key authentication via header",
+};
+/**
+ * Basic auth security scheme
+ */
+export const BasicSecurityScheme = {
+    type: "http",
+    scheme: "basic",
+    description: "HTTP Basic authentication",
+};
+// ============================================
+// Tag Templates
+// ============================================
+/**
+ * Standard API tags
+ */
+export const StandardTags = [
+    {
+        name: "agent",
+        description: "Agent execution and streaming endpoints",
+    },
+    {
+        name: "tools",
+        description: "Tool discovery and execution endpoints",
+    },
+    {
+        name: "mcp",
+        description: "MCP server management endpoints",
+    },
+    {
+        name: "memory",
+        description: "Conversation memory and session management",
+    },
+    {
+        name: "health",
+        description: "Health check and metrics endpoints",
+    },
+    {
+        name: "streaming",
+        description: "Real-time streaming endpoints",
+    },
+];
+// ============================================
+// Server Templates
+// ============================================
+/**
+ * Create a server definition
+ */
+export function createServer(url, description, variables) {
+    const server = {
+        url,
+        description,
+    };
+    if (variables) {
+        server.variables = Object.entries(variables).reduce((acc, [key, value]) => {
+            acc[key] = {
+                default: value.default,
+                description: value.description,
+            };
+            return acc;
+        }, {});
+    }
+    return server;
+}
+/**
+ * Default server configurations
+ */
+export const DefaultServers = [
+    createServer("http://localhost:3000", "Local development server"),
+    createServer("{protocol}://{host}:{port}", "Custom server", {
+        protocol: {
+            default: "http",
+            description: "Protocol (http or https)",
+        },
+        host: {
+            default: "localhost",
+            description: "Server hostname",
+        },
+        port: {
+            default: "3000",
+            description: "Server port",
+        },
+    }),
+];
+// ============================================
+// Info Templates
+// ============================================
+/**
+ * Create API info section
+ */
+export function createApiInfo(title, version, description, options) {
+    const info = {
+        title,
+        version,
+        description,
+    };
+    if (options?.termsOfService) {
+        info.termsOfService = options.termsOfService;
+    }
+    if (options?.contact) {
+        info.contact = options.contact;
+    }
+    if (options?.license) {
+        info.license = options.license;
+    }
+    return info;
+}
+/**
+ * Default NeuroLink API info
+ */
+export const NeuroLinkApiInfo = createApiInfo("NeuroLink API", "1.0.0", `
+NeuroLink Server API provides a unified interface to access AI capabilities
+through multiple providers. This API supports:
+
+- **Agent Execution**: Run AI agents with customizable parameters
+- **Streaming**: Real-time streaming responses via Server-Sent Events
+- **Tool Management**: Discover and execute tools from MCP servers
+- **Memory Management**: Conversation session and context management
+- **MCP Integration**: Manage external Model Context Protocol servers
+
+## Authentication
+
+The API supports multiple authentication methods:
+- **Bearer Token**: JWT tokens in the Authorization header
+- **API Key**: API key via X-API-Key header
+- **Basic Auth**: HTTP Basic authentication
+
+## Rate Limiting
+
+Default rate limits apply to all endpoints:
+- 100 requests per 15-minute window
+- Custom limits may apply to specific endpoints
+
+## Errors
+
+All errors follow a consistent format with error code, message, and optional details.
+`.trim(), {
+    contact: {
+        name: "NeuroLink Team",
+        url: "https://github.com/juspay/neurolink",
+    },
+    license: {
+        name: "Apache 2.0",
+        url: "https://www.apache.org/licenses/LICENSE-2.0",
+    },
+});

package/dist/client/server/routes/agentRoutes.js

@@ -0,0 +1,171 @@
+/**
+ * Agent Routes
+ * Endpoints for agent execution and streaming
+ */
+import { ProviderFactory } from "../../factories/providerFactory.js";
+import { createStreamRedactor } from "../utils/redaction.js";
+import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, validateRequest, } from "../utils/validation.js";
+/**
+ * Create agent routes
+ */
+export function createAgentRoutes(basePath = "/api") {
+    return {
+        prefix: `${basePath}/agent`,
+        routes: [
+            {
+                method: "POST",
+                path: `${basePath}/agent/execute`,
+                handler: async (ctx) => {
+                    // Validate request body
+                    const validation = validateRequest(AgentExecuteRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const request = validation.data;
+                    // Normalize input
+                    const input = typeof request.input === "string"
+                        ? { text: request.input }
+                        : request.input;
+                    const result = await ctx.neurolink.generate({
+                        input,
+                        provider: request.provider,
+                        model: request.model,
+                        systemPrompt: request.systemPrompt,
+                        temperature: request.temperature,
+                        maxTokens: request.maxTokens,
+                        // Note: tools should be passed as Record<string, Tool> in generate options
+                        // If request.tools is an array of tool names, we skip them
+                        context: {
+                            sessionId: request.sessionId,
+                            userId: request.userId,
+                        },
+                    });
+                    // Map tool calls from SDK format to API format
+                    const toolCalls = result.toolCalls?.map((tc) => ({
+                        name: tc.toolName,
+                        arguments: tc.args,
+                    }));
+                    return {
+                        content: result.content || "",
+                        provider: result.provider || request.provider || "unknown",
+                        model: result.model || request.model || "unknown",
+                        usage: result.usage,
+                        toolCalls,
+                    };
+                },
+                description: "Execute agent with prompt",
+                tags: ["agent"],
+            },
+            {
+                method: "POST",
+                path: `${basePath}/agent/stream`,
+                streaming: { enabled: true, contentType: "text/event-stream" },
+                handler: async (ctx) => {
+                    // Validate request body
+                    const validation = validateRequest(AgentExecuteRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const request = validation.data;
+                    // Normalize input
+                    const input = typeof request.input === "string"
+                        ? { text: request.input }
+                        : request.input;
+                    const result = await ctx.neurolink.stream({
+                        input,
+                        provider: request.provider,
+                        model: request.model,
+                        systemPrompt: request.systemPrompt,
+                        temperature: request.temperature,
+                        maxTokens: request.maxTokens,
+                    });
+                    // Create redactor (no-op if redaction is not enabled)
+                    const redactor = createStreamRedactor(ctx.redaction);
+                    // Wrap stream to apply redaction to each chunk
+                    async function* redactedStream() {
+                        for await (const chunk of result.stream) {
+                            // Apply redaction to chunk (returns unchanged if redaction disabled)
+                            yield redactor(chunk);
+                        }
+                    }
+                    return redactedStream();
+                },
+                description: "Stream agent response",
+                tags: ["agent", "streaming"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/agent/providers`,
+                handler: async () => {
+                    // Get available providers dynamically from ProviderFactory
+                    const providers = ProviderFactory.getAvailableProviders();
+                    return {
+                        providers,
+                        total: providers.length,
+                    };
+                },
+                description: "List available AI providers",
+                tags: ["agent", "providers"],
+            },
+            {
+                method: "POST",
+                path: `${basePath}/agent/embed`,
+                handler: async (ctx) => {
+                    const validation = validateRequest(EmbedRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const request = validation.data;
+                    try {
+                        const providerName = request.provider || "openai";
+                        const provider = await ProviderFactory.createProvider(providerName, request.model);
+                        const embedding = await provider.embed(request.text, request.model);
+                        return {
+                            embedding,
+                            provider: providerName,
+                            model: request.model || "default",
+                            dimension: embedding.length,
+                        };
+                    }
+                    catch (error) {
+                        return createError("EXECUTION_FAILED", error instanceof Error
+                            ? error.message
+                            : "Embedding generation failed", undefined, ctx.requestId);
+                    }
+                },
+                description: "Generate embedding for a single text",
+                tags: ["agent", "embeddings"],
+            },
+            {
+                method: "POST",
+                path: `${basePath}/agent/embed-many`,
+                handler: async (ctx) => {
+                    const validation = validateRequest(EmbedManyRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const request = validation.data;
+                    try {
+                        const providerName = request.provider || "openai";
+                        const provider = await ProviderFactory.createProvider(providerName, request.model);
+                        const embeddings = await provider.embedMany(request.texts, request.model);
+                        return {
+                            embeddings,
+                            provider: providerName,
+                            model: request.model || "default",
+                            count: embeddings.length,
+                            dimension: embeddings[0]?.length ?? 0,
+                        };
+                    }
+                    catch (error) {
+                        return createError("EXECUTION_FAILED", error instanceof Error
+                            ? error.message
+                            : "Batch embedding generation failed", undefined, ctx.requestId);
+                    }
+                },
+                description: "Generate embeddings for multiple texts in a batch",
+                tags: ["agent", "embeddings"],
+            },
+        ],
+    };
+}