@juspay/neurolink 8.43.0 → 9.0.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [9.0.0](https://github.com/juspay/neurolink/compare/v8.43.0...v9.0.0) (2026-02-03)
+
+### ⚠ BREAKING CHANGES
+
+- **(observability):** @opentelemetry/api, @opentelemetry/sdk-trace-node, and
+  @opentelemetry/sdk-trace-base are now peerDependencies. Host applications
+  must install these packages directly.
+
+### Features
+
+- **(observability):** add external TracerProvider support with operation name auto-detection ([25e3230](https://github.com/juspay/neurolink/commit/25e32301269b45b493df17f94b7e38af2bd7ef36))
+
 ## [8.43.0](https://github.com/juspay/neurolink/compare/v8.42.0...v8.43.0) (2026-02-02)
 
 ### Features

package/README.md

@@ -35,30 +35,32 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 ## What's New (Q1 2026)
 
-| Feature                            | Version | Description                                                                                                                                    | Guide                                                         |
-| ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| **Server Adapters**                | v8.41.0 | Multi-framework HTTP server with Hono, Express, Fastify, Koa support. Full CLI for server management with foreground/background modes.         | [Server Adapters Guide](docs/guides/server-adapters/index.md) |
-| **Title Generation Events**        | v8.38.0 | Emit `conversation:titleGenerated` event when conversation title is generated. Supports custom title prompts via `NEUROLINK_TITLE_PROMPT`.     | [Conversation Memory Guide](docs/conversation-memory.md)      |
-| **Video Generation with Veo**      | v8.32.0 | Video generation using Veo 3.1 (`veo-3.1`). Realistic video generation with many parameter options                                             | [Video Generation Guide](docs/features/video-generation.md)   |
-| **Image Generation with Gemini**   | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI. | [Image Generation Guide](docs/image-generation-streaming.md)  |
-| **HTTP/Streamable HTTP Transport** | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.  | [HTTP Transport Guide](docs/mcp-http-transport.md)            |
-
+| Feature                             | Version | Description                                                                                                                                    | Guide                                                         |
+| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **External TracerProvider Support** | v8.43.0 | Integrate NeuroLink with existing OpenTelemetry instrumentation. Prevents duplicate registration conflicts.                                    | [Observability Guide](docs/features/observability.md)         |
+| **Server Adapters**                 | v8.43.0 | Multi-framework HTTP server with Hono, Express, Fastify, Koa support. Full CLI for server management with foreground/background modes.         | [Server Adapters Guide](docs/guides/server-adapters/index.md) |
+| **Title Generation Events**         | v8.38.0 | Emit `conversation:titleGenerated` event when conversation title is generated. Supports custom title prompts via `NEUROLINK_TITLE_PROMPT`.     | [Conversation Memory Guide](docs/conversation-memory.md)      |
+| **Video Generation with Veo**       | v8.32.0 | Video generation using Veo 3.1 (`veo-3.1`). Realistic video generation with many parameter options                                             | [Video Generation Guide](docs/features/video-generation.md)   |
+| **Image Generation with Gemini**    | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI. | [Image Generation Guide](docs/image-generation-streaming.md)  |
+| **HTTP/Streamable HTTP Transport**  | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.  | [HTTP Transport Guide](docs/mcp-http-transport.md)            |
+
+- **External TracerProvider Support** – Integrate NeuroLink with applications that already have OpenTelemetry instrumentation. Supports auto-detection and manual configuration. → [Observability Guide](docs/features/observability.md)
 - **Server Adapters** – Deploy NeuroLink as an HTTP API server with your framework of choice (Hono, Express, Fastify, Koa). Full CLI support with `serve` and `server` commands for foreground/background modes, route management, and OpenAPI generation. → [Server Adapters Guide](docs/guides/server-adapters/index.md)
 - **Title Generation Events** – Emit real-time events when conversation titles are auto-generated. Listen to `conversation:titleGenerated` for session tracking. → [Conversation Memory Guide](docs/conversation-memory.md#title-generation-events)
 - **Custom Title Prompts** – Customize conversation title generation with `NEUROLINK_TITLE_PROMPT` environment variable. Use `${userMessage}` placeholder for dynamic prompts. → [Conversation Memory Guide](docs/conversation-memory.md#customizing-the-title-prompt)
 - **Video Generation** – Transform images into 8-second videos with synchronized audio using Google Veo 3.1 via Vertex AI. Supports 720p/1080p resolutions, portrait/landscape aspect ratios. → [Video Generation Guide](docs/features/video-generation.md)
-- **Image Generation** – Generate images from text prompts using Gemini models via Vertex AI or Google AI Studio. Supports streaming mode with automatic file saving. → [Image Generation Guide](docs/IMAGE-GENERATION-STREAMING.md)
-- **HTTP/Streamable HTTP Transport for MCP** – Connect to remote MCP servers via HTTP with authentication headers, retry logic, and rate limiting. → [HTTP Transport Guide](docs/MCP-HTTP-TRANSPORT.md)
+- **Image Generation** – Generate images from text prompts using Gemini models via Vertex AI or Google AI Studio. Supports streaming mode with automatic file saving. → [Image Generation Guide](docs/image-generation-streaming.md)
+- **HTTP/Streamable HTTP Transport for MCP** – Connect to remote MCP servers via HTTP with authentication headers, retry logic, and rate limiting. → [HTTP Transport Guide](docs/mcp-http-transport.md)
 - 🧠 **Gemini 3 Preview Support** - Full support for gemini-3-flash-preview and gemini-3-pro-preview with extended thinking capabilities
 - **Structured Output with Zod Schemas** – Type-safe JSON generation with automatic validation using `schema` + `output.format: "json"` in `generate()`. → [Structured Output Guide](docs/features/structured-output.md)
 - **CSV File Support** – Attach CSV files to prompts for AI-powered data analysis with auto-detection. → [CSV Guide](docs/features/multimodal-chat.md#csv-file-support)
 - **PDF File Support** – Process PDF documents with native visual analysis for Vertex AI, Anthropic, Bedrock, AI Studio. → [PDF Guide](docs/features/pdf-support.md)
-- **LiteLLM Integration** – Access 100+ AI models from all major providers through unified interface. → [Setup Guide](docs/LITELLM-INTEGRATION.md)
-- **SageMaker Integration** – Deploy and use custom trained models on AWS infrastructure. → [Setup Guide](docs/SAGEMAKER-INTEGRATION.md)
+- **LiteLLM Integration** – Access 100+ AI models from all major providers through unified interface. → [Setup Guide](docs/litellm-integration.md)
+- **SageMaker Integration** – Deploy and use custom trained models on AWS infrastructure. → [Setup Guide](docs/sagemaker-integration.md)
 - **OpenRouter Integration** – Access 300+ models from OpenAI, Anthropic, Google, Meta, and more through a single unified API. → [Setup Guide](docs/getting-started/providers/openrouter.md)
 - **Human-in-the-loop workflows** – Pause generation for user approval/input before tool execution. → [HITL Guide](docs/features/hitl.md)
 - **Guardrails middleware** – Block PII, profanity, and unsafe content with built-in filtering. → [Guardrails Guide](docs/features/guardrails.md)
-- **Context summarization** – Automatic conversation compression for long-running sessions. → [Summarization Guide](docs/CONTEXT-SUMMARIZATION.md)
+- **Context summarization** – Automatic conversation compression for long-running sessions. → [Summarization Guide](docs/context-summarization.md)
 - **Redis conversation export** – Export full session history as JSON for analytics and debugging. → [History Guide](docs/features/conversation-history.md)
 
 ```typescript

package/dist/core/modules/TelemetryHandler.d.ts

@@ -57,6 +57,8 @@ export declare class TelemetryHandler {
         isEnabled: boolean;
         functionId?: string;
         metadata?: Record<string, string | number | boolean>;
+        recordInputs?: boolean;
+        recordOutputs?: boolean;
     } | undefined;
     /**
      * Handle tool execution storage if available

package/dist/core/modules/TelemetryHandler.js

@@ -147,6 +147,8 @@ export class TelemetryHandler {
             isEnabled: true,
             functionId,
             metadata,
+            recordInputs: true,
+            recordOutputs: true,
         };
     }
     /**

package/dist/index.d.ts

@@ -42,10 +42,10 @@ export type { DynamicModelConfig, ModelRegistry } from "./types/modelTypes.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export type { MCPServerInfo } from "./types/mcpTypes.js";
-export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, } from "./types/observability.js";
+export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, LangfuseSpanAttributes, TraceNameFormat, } from "./types/observability.js";
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext } from "./services/server/ai/observability/instrumentation.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, };
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, };
 export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, MiddlewareConfig, } from "./types/middlewareTypes.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export declare const VERSION = "1.0.0";

package/dist/index.js

@@ -47,9 +47,17 @@ export { dynamicModelProvider } from "./core/dynamicModels.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, } from "./services/server/ai/observability/instrumentation.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
+// NEW EXPORTS - External TracerProvider Support
+getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Enhanced context and tracing
+getLangfuseContext, getTracer, } from "./services/server/ai/observability/instrumentation.js";
 import { initializeTelemetry as init, getTelemetryStatus as getStatus, } from "./telemetry/index.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, };
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
+// NEW EXPORTS - External TracerProvider Support
+getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Enhanced context and tracing
+getLangfuseContext, getTracer, };
 export { MiddlewareFactory } from "./middleware/factory.js";
 // Version
 export const VERSION = "1.0.0";

package/dist/lib/core/modules/TelemetryHandler.d.ts

@@ -57,6 +57,8 @@ export declare class TelemetryHandler {
         isEnabled: boolean;
         functionId?: string;
         metadata?: Record<string, string | number | boolean>;
+        recordInputs?: boolean;
+        recordOutputs?: boolean;
     } | undefined;
     /**
      * Handle tool execution storage if available

package/dist/lib/core/modules/TelemetryHandler.js

@@ -147,6 +147,8 @@ export class TelemetryHandler {
             isEnabled: true,
             functionId,
             metadata,
+            recordInputs: true,
+            recordOutputs: true,
         };
     }
     /**

package/dist/lib/index.d.ts

@@ -42,10 +42,10 @@ export type { DynamicModelConfig, ModelRegistry } from "./types/modelTypes.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export type { MCPServerInfo } from "./types/mcpTypes.js";
-export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, } from "./types/observability.js";
+export type { ObservabilityConfig, LangfuseConfig, OpenTelemetryConfig, LangfuseSpanAttributes, TraceNameFormat, } from "./types/observability.js";
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext } from "./services/server/ai/observability/instrumentation.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, };
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, };
 export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions, MiddlewarePreset, MiddlewareConfig, } from "./types/middlewareTypes.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export declare const VERSION = "1.0.0";

package/dist/lib/index.js

@@ -47,9 +47,17 @@ export { dynamicModelProvider } from "./core/dynamicModels.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, } from "./services/server/ai/observability/instrumentation.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
+// NEW EXPORTS - External TracerProvider Support
+getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Enhanced context and tracing
+getLangfuseContext, getTracer, } from "./services/server/ai/observability/instrumentation.js";
 import { initializeTelemetry as init, getTelemetryStatus as getStatus, } from "./telemetry/index.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, };
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
+// NEW EXPORTS - External TracerProvider Support
+getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Enhanced context and tracing
+getLangfuseContext, getTracer, };
 export { MiddlewareFactory } from "./middleware/factory.js";
 // Version
 export const VERSION = "1.0.0";

package/dist/lib/neurolink.js

@@ -44,7 +44,7 @@ import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
-import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, } from "./services/server/ai/observability/instrumentation.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, isOpenTelemetryInitialized, } from "./services/server/ai/observability/instrumentation.js";
 import { initializeMem0 } from "./memory/mem0Initializer.js";
 /**
  * NeuroLink - Universal AI Development Platform
@@ -635,7 +635,10 @@ Current user's request: ${currentInput}`;
         const langfuseInitStartTime = process.hrtime.bigint();
         try {
             const langfuseConfig = this.observabilityConfig?.langfuse;
-            if (langfuseConfig?.enabled) {
+            // Check if we should use external provider mode - bypass enabled check
+            const useExternalProvider = langfuseConfig?.autoDetectExternalProvider === true ||
+                langfuseConfig?.useExternalTracerProvider === true;
+            if (langfuseConfig?.enabled || useExternalProvider) {
                 logger.debug(`[NeuroLink] 📊 LOG_POINT_C019_LANGFUSE_INIT_START`, {
                     logPoint: "C019_LANGFUSE_INIT_START",
                     constructorId,
@@ -1212,7 +1215,12 @@ Current user's request: ${currentInput}`;
      * Centralized utility to avoid duplication across providers
      */
     isTelemetryEnabled() {
-        return this.observabilityConfig?.langfuse?.enabled || false;
+        // Check if observability config enables telemetry
+        if (this.observabilityConfig?.langfuse?.enabled) {
+            return true;
+        }
+        // Check if OpenTelemetry was initialized (by this or external app)
+        return isOpenTelemetryInitialized();
     }
     /**
      * Public method to initialize Langfuse observability

package/dist/lib/server/utils/validation.d.ts

@@ -37,9 +37,9 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
     };
     provider?: string | undefined;
     model?: string | undefined;
+    userId?: string | undefined;
     tools?: string[] | undefined;
     sessionId?: string | undefined;
-    userId?: string | undefined;
     temperature?: number | undefined;
     maxTokens?: number | undefined;
     stream?: boolean | undefined;
@@ -52,9 +52,9 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
     };
     provider?: string | undefined;
     model?: string | undefined;
+    userId?: string | undefined;
     tools?: string[] | undefined;
     sessionId?: string | undefined;
-    userId?: string | undefined;
     temperature?: number | undefined;
     maxTokens?: number | undefined;
     stream?: boolean | undefined;
@@ -71,12 +71,12 @@ export declare const ToolExecuteRequestSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     arguments: Record<string, unknown>;
-    sessionId?: string | undefined;
     userId?: string | undefined;
+    sessionId?: string | undefined;
 }, {
     name: string;
-    sessionId?: string | undefined;
     userId?: string | undefined;
+    sessionId?: string | undefined;
     arguments?: Record<string, unknown> | undefined;
 }>;
 /**

package/dist/lib/services/server/ai/observability/instrumentation.d.ts

@@ -8,7 +8,50 @@
  */
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { LangfuseSpanProcessor } from "@langfuse/otel";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { trace } from "@opentelemetry/api";
 import type { LangfuseConfig } from "../../../../types/observability.js";
+/**
+ * Extended context for Langfuse spans
+ * Supports all Langfuse trace attributes for rich observability
+ */
+type LangfuseContext = {
+    userId?: string | null;
+    sessionId?: string | null;
+    /** Conversation/thread identifier for grouping related traces */
+    conversationId?: string | null;
+    /** Request identifier for correlating with application logs */
+    requestId?: string | null;
+    /** Custom trace name for better organization in Langfuse UI */
+    traceName?: string | null;
+    /** Custom metadata to attach to spans */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * Explicit operation name (e.g., "ai.streamText", "chat", "embeddings")
+     *
+     * If set, this overrides auto-detection from the span name.
+     * Use this when you want a custom operation name that doesn't match
+     * the auto-detected Vercel AI SDK operation.
+     *
+     * @example
+     * await setLangfuseContext({
+     *   userId: "user@email.com",
+     *   operationName: "customer-support-chat"
+     * }, async () => {
+     *   // Trace name: "user@email.com:customer-support-chat"
+     * });
+     */
+    operationName?: string | null;
+    /**
+     * Override global autoDetectOperationName setting for this context.
+     *
+     * When undefined, uses the global setting from LangfuseConfig.
+     * Set to false to disable auto-detection for this specific context.
+     *
+     * @default undefined (uses global setting, which defaults to true)
+     */
+    autoDetectOperationName?: boolean;
+};
 /**
  * Initialize OpenTelemetry with Langfuse span processor
  *
@@ -17,6 +60,10 @@ import type { LangfuseConfig } from "../../../../types/observability.js";
  * 2. Creating a NodeTracerProvider with service metadata and span processor
  * 3. Registering the provider globally for AI SDK to use
  *
+ * NEW: If useExternalTracerProvider is true or autoDetectExternalProvider detects
+ * an existing provider, steps 2 and 3 are skipped. The span processors are still
+ * created and can be retrieved via getSpanProcessors().
+ *
  * @param config - Langfuse configuration passed from parent application
  */
 export declare function initializeOpenTelemetry(config: LangfuseConfig): void;
@@ -42,33 +89,109 @@ export declare function getTracerProvider(): NodeTracerProvider | null;
 export declare function isOpenTelemetryInitialized(): boolean;
 /**
  * Get health status for Langfuse observability
+ *
+ * @returns Health status object with initialization and configuration details
  */
 export declare function getLangfuseHealthStatus(): {
-    isHealthy: boolean | undefined;
+    isHealthy: boolean;
     initialized: boolean;
     credentialsValid: boolean;
     enabled: boolean;
     hasProcessor: boolean;
-    config: {
+    usingExternalProvider: boolean;
+    config?: {
         baseUrl: string;
         environment: string;
         release: string;
-    } | undefined;
+    };
 };
 /**
  * Set user and session context for Langfuse spans in the current async context
  *
  * Merges the provided context with existing AsyncLocalStorage context. If a callback is provided,
- * the context is scoped to that callback execution. Without a callback, the context applies to
- * the current execution context and its children.
+ * the context is scoped to that callback execution and returns the callback's result.
+ * Without a callback, the context applies to the current execution context and its children.
  *
  * Uses AsyncLocalStorage to properly scope context per request, avoiding race conditions
  * in concurrent scenarios.
  *
- * @param context - Object containing optional userId and/or sessionId to merge with existing context
+ * @param context - Object containing context fields to merge with existing context
  * @param callback - Optional callback to run within the context scope. If omitted, context applies to current execution
+ * @returns The callback's return value if provided, otherwise void
+ *
+ * @example
+ * // With callback - returns the result
+ * const result = await setLangfuseContext({ userId: "user123" }, async () => {
+ *   return await generateText({ model: "gpt-4", prompt: "Hello" });
+ * });
+ *
+ * @example
+ * // Without callback - sets context for current execution
+ * await setLangfuseContext({ sessionId: "session456", traceName: "chat-completion" });
  */
-export declare function setLangfuseContext(context: {
+export declare function setLangfuseContext<T = void>(context: {
     userId?: string | null;
     sessionId?: string | null;
-}, callback?: () => void | Promise<void>): Promise<void>;
+    conversationId?: string | null;
+    requestId?: string | null;
+    traceName?: string | null;
+    metadata?: Record<string, unknown> | null;
+    /** Explicit operation name (overrides auto-detection) */
+    operationName?: string | null;
+    /** Override global autoDetectOperationName for this context */
+    autoDetectOperationName?: boolean;
+}, callback?: () => T | Promise<T>): Promise<T | void>;
+/**
+ * Get the current Langfuse context from AsyncLocalStorage
+ *
+ * Returns the current context including userId, sessionId, conversationId,
+ * requestId, traceName, and metadata. Returns undefined if no context is set.
+ *
+ * @returns The current LangfuseContext or undefined
+ *
+ * @example
+ * const context = getLangfuseContext();
+ * console.log(context?.userId, context?.sessionId);
+ */
+export declare function getLangfuseContext(): LangfuseContext | undefined;
+/**
+ * Get an OpenTelemetry Tracer for creating custom spans
+ *
+ * This allows applications to create their own spans that will be
+ * processed by the same span processors (ContextEnricher + LangfuseSpanProcessor).
+ *
+ * @param name - Tracer name, defaults to "neurolink"
+ * @param version - Tracer version, optional
+ * @returns OpenTelemetry Tracer instance
+ *
+ * @example
+ * const tracer = getTracer("my-app");
+ * const span = tracer.startSpan("custom-operation");
+ * try {
+ *   // ... do work
+ * } finally {
+ *   span.end();
+ * }
+ */
+export declare function getTracer(name?: string, version?: string): ReturnType<typeof trace.getTracer>;
+/**
+ * Create a new ContextEnricher span processor
+ * Use this when useExternalTracerProvider is true to add to your own TracerProvider
+ *
+ * @returns A new ContextEnricher instance
+ */
+export declare function createContextEnricher(): SpanProcessor;
+/**
+ * Get all span processors that NeuroLink would use
+ * Convenience function that returns [ContextEnricher, LangfuseSpanProcessor]
+ *
+ * @returns Array of span processors, or empty array if not initialized
+ */
+export declare function getSpanProcessors(): SpanProcessor[];
+/**
+ * Check if using external TracerProvider mode
+ *
+ * @returns true if operating in external TracerProvider mode
+ */
+export declare function isUsingExternalTracerProvider(): boolean;
+export {};