@juspay/neurolink 9.24.0 → 9.25.1

package/dist/lib/observability/types/spanTypes.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 declare enum SpanType {
+    /** Agent execution run (reserved for future multi-agent support) */
+    AGENT_RUN = "agent.run",
+    /** Workflow step execution (reserved for future workflow engine) */
+    WORKFLOW_STEP = "workflow.step",
+    /** Tool/function call */
+    TOOL_CALL = "tool.call",
+    /** LLM generation request */
+    MODEL_GENERATION = "model.generation",
+    /** Embedding generation (reserved for future embedding API) */
+    EMBEDDING = "embedding",
+    /** Retrieval operation (reserved for future RAG support) */
+    RETRIEVAL = "retrieval",
+    /** Memory operation */
+    MEMORY = "memory",
+    /** Context compaction operation */
+    CONTEXT_COMPACTION = "context.compaction",
+    /** RAG pipeline operation */
+    RAG = "rag",
+    /** Evaluation/scoring operation */
+    EVALUATION = "evaluation",
+    /** MCP transport operation */
+    MCP_TRANSPORT = "mcp.transport",
+    /** Media generation (image/video) */
+    MEDIA_GENERATION = "media.generation",
+    /** PPT/presentation generation */
+    PPT_GENERATION = "ppt.generation",
+    /** Workflow execution */
+    WORKFLOW = "workflow",
+    /** TTS synthesis */
+    TTS = "tts",
+    /** Server adapter request */
+    SERVER_REQUEST = "server.request",
+    /** Custom span */
+    CUSTOM = "custom"
+}
+/**
+ * Span status codes (following OTel conventions)
+ */
+export declare enum SpanStatus {
+    UNSET = 0,
+    OK = 1,
+    ERROR = 2
+}
+/**
+ * OpenTelemetry GenAI semantic conventions
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+export declare const GENAI_ATTRIBUTES: {
+    readonly GEN_AI_SYSTEM: "gen_ai.system";
+    readonly GEN_AI_REQUEST_MODEL: "gen_ai.request.model";
+    readonly GEN_AI_RESPONSE_MODEL: "gen_ai.response.model";
+    readonly GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+    readonly GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature";
+    readonly GEN_AI_REQUEST_TOP_P: "gen_ai.request.top_p";
+    readonly GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens";
+    readonly GEN_AI_REQUEST_STOP_SEQUENCES: "gen_ai.request.stop_sequences";
+    readonly GEN_AI_RESPONSE_FINISH_REASON: "gen_ai.response.finish_reasons";
+    readonly GEN_AI_RESPONSE_ID: "gen_ai.response.id";
+    readonly GEN_AI_TOOL_NAME: "gen_ai.tool.name";
+    readonly GEN_AI_TOOL_CALL_ID: "gen_ai.tool.call_id";
+    readonly GEN_AI_PROMPT: "gen_ai.prompt";
+    readonly GEN_AI_COMPLETION: "gen_ai.completion";
+};
+/**
+ * Agent-specific conventions (emerging standard)
+ */
+export declare const AGENT_ATTRIBUTES: {
+    readonly AGENT_NAME: "gen_ai.agent.name";
+    readonly AGENT_STEP_TYPE: "gen_ai.agent.step_type";
+    readonly AGENT_TOOL_CALLS: "gen_ai.agent.tool_calls";
+    readonly AGENT_MEMORY_ACCESS: "gen_ai.agent.memory_access";
+    readonly AGENT_REASONING_TRACE: "gen_ai.agent.reasoning_trace";
+};
+/**
+ * Span attributes with AI-specific fields
+ */
+export type SpanAttributes = {
+    "service.name"?: string;
+    "service.version"?: string;
+    "deployment.environment"?: string;
+    "user.id"?: string;
+    "session.id"?: string;
+    "ai.provider"?: string;
+    "ai.model"?: string;
+    "ai.model.version"?: string;
+    "ai.tokens.input"?: number;
+    "ai.tokens.output"?: number;
+    "ai.tokens.total"?: number;
+    "ai.tokens.cache_read"?: number;
+    "ai.tokens.cache_creation"?: number;
+    "ai.tokens.reasoning"?: number;
+    "ai.cost.input"?: number;
+    "ai.cost.output"?: number;
+    "ai.cost.total"?: number;
+    "ai.cost.currency"?: string;
+    "ai.temperature"?: number;
+    "ai.max_tokens"?: number;
+    "ai.top_p"?: number;
+    "ai.stop_sequences"?: string[];
+    "tool.name"?: string;
+    "tool.server"?: string;
+    "tool.success"?: boolean;
+    "error.type"?: string;
+    "error.message"?: string;
+    "error.stack"?: string;
+    error?: boolean;
+    input?: unknown;
+    output?: unknown;
+    expected?: unknown;
+    scores?: Record<string, number>;
+    [key: string]: unknown;
+};
+/**
+ * Span event for recording discrete occurrences
+ */
+export type SpanEvent = {
+    name: string;
+    timestamp: string;
+    attributes?: Record<string, unknown>;
+};
+/**
+ * Link to related span
+ */
+export type SpanLink = {
+    traceId: string;
+    spanId: string;
+    attributes?: Record<string, unknown>;
+};
+/**
+ * Complete span data structure
+ */
+export type SpanData = {
+    /** Unique span identifier */
+    spanId: string;
+    /** Trace identifier for distributed tracing */
+    traceId: string;
+    /** Parent span ID for nested operations */
+    parentSpanId?: string;
+    /** Span type category */
+    type: SpanType;
+    /** Human-readable span name */
+    name: string;
+    /** Start timestamp (ISO 8601) */
+    startTime: string;
+    /** End timestamp (ISO 8601) */
+    endTime?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Span status */
+    status: SpanStatus;
+    /** Status message (for errors) */
+    statusMessage?: string;
+    /** Span attributes/tags */
+    attributes: SpanAttributes;
+    /** Events within the span */
+    events: SpanEvent[];
+    /** Links to related spans */
+    links: SpanLink[];
+};
+/**
+ * Langfuse-specific span format
+ */
+export type LangfuseSpan = {
+    id: string;
+    traceId: string;
+    parentObservationId?: string;
+    name: string;
+    startTime: string;
+    endTime?: string;
+    metadata: Record<string, unknown>;
+    level: "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+    statusMessage?: string;
+    input?: unknown;
+    output?: unknown;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+};
+/**
+ * LangSmith-specific run format
+ */
+export type LangSmithRun = {
+    id: string;
+    trace_id: string;
+    parent_run_id?: string;
+    name: string;
+    run_type: "llm" | "chain" | "tool" | "retriever" | "embedding";
+    start_time: string;
+    end_time?: string;
+    extra: Record<string, unknown>;
+    error?: string;
+    inputs?: unknown;
+    outputs?: unknown;
+    tags?: string[];
+};
+/**
+ * OpenTelemetry span format
+ */
+export type OtelSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: number;
+    endTimeUnixNano?: number;
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+            intValue?: number;
+            boolValue?: boolean;
+        };
+    }>;
+    status: {
+        code: number;
+        message?: string;
+    };
+    events: Array<{
+        name: string;
+        timeUnixNano: number;
+        attributes: Array<{
+            key: string;
+            value: {
+                stringValue?: string;
+                intValue?: number;
+                boolValue?: boolean;
+            };
+        }>;
+    }>;
+};

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

@@ -0,0 +1,93 @@
+/**
+ * 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",
+};
+//# sourceMappingURL=spanTypes.js.map

package/dist/lib/observability/utils/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Observability utilities exports
+ */
+export { SpanSerializer } from "./spanSerializer.js";

package/dist/lib/observability/utils/index.js

@@ -0,0 +1,5 @@
+/**
+ * Observability utilities exports
+ */
+export { SpanSerializer } from "./spanSerializer.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/observability/utils/safeMetadata.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+import type { SpanAttributes } from "../types/spanTypes.js";
+export declare const SAFE_METADATA_KEYS: Set<string>;
+export declare function filterSafeMetadata(attributes: SpanAttributes): Record<string, unknown>;

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

@@ -0,0 +1,26 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=safeMetadata.js.map

package/dist/lib/observability/utils/spanSerializer.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Utility class for span creation and serialization
+ * Handles conversion between NeuroLink's span format and platform-specific formats
+ */
+import { type LangfuseSpan, type LangSmithRun, type OtelSpan, type SpanAttributes, type SpanData, SpanStatus, SpanType } from "../types/index.js";
+/**
+ * Utility class for span creation and serialization
+ */
+export declare class SpanSerializer {
+    /**
+     * Create a new span with generated IDs
+     */
+    static createSpan(type: SpanType, name: string, attributes?: Partial<SpanAttributes>, parentSpanId?: string, traceId?: string): SpanData;
+    /**
+     * End a span with status
+     */
+    static endSpan(span: SpanData, status?: SpanStatus, statusMessage?: string): SpanData;
+    /**
+     * Add event to span
+     */
+    static addEvent(span: SpanData, name: string, attributes?: Record<string, unknown>): SpanData;
+    /**
+     * Update span attributes
+     */
+    static updateAttributes(span: SpanData, attributes: Partial<SpanAttributes>): SpanData;
+    /**
+     * Serialize span to JSON for export
+     */
+    static toJSON(span: SpanData): string;
+    /**
+     * 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: Partial<SpanData> | Record<string, unknown>): string;
+    /**
+     * Instance method to deserialize a JSON string to span data
+     * @param json - The JSON string to parse
+     * @returns Parsed span data
+     */
+    deserialize(json: string): SpanData;
+    /**
+     * Parse span from JSON
+     */
+    static fromJSON(json: string): SpanData;
+    /**
+     * Serialize span for Langfuse format
+     */
+    static toLangfuseFormat(span: SpanData): LangfuseSpan;
+    /**
+     * Serialize span for LangSmith format
+     */
+    static toLangSmithFormat(span: SpanData): LangSmithRun;
+    /**
+     * Serialize span for OpenTelemetry format
+     */
+    static toOtelFormat(span: SpanData): OtelSpan;
+    /**
+     * Convert value to OTel attribute value format
+     */
+    private static toOtelAttributeValue;
+    /**
+     * Map NeuroLink span type to LangSmith run type
+     */
+    private static mapSpanTypeToLangSmithRunType;
+    /**
+     * Extract tags from span attributes for LangSmith
+     */
+    private static extractTags;
+    /**
+     * Create a generation span with AI-specific attributes
+     */
+    static createGenerationSpan(params: {
+        provider: string;
+        model: string;
+        name?: string;
+        parentSpanId?: string;
+        traceId?: string;
+        temperature?: number;
+        maxTokens?: number;
+        input?: unknown;
+        userId?: string;
+        sessionId?: string;
+    }): SpanData;
+    /**
+     * Create a tool call span
+     */
+    static createToolCallSpan(params: {
+        toolName: string;
+        server?: string;
+        input?: unknown;
+        parentSpanId?: string;
+        traceId?: string;
+    }): SpanData;
+    /**
+     * Enrich span with token usage
+     */
+    static enrichWithTokenUsage(span: SpanData, usage: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: number;
+        reasoningTokens?: number;
+    }): SpanData;
+    /**
+     * Enrich span with cost information
+     */
+    static enrichWithCost(span: SpanData, cost: {
+        inputCost?: number;
+        outputCost?: number;
+        totalCost: number;
+        currency?: string;
+    }): SpanData;
+}