@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/observability/types/exporterTypes.js

@@ -0,0 +1,5 @@
+/**
+ * Exporter configuration types
+ * Following NeuroLink's type conventions
+ */
+export {};

package/dist/client/observability/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Observability types exports
+ */
+export { AGENT_ATTRIBUTES, GENAI_ATTRIBUTES, SpanStatus, SpanType, } from "./spanTypes.js";

package/dist/client/observability/types/spanTypes.js

@@ -0,0 +1,92 @@
+/**
+ * AI-specific span types and data structures
+ * Following OpenTelemetry GenAI semantic conventions
+ */
+/**
+ * Span types for AI operations
+ * Following Mastra's span categorization and OTel GenAI conventions
+ */
+export var SpanType;
+(function (SpanType) {
+    /** Agent execution run (reserved for future multi-agent support) */
+    SpanType["AGENT_RUN"] = "agent.run";
+    /** Workflow step execution (reserved for future workflow engine) */
+    SpanType["WORKFLOW_STEP"] = "workflow.step";
+    /** Tool/function call */
+    SpanType["TOOL_CALL"] = "tool.call";
+    /** LLM generation request */
+    SpanType["MODEL_GENERATION"] = "model.generation";
+    /** Embedding generation (reserved for future embedding API) */
+    SpanType["EMBEDDING"] = "embedding";
+    /** Retrieval operation (reserved for future RAG support) */
+    SpanType["RETRIEVAL"] = "retrieval";
+    /** Memory operation */
+    SpanType["MEMORY"] = "memory";
+    /** Context compaction operation */
+    SpanType["CONTEXT_COMPACTION"] = "context.compaction";
+    /** RAG pipeline operation */
+    SpanType["RAG"] = "rag";
+    /** Evaluation/scoring operation */
+    SpanType["EVALUATION"] = "evaluation";
+    /** MCP transport operation */
+    SpanType["MCP_TRANSPORT"] = "mcp.transport";
+    /** Media generation (image/video) */
+    SpanType["MEDIA_GENERATION"] = "media.generation";
+    /** PPT/presentation generation */
+    SpanType["PPT_GENERATION"] = "ppt.generation";
+    /** Workflow execution */
+    SpanType["WORKFLOW"] = "workflow";
+    /** TTS synthesis */
+    SpanType["TTS"] = "tts";
+    /** Server adapter request */
+    SpanType["SERVER_REQUEST"] = "server.request";
+    /** Custom span */
+    SpanType["CUSTOM"] = "custom";
+})(SpanType || (SpanType = {}));
+/**
+ * Span status codes (following OTel conventions)
+ */
+export var SpanStatus;
+(function (SpanStatus) {
+    SpanStatus[SpanStatus["UNSET"] = 0] = "UNSET";
+    SpanStatus[SpanStatus["OK"] = 1] = "OK";
+    SpanStatus[SpanStatus["ERROR"] = 2] = "ERROR";
+})(SpanStatus || (SpanStatus = {}));
+/**
+ * OpenTelemetry GenAI semantic conventions
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+export const GENAI_ATTRIBUTES = {
+    // System and model identification
+    GEN_AI_SYSTEM: "gen_ai.system",
+    GEN_AI_REQUEST_MODEL: "gen_ai.request.model",
+    GEN_AI_RESPONSE_MODEL: "gen_ai.response.model",
+    // Token usage
+    GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+    GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+    GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens",
+    // Request parameters
+    GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature",
+    GEN_AI_REQUEST_TOP_P: "gen_ai.request.top_p",
+    GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
+    GEN_AI_REQUEST_STOP_SEQUENCES: "gen_ai.request.stop_sequences",
+    // Response metadata
+    GEN_AI_RESPONSE_FINISH_REASON: "gen_ai.response.finish_reasons",
+    GEN_AI_RESPONSE_ID: "gen_ai.response.id",
+    // Tool/function calling
+    GEN_AI_TOOL_NAME: "gen_ai.tool.name",
+    GEN_AI_TOOL_CALL_ID: "gen_ai.tool.call_id",
+    // Prompts and completions (optional, privacy-sensitive)
+    GEN_AI_PROMPT: "gen_ai.prompt",
+    GEN_AI_COMPLETION: "gen_ai.completion",
+};
+/**
+ * Agent-specific conventions (emerging standard)
+ */
+export const AGENT_ATTRIBUTES = {
+    AGENT_NAME: "gen_ai.agent.name",
+    AGENT_STEP_TYPE: "gen_ai.agent.step_type",
+    AGENT_TOOL_CALLS: "gen_ai.agent.tool_calls",
+    AGENT_MEMORY_ACCESS: "gen_ai.agent.memory_access",
+    AGENT_REASONING_TRACE: "gen_ai.agent.reasoning_trace",
+};

package/dist/client/observability/utils/safeMetadata.js

@@ -0,0 +1,25 @@
+/**
+ * Safe metadata filtering for observability exporters.
+ *
+ * Only these attribute keys are forwarded to third-party backends as trace
+ * metadata. User prompts (input), LLM responses (output), error stacks, and
+ * any other potentially sensitive data are excluded to prevent PII leaks.
+ */
+// Only ai.* keys are forwarded as metadata. Stream metrics (chunk_count,
+// content_length) should be accessed via span attributes directly, not via
+// metadata sent to third-party backends.
+export const SAFE_METADATA_KEYS = new Set([
+    "ai.provider",
+    "ai.model",
+    "ai.temperature",
+    "ai.max_tokens",
+]);
+export function filterSafeMetadata(attributes) {
+    const filtered = {};
+    for (const key of SAFE_METADATA_KEYS) {
+        if (attributes[key] !== undefined) {
+            filtered[key] = attributes[key];
+        }
+    }
+    return filtered;
+}

package/dist/client/observability/utils/spanSerializer.js

@@ -0,0 +1,292 @@
+/**
+ * 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,
+            // Only pick safe, non-PII attributes for metadata — intentionally excludes
+            // error.stack and other internal fields. input/output are exported here for
+            // Langfuse tracing; use LangfuseExporterConfig.redactIO=true to suppress them
+            // in compliance-sensitive deployments.
+            metadata: filterSafeMetadata(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",
+        });
+    }
+}
+// Safe metadata filtering imported from shared module to avoid duplication
+import { filterSafeMetadata } from "./safeMetadata.js";