@juspay/neurolink 9.24.0 → 9.25.0

package/dist/observability/utils/spanSerializer.js

@@ -0,0 +1,286 @@
+/**
+ * Utility class for span creation and serialization
+ * Handles conversion between NeuroLink's span format and platform-specific formats
+ */
+import { randomBytes } from "node:crypto";
+import { SpanStatus, SpanType, } from "../types/index.js";
+/**
+ * Utility class for span creation and serialization
+ */
+export class SpanSerializer {
+    /**
+     * Create a new span with generated IDs
+     */
+    static createSpan(type, name, attributes = {}, parentSpanId, traceId) {
+        return {
+            spanId: randomBytes(8).toString("hex"),
+            traceId: traceId ?? randomBytes(16).toString("hex"),
+            parentSpanId,
+            type,
+            name,
+            startTime: new Date().toISOString(),
+            status: SpanStatus.UNSET,
+            attributes: attributes,
+            events: [],
+            links: [],
+        };
+    }
+    /**
+     * End a span with status
+     */
+    static endSpan(span, status = SpanStatus.OK, statusMessage) {
+        const endTime = new Date();
+        const startTime = new Date(span.startTime);
+        return {
+            ...span,
+            endTime: endTime.toISOString(),
+            durationMs: endTime.getTime() - startTime.getTime(),
+            status,
+            statusMessage,
+        };
+    }
+    /**
+     * Add event to span
+     */
+    static addEvent(span, name, attributes) {
+        const event = {
+            name,
+            timestamp: new Date().toISOString(),
+            attributes,
+        };
+        return {
+            ...span,
+            events: [...span.events, event],
+        };
+    }
+    /**
+     * Update span attributes
+     */
+    static updateAttributes(span, attributes) {
+        return {
+            ...span,
+            attributes: {
+                ...span.attributes,
+                ...attributes,
+            },
+        };
+    }
+    /**
+     * Serialize span to JSON for export
+     */
+    static toJSON(span) {
+        return JSON.stringify(span, null, 2);
+    }
+    /**
+     * Instance method to serialize a span object to JSON string
+     * @param span - The span data to serialize (can be partial span data)
+     * @returns JSON string representation of the span
+     */
+    serialize(span) {
+        return JSON.stringify(span, null, 2);
+    }
+    /**
+     * Instance method to deserialize a JSON string to span data
+     * @param json - The JSON string to parse
+     * @returns Parsed span data
+     */
+    deserialize(json) {
+        return JSON.parse(json);
+    }
+    /**
+     * Parse span from JSON
+     */
+    static fromJSON(json) {
+        return JSON.parse(json);
+    }
+    /**
+     * Serialize span for Langfuse format
+     */
+    static toLangfuseFormat(span) {
+        return {
+            id: span.spanId,
+            traceId: span.traceId,
+            parentObservationId: span.parentSpanId,
+            name: span.name,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            metadata: { ...span.attributes },
+            level: span.status === SpanStatus.ERROR ? "ERROR" : "DEFAULT",
+            statusMessage: span.statusMessage,
+            input: span.attributes["input"],
+            output: span.attributes["output"],
+            usage: span.attributes["ai.tokens.total"] !== undefined
+                ? {
+                    promptTokens: span.attributes["ai.tokens.input"],
+                    completionTokens: span.attributes["ai.tokens.output"],
+                    totalTokens: span.attributes["ai.tokens.total"],
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Serialize span for LangSmith format
+     */
+    static toLangSmithFormat(span) {
+        return {
+            id: span.spanId,
+            trace_id: span.traceId,
+            parent_run_id: span.parentSpanId,
+            name: span.name,
+            run_type: SpanSerializer.mapSpanTypeToLangSmithRunType(span.type),
+            start_time: span.startTime,
+            end_time: span.endTime,
+            extra: { ...span.attributes },
+            error: span.status === SpanStatus.ERROR ? span.statusMessage : undefined,
+            inputs: span.attributes["input"],
+            outputs: span.attributes["output"],
+            tags: SpanSerializer.extractTags(span.attributes),
+        };
+    }
+    /**
+     * Serialize span for OpenTelemetry format
+     */
+    static toOtelFormat(span) {
+        return {
+            traceId: span.traceId,
+            spanId: span.spanId,
+            parentSpanId: span.parentSpanId,
+            name: span.name,
+            kind: 1, // SPAN_KIND_INTERNAL
+            startTimeUnixNano: new Date(span.startTime).getTime() * 1_000_000,
+            endTimeUnixNano: span.endTime
+                ? new Date(span.endTime).getTime() * 1_000_000
+                : undefined,
+            attributes: Object.entries(span.attributes)
+                .filter(([, value]) => value !== undefined)
+                .map(([key, value]) => ({
+                key,
+                value: SpanSerializer.toOtelAttributeValue(value),
+            })),
+            status: {
+                code: span.status,
+                message: span.statusMessage,
+            },
+            events: span.events.map((e) => ({
+                name: e.name,
+                timeUnixNano: new Date(e.timestamp).getTime() * 1_000_000,
+                attributes: e.attributes
+                    ? Object.entries(e.attributes).map(([k, v]) => ({
+                        key: k,
+                        value: SpanSerializer.toOtelAttributeValue(v),
+                    }))
+                    : [],
+            })),
+        };
+    }
+    /**
+     * Convert value to OTel attribute value format
+     */
+    static toOtelAttributeValue(value) {
+        if (typeof value === "string") {
+            return { stringValue: value };
+        }
+        if (typeof value === "number") {
+            return Number.isInteger(value)
+                ? { intValue: value }
+                : { stringValue: String(value) };
+        }
+        if (typeof value === "boolean") {
+            return { boolValue: value };
+        }
+        return { stringValue: JSON.stringify(value) };
+    }
+    /**
+     * Map NeuroLink span type to LangSmith run type
+     */
+    static mapSpanTypeToLangSmithRunType(type) {
+        const mapping = {
+            [SpanType.AGENT_RUN]: "chain",
+            [SpanType.WORKFLOW_STEP]: "chain",
+            [SpanType.TOOL_CALL]: "tool",
+            [SpanType.MODEL_GENERATION]: "llm",
+            [SpanType.EMBEDDING]: "embedding",
+            [SpanType.RETRIEVAL]: "retriever",
+            [SpanType.MEMORY]: "chain",
+            [SpanType.CONTEXT_COMPACTION]: "chain",
+            [SpanType.RAG]: "retriever",
+            [SpanType.EVALUATION]: "chain",
+            [SpanType.MCP_TRANSPORT]: "tool",
+            [SpanType.MEDIA_GENERATION]: "llm",
+            [SpanType.PPT_GENERATION]: "chain",
+            [SpanType.WORKFLOW]: "chain",
+            [SpanType.TTS]: "chain",
+            [SpanType.SERVER_REQUEST]: "chain",
+            [SpanType.CUSTOM]: "chain",
+        };
+        return mapping[type] || "chain";
+    }
+    /**
+     * Extract tags from span attributes for LangSmith
+     */
+    static extractTags(attributes) {
+        const tags = [];
+        if (attributes["ai.provider"]) {
+            tags.push(`provider:${attributes["ai.provider"]}`);
+        }
+        if (attributes["ai.model"]) {
+            tags.push(`model:${attributes["ai.model"]}`);
+        }
+        if (attributes["deployment.environment"]) {
+            tags.push(`env:${attributes["deployment.environment"]}`);
+        }
+        if (attributes["tool.name"]) {
+            tags.push(`tool:${attributes["tool.name"]}`);
+        }
+        return tags;
+    }
+    /**
+     * Create a generation span with AI-specific attributes
+     */
+    static createGenerationSpan(params) {
+        return SpanSerializer.createSpan(SpanType.MODEL_GENERATION, params.name ?? `gen_ai.${params.provider}.chat`, {
+            "ai.provider": params.provider,
+            "ai.model": params.model,
+            "ai.temperature": params.temperature,
+            "ai.max_tokens": params.maxTokens,
+            input: params.input,
+            "user.id": params.userId,
+            "session.id": params.sessionId,
+        }, params.parentSpanId, params.traceId);
+    }
+    /**
+     * Create a tool call span
+     */
+    static createToolCallSpan(params) {
+        return SpanSerializer.createSpan(SpanType.TOOL_CALL, `tool.${params.toolName}`, {
+            "tool.name": params.toolName,
+            "tool.server": params.server,
+            input: params.input,
+        }, params.parentSpanId, params.traceId);
+    }
+    /**
+     * Enrich span with token usage
+     */
+    static enrichWithTokenUsage(span, usage) {
+        return SpanSerializer.updateAttributes(span, {
+            "ai.tokens.input": usage.promptTokens ?? 0,
+            "ai.tokens.output": usage.completionTokens ?? 0,
+            "ai.tokens.total": usage.totalTokens ??
+                (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0),
+            "ai.tokens.cache_creation": usage.cacheCreationTokens,
+            "ai.tokens.cache_read": usage.cacheReadTokens,
+            "ai.tokens.reasoning": usage.reasoningTokens,
+        });
+    }
+    /**
+     * Enrich span with cost information
+     */
+    static enrichWithCost(span, cost) {
+        return SpanSerializer.updateAttributes(span, {
+            "ai.cost.input": cost.inputCost,
+            "ai.cost.output": cost.outputCost,
+            "ai.cost.total": cost.totalCost,
+            "ai.cost.currency": cost.currency ?? "USD",
+        });
+    }
+}

package/dist/providers/amazonSagemaker.d.ts

@@ -4,11 +4,12 @@
  * This module provides a simplified SageMaker provider that extends BaseProvider
  * and integrates with the NeuroLink ecosystem using existing patterns.
  */
+import type { LanguageModelV1, Schema } from "ai";
 import type { ZodType, ZodTypeDef } from "zod";
-import type { Schema, LanguageModelV1 } from "ai";
-import { AIProviderName } from "../constants/enums.js";
-import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
+import type { AIProviderName } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
+import type { NeuroLink } from "../neurolink.js";
+import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
 /**
  * Amazon SageMaker Provider extending BaseProvider
  */
@@ -16,7 +17,7 @@ export declare class AmazonSageMakerProvider extends BaseProvider {
     private sagemakerModel;
     private sagemakerConfig;
     private modelConfig;
-    constructor(modelName?: string, endpointName?: string, region?: string);
+    constructor(modelName?: string, endpointName?: string, region?: string, neurolink?: NeuroLink);
     protected getProviderName(): AIProviderName;
     protected getDefaultModel(): string;
     protected getAISDKModel(): LanguageModelV1;

package/dist/providers/amazonSagemaker.js

@@ -4,11 +4,10 @@
  * This module provides a simplified SageMaker provider that extends BaseProvider
  * and integrates with the NeuroLink ecosystem using existing patterns.
  */
-import { AIProviderName } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { logger } from "../utils/logger.js";
 // SageMaker-specific imports
-import { getSageMakerConfig, getSageMakerModelConfig, getDefaultSageMakerEndpoint, getSageMakerModel, } from "./sagemaker/config.js";
+import { getDefaultSageMakerEndpoint, getSageMakerConfig, getSageMakerModel, getSageMakerModelConfig, } from "./sagemaker/config.js";
 import { handleSageMakerError, SageMakerError } from "./sagemaker/errors.js";
 import { SageMakerLanguageModel } from "./sagemaker/language-model.js";
 /**
@@ -18,8 +17,8 @@ export class AmazonSageMakerProvider extends BaseProvider {
     sagemakerModel;
     sagemakerConfig;
     modelConfig;
-    constructor(modelName, endpointName, region) {
-        super(modelName, "sagemaker");
+    constructor(modelName, endpointName, region, neurolink) {
+        super(modelName, "sagemaker", neurolink);
         try {
             // Load and validate configuration
             this.sagemakerConfig = getSageMakerConfig(region);

package/dist/providers/googleVertex.d.ts

@@ -130,6 +130,13 @@ export declare class GoogleVertexProvider extends BaseProvider {
      * Shared by both stream and generate native Gemini 3 paths.
      */
     private buildNativeContentParts;
+    /**
+     * Convert conversationMessages from NeuroLink's ChatMessage format into
+     * the @google/genai contents format and prepend them before the current
+     * user message. This gives the native Gemini 3 path multi-turn context
+     * that was previously dropped (only the current prompt was sent).
+     */
+    private prependConversationHistory;
     /**
      * Execute stream using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature

package/dist/providers/googleVertex.js

@@ -1140,6 +1140,33 @@ export class GoogleVertexProvider extends BaseProvider {
             },
         ];
     }
+    /**
+     * Convert conversationMessages from NeuroLink's ChatMessage format into
+     * the @google/genai contents format and prepend them before the current
+     * user message. This gives the native Gemini 3 path multi-turn context
+     * that was previously dropped (only the current prompt was sent).
+     */
+    prependConversationHistory(currentContents, conversationMessages) {
+        if (!conversationMessages || conversationMessages.length === 0) {
+            return currentContents;
+        }
+        const history = [];
+        for (const msg of conversationMessages) {
+            // @google/genai only accepts "user" and "model" roles in contents.
+            // Skip system messages (handled via config.systemInstruction).
+            // Map "assistant" → "model" (Gemini convention).
+            const role = msg.role === "assistant" ? "model" : msg.role;
+            if (role !== "user" && role !== "model") {
+                continue;
+            }
+            if (!msg.content || msg.content.trim().length === 0) {
+                continue;
+            }
+            history.push({ role, parts: [{ text: msg.content }] });
+        }
+        // Prepend history before current user message
+        return [...history, ...currentContents];
+    }
     // ── Shared Gemini 3 helpers are now in ./googleNativeGemini3.ts ──
     /**
      * Execute stream using native @google/genai SDK for Gemini 3 models on Vertex AI
@@ -1192,6 +1219,13 @@ export class GoogleVertexProvider extends BaseProvider {
             }
             // Build config
             const config = buildNativeConfig(options, toolsConfig);
+            // Global endpoint rejects systemInstruction for Gemini 3.x —
+            // move it into a prefixed user message (same fix as generate path)
+            let streamSystemPreamble;
+            if (effectiveLocation === "global" && config.systemInstruction) {
+                streamSystemPreamble = config.systemInstruction;
+                delete config.systemInstruction;
+            }
             // Add JSON output format support for native SDK stream
             if (streamOptions.output?.format === "json" || streamOptions.schema) {
                 config.responseMimeType = "application/json";
@@ -1212,7 +1246,26 @@ export class GoogleVertexProvider extends BaseProvider {
             const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
             const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
             const maxSteps = computeMaxStepsShared(options.maxSteps);
-            const currentContents = [...contents];
+            // Inject conversation history so the native path has multi-turn context
+            let currentContents = this.prependConversationHistory([...contents], options.conversationMessages);
+            // Prepend system prompt as a user message for the global endpoint
+            if (streamSystemPreamble) {
+                currentContents = [
+                    {
+                        role: "user",
+                        parts: [
+                            { text: `[System Instructions]\n${streamSystemPreamble}` },
+                        ],
+                    },
+                    {
+                        role: "model",
+                        parts: [
+                            { text: "Understood. I will follow these instructions." },
+                        ],
+                    },
+                    ...currentContents,
+                ];
+            }
             let finalText = "";
             let lastStepText = "";
             let totalInputTokens = 0;
@@ -1355,6 +1408,14 @@ export class GoogleVertexProvider extends BaseProvider {
             }
             // Build config
             const config = buildNativeConfig(options, toolsConfig);
+            // Global endpoint rejects systemInstruction for Gemini 3.x, returning
+            // "Please use a valid role: user, model." Move it into a prefixed
+            // user message so the model still receives the system context.
+            let systemPreamble;
+            if (effectiveLocation === "global" && config.systemInstruction) {
+                systemPreamble = config.systemInstruction;
+                delete config.systemInstruction;
+            }
             // Note: Schema/JSON output for Gemini 3 native SDK is complex due to $ref resolution issues
             // For now, schemas are handled via the AI SDK fallback path, not native SDK
             // TODO: Implement proper $ref resolution for complex nested schemas
@@ -1363,7 +1424,24 @@ export class GoogleVertexProvider extends BaseProvider {
             const timeoutController = createTimeoutController(timeout, this.providerName, "generate");
             const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
             const maxSteps = computeMaxStepsShared(options.maxSteps);
-            const currentContents = [...contents];
+            // Inject conversation history so the native path has multi-turn context
+            let currentContents = this.prependConversationHistory([...contents], options.conversationMessages);
+            // Prepend system prompt as a user message for the global endpoint
+            if (systemPreamble) {
+                currentContents = [
+                    {
+                        role: "user",
+                        parts: [{ text: `[System Instructions]\n${systemPreamble}` }],
+                    },
+                    {
+                        role: "model",
+                        parts: [
+                            { text: "Understood. I will follow these instructions." },
+                        ],
+                    },
+                    ...currentContents,
+                ];
+            }
             let finalText = "";
             let lastStepText = "";
             let totalInputTokens = 0;

package/dist/rag/pipeline/RAGPipeline.d.ts

@@ -34,11 +34,6 @@ export type { IngestOptions } from "../../types/ragTypes.js";
 export type { QueryOptions } from "../../types/ragTypes.js";
 export type { RAGResponse } from "../../types/ragTypes.js";
 export type { PipelineStats } from "../../types/ragTypes.js";
-/**
- * RAG Pipeline Orchestrator
- *
- * Complete end-to-end pipeline for Retrieval-Augmented Generation.
- */
 export declare class RAGPipeline {
     private id;
     private config;