@elasticdash/tracing 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,2090 @@
+import * as _opentelemetry_api from '@opentelemetry/api';
+import { Span, TimeInput, Attributes, TracerProvider, SpanContext } from '@opentelemetry/api';
+import { OpenAiUsage } from '@elasticdash/core';
+export { LangfuseOtelSpanAttributes, PropagateAttributesParams, propagateAttributes } from '@elasticdash/core';
+
+/**
+ * Types of observations that can be created in Langfuse.
+ *
+ * - `span`: General-purpose observations for tracking operations, functions, or logical units of work
+ * - `generation`: Specialized observations for LLM calls with model parameters, usage, and costs
+ * - `event`: Point-in-time occurrences or log entries within a trace
+ *
+ * @public
+ */
+type LangfuseObservationType = "span" | "generation" | "event" | "embedding" | "agent" | "tool" | "chain" | "retriever" | "evaluator" | "guardrail";
+/**
+ * Severity levels for observations in Langfuse.
+ *
+ * Used to categorize the importance or severity of observations:
+ * - `DEBUG`: Detailed diagnostic information
+ * - `DEFAULT`: Normal operation information
+ * - `WARNING`: Potentially problematic situations
+ * - `ERROR`: Error conditions that need attention
+ *
+ * @public
+ */
+type ObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+/**
+ * Attributes for Langfuse span observations.
+ *
+ * Spans are used to track operations, functions, or logical units of work.
+ * They can contain other spans, generations, or events as children.
+ *
+ * @public
+ */
+type LangfuseSpanAttributes = {
+    /** Input data for the operation being tracked */
+    input?: unknown;
+    /** Output data from the operation */
+    output?: unknown;
+    /** Additional metadata as key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Severity level of the observation */
+    level?: ObservationLevel;
+    /** Human-readable status message */
+    statusMessage?: string;
+    /** Version identifier for the code/model being tracked */
+    version?: string;
+    /** Environment where the operation is running (e.g., 'production', 'staging') */
+    environment?: string;
+};
+/**
+ * Attributes for Langfuse generation observations.
+ *
+ * Generations are specialized observations for tracking LLM interactions,
+ * including model parameters, usage metrics, costs, and prompt information.
+ *
+ * @public
+ */
+type LangfuseGenerationAttributes = LangfuseSpanAttributes & {
+    /** Timestamp when the model started generating completion */
+    completionStartTime?: Date;
+    /** Name of the language model used (e.g., 'gpt-4', 'claude-3') */
+    model?: string;
+    /** Parameters passed to the model (temperature, max_tokens, etc.) */
+    modelParameters?: {
+        [key: string]: string | number;
+    };
+    /** Token usage and other model-specific usage metrics */
+    usageDetails?: {
+        [key: string]: number;
+    } | OpenAiUsage;
+    /** Cost breakdown for the generation (totalCost, etc.) */
+    costDetails?: {
+        [key: string]: number;
+    };
+    /** Information about the prompt used from Langfuse prompt management */
+    prompt?: {
+        /** Name of the prompt template */
+        name: string;
+        /** Version number of the prompt template */
+        version: number;
+        /** Whether this is a fallback prompt due to retrieval failure */
+        isFallback: boolean;
+    };
+};
+type LangfuseEventAttributes = LangfuseSpanAttributes;
+type LangfuseAgentAttributes = LangfuseSpanAttributes;
+type LangfuseToolAttributes = LangfuseSpanAttributes;
+type LangfuseChainAttributes = LangfuseSpanAttributes;
+type LangfuseRetrieverAttributes = LangfuseSpanAttributes;
+type LangfuseEvaluatorAttributes = LangfuseSpanAttributes;
+type LangfuseGuardrailAttributes = LangfuseSpanAttributes;
+type LangfuseEmbeddingAttributes = LangfuseGenerationAttributes;
+/**
+ * Union type representing any Langfuse observation attributes.
+ *
+ * This type is used when you need to accept any type of observation attributes.
+ *
+ * @public
+ */
+type LangfuseObservationAttributes = LangfuseSpanAttributes & LangfuseGenerationAttributes & LangfuseEventAttributes & LangfuseAgentAttributes & LangfuseToolAttributes & LangfuseChainAttributes & LangfuseRetrieverAttributes & LangfuseEvaluatorAttributes & LangfuseGuardrailAttributes;
+/**
+ * Attributes for Langfuse traces.
+ *
+ * Traces are the top-level containers that group related observations together.
+ * They represent a complete workflow, request, or user interaction.
+ *
+ * @public
+ */
+type LangfuseTraceAttributes = {
+    /** Human-readable name for the trace */
+    name?: string;
+    /** Identifier for the user associated with this trace */
+    userId?: string;
+    /** Session identifier for grouping related traces */
+    sessionId?: string;
+    /** Version identifier for the code/application */
+    version?: string;
+    /** Release identifier for deployment tracking */
+    release?: string;
+    /** Input data that initiated the trace */
+    input?: unknown;
+    /** Final output data from the trace */
+    output?: unknown;
+    /** Additional metadata for the trace */
+    metadata?: unknown;
+    /** Tags for categorizing and filtering traces */
+    tags?: string[];
+    /** Whether this trace should be publicly visible */
+    public?: boolean;
+    /** Environment where the trace was captured */
+    environment?: string;
+};
+
+/**
+ * Union type representing any Langfuse observation wrapper.
+ *
+ * This type encompasses all observation types supported by Langfuse, providing
+ * a unified interface for handling different kinds of traced operations. It's
+ * particularly useful for generic functions that work with any observation type.
+ *
+ * ## Included Types
+ * - **LangfuseSpan**: General-purpose operations and workflows
+ * - **LangfuseGeneration**: LLM calls and AI model interactions
+ * - **LangfuseEmbedding**: Text embedding and vector operations
+ * - **LangfuseAgent**: AI agent workflows with tool usage
+ * - **LangfuseTool**: Individual tool calls and API requests
+ * - **LangfuseChain**: Multi-step processes and pipelines
+ * - **LangfuseRetriever**: Document retrieval and search operations
+ * - **LangfuseEvaluator**: Quality assessment and scoring
+ * - **LangfuseGuardrail**: Safety checks and content filtering
+ * - **LangfuseEvent**: Point-in-time occurrences and log entries
+ *
+ * @example
+ * ```typescript
+ * // Function accepting any observation type
+ * function logObservation(obs: LangfuseObservation) {
+ *   console.log(`Observation ${obs.id} in trace ${obs.traceId}`);
+ *
+ *   // All observations have common methods
+ *   obs.updateTrace({ tags: ['logged'] });
+ *   obs.end();
+ * }
+ *
+ * // Works with any observation type
+ * const span = startObservation('test-span');
+ * const generation = startObservation('llm-call', {}, { asType: 'generation' });
+ * const agent = startObservation('ai-agent', {}, { asType: 'agent' });
+ *
+ * logObservation(span);
+ * logObservation(generation);
+ * logObservation(agent);
+ * ```
+ *
+ * @public
+ */
+type LangfuseObservation = LangfuseSpan | LangfuseGeneration | LangfuseEvent | LangfuseAgent | LangfuseTool | LangfuseChain | LangfuseRetriever | LangfuseEvaluator | LangfuseGuardrail | LangfuseEmbedding;
+/**
+ * Parameters for creating a Langfuse observation wrapper.
+ *
+ * @internal
+ */
+type LangfuseObservationParams = {
+    otelSpan: Span;
+    type: LangfuseObservationType;
+    attributes?: LangfuseSpanAttributes | LangfuseGenerationAttributes | LangfuseEventAttributes;
+};
+/**
+ * Base class for all Langfuse observation wrappers providing unified functionality.
+ *
+ * This abstract class serves as the foundation for all observation types in Langfuse,
+ * encapsulating common operations and properties shared across spans, generations,
+ * events, and specialized observation types like agents, tools, and chains.
+ *
+ * ## Core Capabilities
+ * - **OpenTelemetry Integration**: Wraps OTEL spans with Langfuse-specific functionality
+ * - **Unique Identification**: Provides span ID and trace ID for correlation
+ * - **Lifecycle Management**: Handles observation creation, updates, and completion
+ * - **Trace Context**: Enables updating trace-level attributes from any observation
+ * - **Hierarchical Structure**: Supports creating nested child observations
+ * - **Type Safety**: Ensures type-safe attribute handling based on observation type
+ *
+ * ## Common Properties
+ * - `id`: Unique identifier for this observation (OpenTelemetry span ID)
+ * - `traceId`: Identifier of the parent trace containing this observation
+ * - `otelSpan`: Direct access to the underlying OpenTelemetry span
+ * - `type`: The observation type (span, generation, event, etc.)
+ *
+ * ## Common Methods
+ * - `end()`: Marks the observation as complete with optional timestamp
+ * - `updateTrace()`: Sets trace-level attributes like user ID, session ID, tags
+ * - `startObservation()`: Creates child observations with inherited context
+ *
+ * @example
+ * ```typescript
+ * // All observation types share these common capabilities
+ * const observation: LangfuseObservation = startObservation('my-operation');
+ *
+ * // Common properties available on all observations
+ * console.log(`Observation ID: ${observation.id}`);
+ * console.log(`Trace ID: ${observation.traceId}`);
+ * console.log(`Type: ${observation.type}`);
+ *
+ * // Common methods available on all observations
+ * observation.updateTrace({
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ *   tags: ['production', 'api-v2']
+ * });
+ *
+ * // Create child observations
+ * const child = observation.startObservation('child-operation', {
+ *   input: { step: 'processing' }
+ * });
+ *
+ * // End observations
+ * child.end();
+ * observation.end();
+ * ```
+ *
+ * @internal
+ */
+declare abstract class LangfuseBaseObservation {
+    /** The underlying OpenTelemetry span */
+    readonly otelSpan: Span;
+    /** The underlying OpenTelemetry span */
+    readonly type: LangfuseObservationType;
+    /** The span ID from the OpenTelemetry span context */
+    id: string;
+    /** The trace ID from the OpenTelemetry span context */
+    traceId: string;
+    constructor(params: LangfuseObservationParams);
+    /** Gets the Langfuse OpenTelemetry tracer instance */
+    protected get tracer(): _opentelemetry_api.Tracer;
+    /**
+     * Ends the observation, marking it as complete.
+     *
+     * @param endTime - Optional end time, defaults to current time
+     */
+    end(endTime?: TimeInput): void;
+    updateOtelSpanAttributes(attributes: LangfuseObservationAttributes): void;
+    /**
+     * Updates the parent trace with new attributes.
+     */
+    updateTrace(attributes: LangfuseTraceAttributes): this;
+    /**
+     * Creates a new child observation within this observation's context with full type safety.
+     *
+     * This method enables hierarchical tracing by creating child observations that inherit
+     * the parent's trace context. It supports all observation types with automatic TypeScript
+     * type inference based on the `asType` parameter, ensuring compile-time safety for
+     * attributes and return types.
+     *
+     * ## Hierarchy & Context
+     * - Child observations automatically inherit the parent's trace ID and span context
+     * - Creates proper parent-child relationships in the trace structure
+     * - Enables distributed tracing across nested operations
+     * - Maintains correlation between related operations
+     *
+     * ## Type Safety
+     * - Return type is automatically inferred from `asType` parameter
+     * - Attributes parameter is type-checked based on observation type
+     * - Compile-time validation prevents type mismatches
+     * - Full IntelliSense support for observation-specific attributes
+     *
+     * @param name - Descriptive name for the child observation
+     * @param attributes - Type-specific attributes (varies by observation type)
+     * @param options - Configuration including observation type (defaults to 'span')
+     * @returns Strongly-typed observation instance based on `asType`
+     *
+     * @example
+     * ```typescript
+     * // Within any observation (span, generation, agent, etc.)
+     * const parentObservation = startObservation('ai-workflow');
+     *
+     * // Create child span (default)
+     * const dataProcessing = parentObservation.startObservation('data-processing', {
+     *   input: { userId: '123', dataSize: 1024 },
+     *   metadata: { processor: 'fast-lane', version: '2.1' }
+     * }); // Returns LangfuseSpan
+     *
+     * // Create child generation with full LLM attributes
+     * const llmCall = parentObservation.startObservation('openai-gpt-4', {
+     *   input: [{ role: 'system', content: 'You are a helpful assistant' },
+     *           { role: 'user', content: 'Explain machine learning' }],
+     *   model: 'gpt-4-turbo',
+     *   modelParameters: {
+     *     temperature: 0.7,
+     *     maxTokens: 500,
+     *     topP: 1.0
+     *   },
+     *   metadata: { priority: 'high', timeout: 30000 }
+     * }, { asType: 'generation' }); // Returns LangfuseGeneration
+     *
+     * // Create child agent for complex reasoning
+     * const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
+     *   input: {
+     *     task: 'Analyze market trends',
+     *     context: 'Q4 2024 financial data'
+     *   },
+     *   metadata: {
+     *     model: 'gpt-4',
+     *     tools: ['calculator', 'web-search', 'data-analysis'],
+     *     maxIterations: 5
+     *   }
+     * }, { asType: 'agent' }); // Returns LangfuseAgent
+     *
+     * // Create child tool for external API calls
+     * const apiCall = reasoningAgent.startObservation('market-data-api', {
+     *   input: {
+     *     endpoint: '/market/trends',
+     *     params: { symbol: 'AAPL', period: '1Y' }
+     *   },
+     *   metadata: {
+     *     provider: 'alpha-vantage',
+     *     rateLimit: 5,
+     *     timeout: 10000
+     *   }
+     * }, { asType: 'tool' }); // Returns LangfuseTool
+     *
+     * // Create child retriever for document search
+     * const docSearch = parentObservation.startObservation('document-retrieval', {
+     *   input: {
+     *     query: 'sustainable energy solutions',
+     *     filters: { year: '2024', category: 'research' },
+     *     topK: 10
+     *   },
+     *   metadata: {
+     *     vectorStore: 'pinecone',
+     *     embeddingModel: 'text-embedding-ada-002',
+     *     similarity: 'cosine'
+     *   }
+     * }, { asType: 'retriever' }); // Returns LangfuseRetriever
+     *
+     * // Create child evaluator for quality assessment
+     * const qualityCheck = parentObservation.startObservation('response-evaluator', {
+     *   input: {
+     *     response: llmCall.output?.content,
+     *     reference: 'Expected high-quality explanation',
+     *     criteria: ['accuracy', 'clarity', 'completeness']
+     *   },
+     *   metadata: {
+     *     evaluator: 'custom-bert-scorer',
+     *     threshold: 0.8,
+     *     metrics: ['bleu', 'rouge', 'semantic-similarity']
+     *   }
+     * }, { asType: 'evaluator' }); // Returns LangfuseEvaluator
+     *
+     * // Create child guardrail for safety checking
+     * const safetyCheck = parentObservation.startObservation('content-guardrail', {
+     *   input: {
+     *     text: llmCall.output?.content,
+     *     policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
+     *   },
+     *   metadata: {
+     *     guardrailVersion: 'v2.1',
+     *     strictMode: true,
+     *     confidence: 0.95
+     *   }
+     * }, { asType: 'guardrail' }); // Returns LangfuseGuardrail
+     *
+     * // Create child embedding for vector generation
+     * const textEmbedding = parentObservation.startObservation('text-embedder', {
+     *   input: {
+     *     texts: ['Document summary', 'Key insights', 'Conclusions'],
+     *     batchSize: 3
+     *   },
+     *   model: 'text-embedding-ada-002',
+     *   metadata: {
+     *     dimensions: 1536,
+     *     normalization: 'l2',
+     *     purpose: 'semantic-search'
+     *   }
+     * }, { asType: 'embedding' }); // Returns LangfuseEmbedding
+     *
+     * // Create child event for point-in-time logging
+     * const userAction = parentObservation.startObservation('user-interaction', {
+     *   input: {
+     *     action: 'button-click',
+     *     element: 'generate-report',
+     *     timestamp: new Date().toISOString()
+     *   },
+     *   level: 'DEFAULT',
+     *   metadata: {
+     *     sessionId: 'sess_123',
+     *     userId: 'user_456',
+     *     browser: 'Chrome 120.0'
+     *   }
+     * }, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)
+     *
+     * // Chain operations - each child inherits context
+     * dataProcessing.update({ output: { processed: true, records: 1000 } });
+     * dataProcessing.end();
+     *
+     * llmCall.update({
+     *   output: { role: 'assistant', content: 'Machine learning is...' },
+     *   usageDetails: { promptTokens: 25, completionTokens: 150 }
+     * });
+     * llmCall.end();
+     *
+     * parentObservation.update({
+     *   output: {
+     *     workflowCompleted: true,
+     *     childOperations: 8,
+     *     totalDuration: Date.now() - startTime
+     *   }
+     * });
+     * parentObservation.end();
+     * ```
+     *
+     * @see {@link startObservation} for creating root-level observations
+     * @see {@link startActiveObservation} for function-scoped child observations
+     */
+    startObservation(name: string, attributes: LangfuseGenerationAttributes, options: {
+        asType: "generation";
+    }): LangfuseGeneration;
+    startObservation(name: string, attributes: LangfuseEventAttributes, options: {
+        asType: "event";
+    }): LangfuseEvent;
+    startObservation(name: string, attributes: LangfuseAgentAttributes, options: {
+        asType: "agent";
+    }): LangfuseAgent;
+    startObservation(name: string, attributes: LangfuseToolAttributes, options: {
+        asType: "tool";
+    }): LangfuseTool;
+    startObservation(name: string, attributes: LangfuseChainAttributes, options: {
+        asType: "chain";
+    }): LangfuseChain;
+    startObservation(name: string, attributes: LangfuseRetrieverAttributes, options: {
+        asType: "retriever";
+    }): LangfuseRetriever;
+    startObservation(name: string, attributes: LangfuseEvaluatorAttributes, options: {
+        asType: "evaluator";
+    }): LangfuseEvaluator;
+    startObservation(name: string, attributes: LangfuseGuardrailAttributes, options: {
+        asType: "guardrail";
+    }): LangfuseGuardrail;
+    startObservation(name: string, attributes: LangfuseEmbeddingAttributes, options: {
+        asType: "embedding";
+    }): LangfuseEmbedding;
+    startObservation(name: string, attributes?: LangfuseSpanAttributes, options?: {
+        asType?: "span";
+    }): LangfuseSpan;
+}
+type LangfuseSpanParams = {
+    otelSpan: Span;
+    attributes?: LangfuseSpanAttributes;
+};
+/**
+ * General-purpose observation wrapper for tracking operations, functions, and workflows.
+ *
+ * LangfuseSpan is the default and most versatile observation type, designed for tracing
+ * any operation that has a defined start and end time. It serves as the foundation for
+ * building hierarchical traces and can contain any other observation type as children.
+ *
+ * ## Primary Use Cases
+ * - **Business Logic**: User workflows, order processing, data transformations
+ * - **API Operations**: REST endpoint handling, database queries, external service calls
+ * - **System Operations**: File I/O, network requests, background jobs
+ * - **Pipeline Steps**: Data processing stages, validation steps, orchestration
+ * - **Application Functions**: Any measurable operation in your application
+ *
+ * ## Key Features
+ * - **Hierarchical Structure**: Can contain child observations of any type
+ * - **Flexible Attributes**: Supports arbitrary input, output, and metadata
+ * - **Duration Tracking**: Automatically measures execution time from start to end
+ * - **Status Monitoring**: Tracks success/failure states and error conditions
+ * - **Context Propagation**: Maintains trace context for distributed operations
+ *
+ * ## Span Lifecycle
+ * 1. **Creation**: Span starts automatically when created
+ * 2. **Updates**: Add input data, intermediate state, metadata as needed
+ * 3. **Child Operations**: Create nested observations for sub-operations
+ * 4. **Completion**: Update with final output and call `.end()` to finish
+ *
+ * @example
+ * ```typescript
+ * // Basic span tracking
+ * const span = startObservation('user-authentication', {
+ *   input: { username: 'john_doe', method: 'oauth' },
+ *   metadata: { provider: 'google' }
+ * });
+ *
+ * try {
+ *   const user = await authenticateUser(credentials);
+ *   span.update({
+ *     output: { userId: user.id, success: true }
+ *   });
+ * } catch (error) {
+ *   span.update({
+ *     level: 'ERROR',
+ *     output: { success: false, error: error.message }
+ *   });
+ * } finally {
+ *   span.end();
+ * }
+ *
+ * // Nested operations
+ * const workflow = startObservation('order-processing', {
+ *   input: { orderId: 'ord_123' }
+ * });
+ *
+ * const validation = workflow.startObservation('validation', {
+ *   input: { items: cartItems }
+ * });
+ * validation.update({ output: { valid: true } });
+ * validation.end();
+ *
+ * const payment = workflow.startObservation('payment', {
+ *   input: { amount: 100 }
+ * });
+ * payment.update({ output: { status: 'completed' } });
+ * payment.end();
+ *
+ * workflow.update({
+ *   output: { status: 'confirmed', steps: 2 }
+ * });
+ * workflow.end();
+ * ```
+ *
+ * @see {@link startObservation} - Factory function for creating spans
+ * @see {@link startActiveObservation} - Function-scoped span creation
+ * @see {@link LangfuseGeneration} - For LLM and AI model interactions
+ * @see {@link LangfuseEvent} - For point-in-time occurrences
+ *
+ * @public
+ */
+declare class LangfuseSpan extends LangfuseBaseObservation {
+    constructor(params: LangfuseSpanParams);
+    /**
+     * Updates this span with new attributes.
+     *
+     * @param attributes - Span attributes to set
+     * @returns This span for method chaining
+     *
+     * @example
+     * ```typescript
+     * span.update({
+     *   output: { result: 'success' },
+     *   level: 'DEFAULT',
+     *   metadata: { duration: 150 }
+     * });
+     * ```
+     */
+    update(attributes: LangfuseSpanAttributes): LangfuseSpan;
+}
+type LangfuseAgentParams = {
+    otelSpan: Span;
+    attributes?: LangfuseAgentAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking AI agent workflows and autonomous operations.
+ *
+ * LangfuseAgent is designed for observing intelligent agent systems that combine reasoning,
+ * tool usage, memory management, and decision-making in autonomous workflows. It captures
+ * the complex multi-step nature of agent operations, including planning, execution, and
+ * self-correction cycles typical in advanced AI agent architectures.
+ *
+ * ## Primary Use Cases
+ * - **Autonomous AI Agents**: ReAct, AutoGPT, LangGraph agent implementations
+ * - **Tool-Using Agents**: Function calling agents with external API access
+ * - **Multi-Step Reasoning**: Chain-of-thought, tree-of-thought agent workflows
+ * - **Planning Agents**: Goal decomposition and task planning systems
+ * - **Conversational Agents**: Multi-turn dialogue agents with memory
+ * - **Code Generation Agents**: AI assistants that write, test, and debug code
+ *
+ * ## Key Features
+ * - **Multi-Step Tracking**: Captures entire agent workflow from planning to execution
+ * - **Tool Integration**: Records all tool calls and their results within agent context
+ * - **Decision Logic**: Tracks reasoning steps, decisions, and strategy adaptations
+ * - **Memory Management**: Observes how agents maintain and use context across steps
+ * - **Error Recovery**: Monitors how agents handle failures and adapt their approach
+ * - **Performance Metrics**: Measures agent efficiency, success rates, and resource usage
+ *
+ * ## Agent-Specific Patterns
+ * - **Planning Phase**: Initial goal analysis and strategy formulation
+ * - **Execution Loop**: Iterative action-observation-reasoning cycles
+ * - **Tool Selection**: Dynamic tool choice based on context and goals
+ * - **Self-Correction**: Error detection and strategy adjustment
+ * - **Memory Updates**: Context retention and knowledge accumulation
+ * - **Final Synthesis**: Result compilation and quality assessment
+ *
+ * @example
+ * ```typescript
+ * // Basic agent workflow
+ * const agent = startObservation('research-agent', {
+ *   input: {
+ *     task: 'Research renewable energy trends',
+ *     tools: ['web-search', 'summarizer'],
+ *     maxIterations: 3
+ *   }
+ * }, { asType: 'agent' });
+ *
+ * // Agent uses tools and makes decisions
+ * const searchTool = agent.startObservation('web-search', {
+ *   input: { query: 'renewable energy 2024' }
+ * }, { asType: 'tool' });
+ *
+ * const results = await webSearch('renewable energy 2024');
+ * searchTool.update({ output: results });
+ * searchTool.end();
+ *
+ * // Agent generates final response
+ * const generation = agent.startObservation('synthesize-findings', {
+ *   input: results,
+ *   model: 'gpt-4'
+ * }, { asType: 'generation' });
+ *
+ * const response = await llm.generate(results);
+ * generation.update({ output: response });
+ * generation.end();
+ *
+ * agent.update({
+ *   output: {
+ *     completed: true,
+ *     toolsUsed: 1,
+ *     finalResponse: response
+ *   }
+ * });
+ * agent.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'agent' }` - Factory function
+ * @see {@link startActiveObservation} with `{ asType: 'agent' }` - Function-scoped agent
+ * @see {@link LangfuseTool} - For individual tool executions within agents
+ * @see {@link LangfuseChain} - For structured multi-step workflows
+ *
+ * @public
+ */
+declare class LangfuseAgent extends LangfuseBaseObservation {
+    constructor(params: LangfuseAgentParams);
+    /**
+     * Updates this agent observation with new attributes.
+     *
+     * @param attributes - Agent attributes to set
+     * @returns This agent for method chaining
+     *
+     * @example
+     * ```typescript
+     * agent.update({
+     *   output: {
+     *     taskCompleted: true,
+     *     iterationsUsed: 5,
+     *     toolsInvoked: ['web-search', 'calculator', 'summarizer'],
+     *     finalResult: 'Research completed with high confidence'
+     *   },
+     *   metadata: {
+     *     efficiency: 0.85,
+     *     qualityScore: 0.92,
+     *     resourcesConsumed: { tokens: 15000, apiCalls: 12 }
+     *   }
+     * });
+     * ```
+     */
+    update(attributes: LangfuseAgentAttributes): LangfuseAgent;
+}
+type LangfuseToolParams = {
+    otelSpan: Span;
+    attributes?: LangfuseToolAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking individual tool calls and external API interactions.
+ *
+ * LangfuseTool is designed for observing discrete tool invocations within agent workflows,
+ * function calling scenarios, or standalone API integrations. It captures the input parameters,
+ * execution results, performance metrics, and error conditions of tool operations, making it
+ * essential for debugging tool reliability and optimizing tool selection strategies.
+ *
+ * ## Primary Use Cases
+ * - **Function Calling**: OpenAI function calls, Anthropic tool use, Claude function calling
+ * - **External APIs**: REST API calls, GraphQL queries, database operations
+ * - **System Tools**: File operations, shell commands, system integrations
+ * - **Data Processing Tools**: Calculators, converters, validators, parsers
+ * - **Search Tools**: Web search, vector search, document retrieval
+ * - **Content Tools**: Image generation, text processing, format conversion
+ *
+ * ## Key Features
+ * - **Parameter Tracking**: Complete input parameter logging and validation
+ * - **Result Capture**: Full output data and metadata from tool execution
+ * - **Performance Monitoring**: Execution time, success rates, retry attempts
+ * - **Error Analysis**: Detailed error tracking with context and recovery info
+ * - **Usage Analytics**: Frequency, patterns, and efficiency metrics
+ * - **Integration Health**: API status, rate limits, and service availability
+ *
+ * ## Tool-Specific Patterns
+ * - **Input Validation**: Parameter checking and sanitization before execution
+ * - **Execution Monitoring**: Real-time performance and status tracking
+ * - **Result Processing**: Output validation, transformation, and formatting
+ * - **Error Handling**: Retry logic, fallbacks, and graceful degradation
+ * - **Caching Integration**: Result caching and cache hit/miss tracking
+ * - **Rate Limiting**: Request throttling and quota management
+ *
+ * @example
+ * ```typescript
+ * // Web search tool
+ * const searchTool = startObservation('web-search', {
+ *   input: {
+ *     query: 'latest AI developments',
+ *     maxResults: 10
+ *   },
+ *   metadata: { provider: 'google-api' }
+ * }, { asType: 'tool' });
+ *
+ * try {
+ *   const results = await webSearch('latest AI developments');
+ *
+ *   searchTool.update({
+ *     output: {
+ *       results: results,
+ *       count: results.length
+ *     },
+ *     metadata: {
+ *       latency: 1200,
+ *       cacheHit: false
+ *     }
+ *   });
+ * } catch (error) {
+ *   searchTool.update({
+ *     level: 'ERROR',
+ *     statusMessage: 'Search failed',
+ *     output: { error: error.message }
+ *   });
+ * } finally {
+ *   searchTool.end();
+ * }
+ *
+ * // Database query tool
+ * const dbTool = startObservation('db-query', {
+ *   input: {
+ *     query: 'SELECT * FROM users WHERE active = true',
+ *     timeout: 30000
+ *   }
+ * }, { asType: 'tool' });
+ *
+ * const result = await db.query('SELECT * FROM users WHERE active = true');
+ * dbTool.update({
+ *   output: { rowCount: result.length },
+ *   metadata: { executionTime: 150 }
+ * });
+ * dbTool.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'tool' }` - Factory function
+ * @see {@link startActiveObservation} with `{ asType: 'tool' }` - Function-scoped tool
+ * @see {@link LangfuseAgent} - For agent workflows that use multiple tools
+ * @see {@link LangfuseChain} - For orchestrated tool sequences
+ *
+ * @public
+ */
+declare class LangfuseTool extends LangfuseBaseObservation {
+    constructor(params: LangfuseToolParams);
+    /**
+     * Updates this tool observation with new attributes.
+     *
+     * @param attributes - Tool attributes to set
+     * @returns This tool for method chaining
+     *
+     * @example
+     * ```typescript
+     * tool.update({
+     *   output: {
+     *     result: searchResults,
+     *     count: searchResults.length,
+     *     relevanceScore: 0.89,
+     *     executionTime: 1250
+     *   },
+     *   metadata: {
+     *     cacheHit: false,
+     *     apiCost: 0.025,
+     *     rateLimitRemaining: 950
+     *   }
+     * });
+     * ```
+     */
+    update(attributes: LangfuseToolAttributes): LangfuseTool;
+}
+type LangfuseChainParams = {
+    otelSpan: Span;
+    attributes?: LangfuseChainAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking structured multi-step workflows and process chains.
+ *
+ * LangfuseChain is designed for observing sequential, parallel, or conditional workflow orchestration
+ * where multiple operations are coordinated to achieve a larger goal. It captures the flow of data
+ * between steps, manages dependencies, tracks progress through complex pipelines, and provides
+ * insights into workflow performance and reliability patterns.
+ *
+ * ## Primary Use Cases
+ * - **Data Processing Pipelines**: ETL processes, data transformation workflows
+ * - **Business Process Automation**: Order processing, approval workflows, document processing
+ * - **LangChain Integration**: LangChain chain execution and orchestration
+ * - **RAG Pipelines**: Document retrieval → context preparation → generation → post-processing
+ * - **Multi-Model Workflows**: Preprocessing → model inference → post-processing → validation
+ * - **Content Production**: Research → drafting → review → editing → publishing
+ *
+ * ## Key Features
+ * - **Step Orchestration**: Sequential, parallel, and conditional step execution tracking
+ * - **Data Flow Management**: Input/output tracking between pipeline steps
+ * - **Dependency Resolution**: Manages complex step dependencies and prerequisites
+ * - **Progress Monitoring**: Real-time workflow progress and completion status
+ * - **Error Propagation**: Handles failures, retries, and recovery across workflow steps
+ * - **Performance Analytics**: Bottleneck identification and optimization insights
+ *
+ * ## Chain-Specific Patterns
+ * - **Pipeline Setup**: Workflow definition, step configuration, and dependency mapping
+ * - **Sequential Execution**: Step-by-step processing with state management
+ * - **Parallel Processing**: Concurrent step execution with synchronization
+ * - **Conditional Logic**: Dynamic branching based on intermediate results
+ * - **Error Recovery**: Failure handling, rollback, and alternative path execution
+ * - **Result Aggregation**: Combining outputs from multiple workflow branches
+ *
+ * @example
+ * ```typescript
+ * // RAG processing chain
+ * const ragChain = startObservation('rag-chain', {
+ *   input: {
+ *     query: 'What is renewable energy?',
+ *     steps: ['retrieval', 'generation']
+ *   }
+ * }, { asType: 'chain' });
+ *
+ * // Step 1: Document retrieval
+ * const retrieval = ragChain.startObservation('document-retrieval', {
+ *   input: { query: 'renewable energy' }
+ * }, { asType: 'retriever' });
+ *
+ * const docs = await vectorSearch('renewable energy');
+ * retrieval.update({ output: { documents: docs, count: docs.length } });
+ * retrieval.end();
+ *
+ * // Step 2: Generate response
+ * const generation = ragChain.startObservation('response-generation', {
+ *   input: {
+ *     query: 'What is renewable energy?',
+ *     context: docs
+ *   },
+ *   model: 'gpt-4'
+ * }, { asType: 'generation' });
+ *
+ * const response = await llm.generate({
+ *   prompt: buildPrompt('What is renewable energy?', docs)
+ * });
+ *
+ * generation.update({ output: response });
+ * generation.end();
+ *
+ * ragChain.update({
+ *   output: {
+ *     finalResponse: response,
+ *     stepsCompleted: 2,
+ *     documentsUsed: docs.length
+ *   }
+ * });
+ * ragChain.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'chain' }` - Factory function
+ * @see {@link startActiveObservation} with `{ asType: 'chain' }` - Function-scoped chain
+ * @see {@link LangfuseSpan} - For individual workflow steps
+ * @see {@link LangfuseAgent} - For intelligent workflow orchestration
+ *
+ * @public
+ */
+declare class LangfuseChain extends LangfuseBaseObservation {
+    constructor(params: LangfuseChainParams);
+    /**
+     * Updates this chain observation with new attributes.
+     *
+     * @param attributes - Chain attributes to set
+     * @returns This chain for method chaining
+     *
+     * @example
+     * ```typescript
+     * chain.update({
+     *   output: {
+     *     stepsCompleted: 5,
+     *     stepsSuccessful: 4,
+     *     finalResult: processedData,
+     *     pipelineEfficiency: 0.87
+     *   },
+     *   metadata: {
+     *     bottleneckStep: 'data-validation',
+     *     parallelizationOpportunities: ['step-2', 'step-3'],
+     *     optimizationSuggestions: ['cache-intermediate-results']
+     *   }
+     * });
+     * ```
+     */
+    update(attributes: LangfuseChainAttributes): LangfuseChain;
+}
+type LangfuseRetrieverParams = {
+    otelSpan: Span;
+    attributes?: LangfuseRetrieverAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking document retrieval and search operations.
+ *
+ * LangfuseRetriever is designed for observing information retrieval systems that search,
+ * filter, and rank content from various data sources. It captures search queries, retrieval
+ * strategies, result quality metrics, and performance characteristics of search operations,
+ * making it essential for RAG systems, knowledge bases, and content discovery workflows.
+ *
+ * ## Primary Use Cases
+ * - **Vector Search**: Semantic similarity search using embeddings and vector databases
+ * - **Document Retrieval**: Full-text search, keyword matching, and document filtering
+ * - **Knowledge Base Query**: FAQ systems, help documentation, and knowledge management
+ * - **RAG Systems**: Retrieval step in retrieval-augmented generation pipelines
+ * - **Recommendation Systems**: Content recommendations and similarity-based suggestions
+ * - **Data Mining**: Information extraction and content discovery from large datasets
+ *
+ * ## Key Features
+ * - **Query Analysis**: Input query processing, expansion, and optimization tracking
+ * - **Search Strategy**: Retrieval algorithms, ranking functions, and filtering criteria
+ * - **Result Quality**: Relevance scores, diversity metrics, and retrieval effectiveness
+ * - **Performance Metrics**: Search latency, index size, and throughput measurements
+ * - **Source Tracking**: Data source attribution and content provenance information
+ * - **Ranking Intelligence**: Personalization, context awareness, and result optimization
+ *
+ * @example
+ * ```typescript
+ * // Vector search retrieval
+ * const retriever = startObservation('vector-search', {
+ *   input: {
+ *     query: 'machine learning applications',
+ *     topK: 10,
+ *     similarityThreshold: 0.7
+ *   },
+ *   metadata: {
+ *     vectorDB: 'pinecone',
+ *     embeddingModel: 'text-embedding-ada-002'
+ *   }
+ * }, { asType: 'retriever' });
+ *
+ * const results = await vectorDB.search({
+ *   query: 'machine learning applications',
+ *   topK: 10,
+ *   threshold: 0.7
+ * });
+ *
+ * retriever.update({
+ *   output: {
+ *     documents: results,
+ *     count: results.length,
+ *     avgSimilarity: 0.89
+ *   },
+ *   metadata: {
+ *     searchLatency: 150,
+ *     cacheHit: false
+ *   }
+ * });
+ * retriever.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'retriever' }` - Factory function
+ * @see {@link LangfuseChain} - For multi-step RAG pipelines
+ * @see {@link LangfuseEmbedding} - For embedding generation used in vector search
+ *
+ * @public
+ */
+declare class LangfuseRetriever extends LangfuseBaseObservation {
+    constructor(params: LangfuseRetrieverParams);
+    /**
+     * Updates this retriever observation with new attributes.
+     *
+     * @param attributes - Retriever attributes to set
+     * @returns This retriever for method chaining
+     */
+    update(attributes: LangfuseRetrieverAttributes): LangfuseRetriever;
+}
+type LangfuseEvaluatorParams = {
+    otelSpan: Span;
+    attributes?: LangfuseEvaluatorAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking quality assessment and evaluation operations.
+ *
+ * LangfuseEvaluator is designed for observing evaluation systems that assess, score, and
+ * validate the quality of AI outputs, content, or system performance. It captures evaluation
+ * criteria, scoring methodologies, benchmark comparisons, and quality metrics, making it
+ * essential for AI system validation, content moderation, and performance monitoring.
+ *
+ * ## Primary Use Cases
+ * - **LLM Output Evaluation**: Response quality, factual accuracy, and relevance assessment
+ * - **Content Quality Assessment**: Writing quality, tone analysis, and style validation
+ * - **Automated Testing**: System performance validation and regression testing
+ * - **Bias Detection**: Fairness evaluation and bias identification in AI systems
+ * - **Safety Evaluation**: Content safety, harm detection, and compliance checking
+ * - **Benchmark Comparison**: Performance comparison against reference standards
+ *
+ * ## Key Features
+ * - **Multi-Criteria Scoring**: Comprehensive evaluation across multiple quality dimensions
+ * - **Automated Assessment**: AI-powered evaluation using specialized models and algorithms
+ * - **Human Evaluation**: Integration with human reviewers and expert assessment
+ * - **Benchmark Tracking**: Performance comparison against established baselines
+ * - **Quality Metrics**: Detailed scoring with confidence intervals and reliability measures
+ * - **Trend Analysis**: Quality tracking over time with improvement recommendations
+ *
+ * @example
+ * ```typescript
+ * // Response quality evaluation
+ * const evaluator = startObservation('response-quality-eval', {
+ *   input: {
+ *     response: 'Machine learning is a subset of artificial intelligence...',
+ *     criteria: ['accuracy', 'completeness', 'clarity']
+ *   }
+ * }, { asType: 'evaluator' });
+ *
+ * const evaluation = await evaluateResponse({
+ *   response: 'Machine learning is a subset of artificial intelligence...',
+ *   criteria: ['accuracy', 'completeness', 'clarity']
+ * });
+ *
+ * evaluator.update({
+ *   output: {
+ *     overallScore: 0.87,
+ *     criteriaScores: {
+ *       accuracy: 0.92,
+ *       completeness: 0.85,
+ *       clarity: 0.90
+ *     },
+ *     passed: true
+ *   }
+ * });
+ * evaluator.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'evaluator' }` - Factory function
+ * @see {@link LangfuseGeneration} - For LLM outputs being evaluated
+ * @see {@link LangfuseGuardrail} - For safety and compliance enforcement
+ *
+ * @public
+ */
+declare class LangfuseEvaluator extends LangfuseBaseObservation {
+    constructor(params: LangfuseEvaluatorParams);
+    /**
+     * Updates this evaluator observation with new attributes.
+     *
+     * @param attributes - Evaluator attributes to set
+     * @returns This evaluator for method chaining
+     */
+    update(attributes: LangfuseEvaluatorAttributes): LangfuseEvaluator;
+}
+type LangfuseGuardrailParams = {
+    otelSpan: Span;
+    attributes?: LangfuseGuardrailAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking safety checks and compliance enforcement.
+ *
+ * LangfuseGuardrail is designed for observing safety and compliance systems that prevent,
+ * detect, and mitigate harmful, inappropriate, or policy-violating content and behaviors
+ * in AI applications. It captures safety policies, violation detection, risk assessment,
+ * and mitigation actions, ensuring responsible AI deployment and regulatory compliance.
+ *
+ * ## Primary Use Cases
+ * - **Content Moderation**: Harmful content detection and filtering in user inputs/outputs
+ * - **Safety Enforcement**: PII detection, toxicity filtering, and inappropriate content blocking
+ * - **Compliance Monitoring**: Regulatory compliance, industry standards, and policy enforcement
+ * - **Bias Mitigation**: Fairness checks and bias prevention in AI decision-making
+ * - **Privacy Protection**: Data privacy safeguards and sensitive information redaction
+ * - **Behavioral Monitoring**: User behavior analysis and anomaly detection
+ *
+ * ## Key Features
+ * - **Multi-Policy Enforcement**: Simultaneous checking against multiple safety policies
+ * - **Risk Assessment**: Quantitative risk scoring with confidence intervals
+ * - **Real-Time Detection**: Low-latency safety checks for interactive applications
+ * - **Context Awareness**: Contextual safety evaluation considering user and application context
+ * - **Mitigation Actions**: Automatic content blocking, filtering, and redaction capabilities
+ * - **Audit Trail**: Comprehensive logging for compliance and safety incident investigation
+ *
+ * @example
+ * ```typescript
+ * // Content safety guardrail
+ * const guardrail = startObservation('content-safety-check', {
+ *   input: {
+ *     content: userMessage,
+ *     policies: ['no-toxicity', 'no-hate-speech'],
+ *     strictMode: false
+ *   }
+ * }, { asType: 'guardrail' });
+ *
+ * const safetyCheck = await checkContentSafety({
+ *   text: userMessage,
+ *   policies: ['no-toxicity', 'no-hate-speech']
+ * });
+ *
+ * guardrail.update({
+ *   output: {
+ *     safe: safetyCheck.safe,
+ *     riskScore: 0.15,
+ *     violations: [],
+ *     action: 'allow'
+ *   }
+ * });
+ * guardrail.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'guardrail' }` - Factory function
+ * @see {@link LangfuseEvaluator} - For detailed quality and safety assessment
+ * @see {@link LangfuseGeneration} - For protecting LLM outputs with guardrails
+ *
+ * @public
+ */
+declare class LangfuseGuardrail extends LangfuseBaseObservation {
+    constructor(params: LangfuseGuardrailParams);
+    /**
+     * Updates this guardrail observation with new attributes.
+     *
+     * @param attributes - Guardrail attributes to set
+     * @returns This guardrail for method chaining
+     */
+    update(attributes: LangfuseGuardrailAttributes): LangfuseGuardrail;
+}
+/**
+ * Parameters for creating a Langfuse generation.
+ *
+ * @internal
+ */
+type LangfuseGenerationParams = {
+    otelSpan: Span;
+    attributes?: LangfuseGenerationAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking LLM interactions, AI model calls, and text generation.
+ *
+ * LangfuseGeneration is purpose-built for observing AI model interactions, providing rich
+ * metadata capture for prompts, completions, model parameters, token usage, and costs.
+ * It's the go-to observation type for any operation involving language models, chat APIs,
+ * completion APIs, or other generative AI services.
+ *
+ * ## Primary Use Cases
+ * - **LLM API Calls**: OpenAI, Anthropic, Cohere, Azure OpenAI, AWS Bedrock
+ * - **Chat Completions**: Multi-turn conversations and dialogue systems
+ * - **Text Generation**: Content creation, summarization, translation
+ * - **Code Generation**: AI-powered code completion and generation
+ * - **RAG Systems**: Generation step in retrieval-augmented generation
+ * - **AI Agents**: LLM reasoning and decision-making within agent workflows
+ *
+ * ## Key Features
+ * - **Rich LLM Metadata**: Model name, parameters, prompts, completions
+ * - **Usage Tracking**: Token counts (prompt, completion, total)
+ * - **Cost Monitoring**: Automatic cost calculation and tracking
+ * - **Performance Metrics**: Latency, throughput, tokens per second
+ * - **Prompt Engineering**: Version control for prompts and templates
+ * - **Error Handling**: Rate limits, timeouts, model-specific errors
+ *
+ * ## Generation-Specific Attributes
+ * - `model`: Model identifier (e.g., 'gpt-4-turbo', 'claude-3-sonnet')
+ * - `modelParameters`: Temperature, max tokens, top-p, frequency penalty
+ * - `input`: Prompt or message array for the model
+ * - `output`: Model response, completion, or generated content
+ * - `usageDetails`: Token consumption (prompt, completion, total)
+ * - `costDetails`: Financial cost breakdown and pricing
+ * - `prompt`: Structured prompt object with name, version, variables
+ *
+ * @example
+ * ```typescript
+ * // Basic LLM generation tracking
+ * const generation = startObservation('openai-completion', {
+ *   model: 'gpt-4-turbo',
+ *   input: [
+ *     { role: 'system', content: 'You are a helpful assistant.' },
+ *     { role: 'user', content: 'Explain quantum computing' }
+ *   ],
+ *   modelParameters: {
+ *     temperature: 0.7,
+ *     maxTokens: 500
+ *   }
+ * }, { asType: 'generation' });
+ *
+ * try {
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4-turbo',
+ *     messages: [
+ *       { role: 'system', content: 'You are a helpful assistant.' },
+ *       { role: 'user', content: 'Explain quantum computing' }
+ *     ],
+ *     temperature: 0.7,
+ *     max_tokens: 500
+ *   });
+ *
+ *   generation.update({
+ *     output: response.choices[0].message,
+ *     usageDetails: {
+ *       promptTokens: response.usage.prompt_tokens,
+ *       completionTokens: response.usage.completion_tokens,
+ *       totalTokens: response.usage.total_tokens
+ *     },
+ *     costDetails: {
+ *       totalCost: 0.025,
+ *       currency: 'USD'
+ *     }
+ *   });
+ * } catch (error) {
+ *   generation.update({
+ *     level: 'ERROR',
+ *     statusMessage: `API error: ${error.message}`,
+ *     output: { error: error.message }
+ *   });
+ * } finally {
+ *   generation.end();
+ * }
+ *
+ * // RAG generation example
+ * const ragGeneration = startObservation('rag-response', {
+ *   model: 'gpt-4',
+ *   input: [
+ *     { role: 'system', content: 'Answer based on provided context.' },
+ *     { role: 'user', content: `Context: ${context}\n\nQuestion: ${question}` }
+ *   ],
+ *   modelParameters: { temperature: 0.1 }
+ * }, { asType: 'generation' });
+ *
+ * const response = await llm.generate({ prompt, context });
+ * ragGeneration.update({
+ *   output: response,
+ *   metadata: { contextSources: 3 }
+ * });
+ * ragGeneration.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'generation' }` - Factory function
+ * @see {@link startActiveObservation} with `{ asType: 'generation' }` - Function-scoped generation
+ * @see {@link LangfuseSpan} - For general-purpose operations
+ * @see {@link LangfuseEmbedding} - For text embedding and vector operations
+ *
+ * @public
+ */
+declare class LangfuseGeneration extends LangfuseBaseObservation {
+    constructor(params: LangfuseGenerationParams);
+    update(attributes: LangfuseGenerationAttributes): LangfuseGeneration;
+}
+type LangfuseEmbeddingParams = {
+    otelSpan: Span;
+    attributes?: LangfuseEmbeddingAttributes;
+};
+/**
+ * Specialized observation wrapper for tracking text embedding and vector generation operations.
+ *
+ * LangfuseEmbedding is designed for observing embedding model interactions that convert
+ * text, images, or other content into high-dimensional vector representations. It captures
+ * embedding model parameters, input preprocessing, vector characteristics, and performance
+ * metrics, making it essential for semantic search, RAG systems, and similarity-based applications.
+ *
+ * ## Primary Use Cases
+ * - **Text Embeddings**: Converting text to vectors for semantic search and similarity
+ * - **Document Indexing**: Creating vector representations for large document collections
+ * - **Semantic Search**: Enabling similarity-based search and content discovery
+ * - **RAG Preparation**: Embedding documents and queries for retrieval-augmented generation
+ * - **Clustering Analysis**: Grouping similar content using vector representations
+ * - **Recommendation Systems**: Content similarity for personalized recommendations
+ *
+ * ## Key Features
+ * - **Model Tracking**: Embedding model selection, version, and parameter monitoring
+ * - **Input Processing**: Text preprocessing, tokenization, and normalization tracking
+ * - **Vector Analysis**: Dimensionality, magnitude, and quality metrics for generated embeddings
+ * - **Batch Processing**: Efficient handling of multiple texts in single embedding operations
+ * - **Performance Monitoring**: Embedding generation speed, cost tracking, and efficiency metrics
+ * - **Quality Assessment**: Vector quality evaluation and embedding effectiveness measurement
+ *
+ * @example
+ * ```typescript
+ * // Text embedding generation
+ * const embedding = startObservation('text-embedder', {
+ *   input: {
+ *     texts: [
+ *       'Machine learning is a subset of AI',
+ *       'Deep learning uses neural networks'
+ *     ],
+ *     batchSize: 2
+ *   },
+ *   model: 'text-embedding-ada-002'
+ * }, { asType: 'embedding' });
+ *
+ * const embedResult = await generateEmbeddings({
+ *   texts: [
+ *     'Machine learning is a subset of AI',
+ *     'Deep learning uses neural networks'
+ *   ],
+ *   model: 'text-embedding-ada-002'
+ * });
+ *
+ * embedding.update({
+ *   output: {
+ *     embeddings: embedResult.vectors,
+ *     count: embedResult.vectors.length,
+ *     dimensions: 1536
+ *   },
+ *   usageDetails: {
+ *     totalTokens: embedResult.tokenCount
+ *   },
+ *   metadata: {
+ *     processingTime: 340
+ *   }
+ * });
+ * embedding.end();
+ * ```
+ *
+ * @see {@link startObservation} with `{ asType: 'embedding' }` - Factory function
+ * @see {@link LangfuseRetriever} - For using embeddings in vector search
+ * @see {@link LangfuseGeneration} - For LLM operations that may use embeddings
+ *
+ * @public
+ */
+declare class LangfuseEmbedding extends LangfuseBaseObservation {
+    constructor(params: LangfuseEmbeddingParams);
+    /**
+     * Updates this embedding observation with new attributes.
+     *
+     * @param attributes - Embedding attributes to set
+     * @returns This embedding for method chaining
+     */
+    update(attributes: LangfuseEmbeddingAttributes): LangfuseEmbedding;
+}
+/**
+ * Parameters for creating a Langfuse event.
+ *
+ * @internal
+ */
+type LangfuseEventParams = {
+    otelSpan: Span;
+    attributes?: LangfuseEventAttributes;
+    timestamp: TimeInput;
+};
+/**
+ * Langfuse event wrapper for point-in-time observations.
+ *
+ * Events represent instantaneous occurrences or log entries within a trace.
+ * Unlike spans and generations, they don't have duration and are automatically
+ * ended when created.
+ *
+ * @public
+ */
+declare class LangfuseEvent extends LangfuseBaseObservation {
+    constructor(params: LangfuseEventParams);
+}
+
+/**
+ * Creates OpenTelemetry attributes from Langfuse trace attributes.
+ *
+ * Converts user-friendly trace attributes into the internal OpenTelemetry
+ * attribute format required by the span processor.
+ *
+ * @param attributes - Langfuse trace attributes to convert
+ * @returns OpenTelemetry attributes object with non-null values
+ *
+ * @example
+ * ```typescript
+ * import { createTraceAttributes } from '@elasticdash/tracing';
+ *
+ * const otelAttributes = createTraceAttributes({
+ *   name: 'user-checkout-flow',
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ *   tags: ['checkout', 'payment'],
+ *   metadata: { version: '2.1.0' }
+ * });
+ *
+ * span.setAttributes(otelAttributes);
+ * ```
+ *
+ * @public
+ */
+declare function createTraceAttributes({ name, userId, sessionId, version, release, input, output, metadata, tags, environment, public: isPublic, }?: LangfuseTraceAttributes): Attributes;
+declare function createObservationAttributes(type: LangfuseObservationType, attributes: LangfuseObservationAttributes): Attributes;
+
+/**
+ * Sets an isolated TracerProvider for Langfuse tracing operations.
+ *
+ * This allows Langfuse to use its own TracerProvider instance, separate from
+ * the global OpenTelemetry TracerProvider. This is useful for avoiding conflicts
+ * with other OpenTelemetry instrumentation in the application.
+ *
+ * ⚠️  **Limitation: Span Context Sharing**
+ *
+ * While this function isolates span processing and export, it does NOT provide
+ * complete trace isolation. OpenTelemetry context (trace IDs, parent spans) is
+ * still shared between the global and isolated providers. This means:
+ *
+ * - Spans created with the isolated provider inherit trace IDs from global spans
+ * - Spans created with the isolated provider inherit parent relationships from global spans
+ * - This can result in spans from different providers being part of the same logical trace
+ *
+ * **Why this happens:**
+ * OpenTelemetry uses a global context propagation mechanism that operates at the
+ * JavaScript runtime level, independent of individual TracerProvider instances.
+ * The context (containing trace ID, span ID) flows through async boundaries and
+ * is inherited by all spans created within that context, regardless of which
+ * TracerProvider creates them.
+ *
+ * @example
+ * ```typescript
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { LangfuseSpanProcessor } from '@elasticdash/otel';
+ * import { setLangfuseTracerProvider } from '@elasticdash/tracing';
+ *
+ * // Create provider with span processors in constructor
+ * const provider = new NodeTracerProvider({
+ *   spanProcessors: [new LangfuseSpanProcessor()]
+ * });
+ *
+ * setLangfuseTracerProvider(provider);
+ *
+ * // Note: Spans created with getLangfuseTracer() may still inherit
+ * // context from spans created with the global tracer
+ * ```
+ *
+ * @param provider - The TracerProvider instance to use, or null to clear the isolated provider
+ * @public
+ */
+declare function setLangfuseTracerProvider(provider: TracerProvider | null): void;
+/**
+ * Gets the TracerProvider for Langfuse tracing operations.
+ *
+ * Returns the isolated TracerProvider if one has been set via setLangfuseTracerProvider(),
+ * otherwise falls back to the global OpenTelemetry TracerProvider.
+ *
+ * @example
+ * ```typescript
+ * import { getLangfuseTracerProvider } from '@elasticdash/tracing';
+ *
+ * const provider = getLangfuseTracerProvider();
+ * const tracer = provider.getTracer('my-tracer', '1.0.0');
+ * ```
+ *
+ * @returns The TracerProvider instance to use for Langfuse tracing
+ * @public
+ */
+declare function getLangfuseTracerProvider(): TracerProvider;
+/**
+ * Gets the OpenTelemetry tracer instance for Langfuse.
+ *
+ * This function returns a tracer specifically configured for Langfuse
+ * with the correct tracer name and version. Used internally by all
+ * Langfuse tracing functions to ensure consistent trace creation.
+ *
+ * @returns The Langfuse OpenTelemetry tracer instance
+ *
+ * @example
+ * ```typescript
+ * import { getLangfuseTracer } from '@elasticdash/tracing';
+ *
+ * const tracer = getLangfuseTracer();
+ * const span = tracer.startSpan('my-operation');
+ * ```
+ *
+ * @public
+ */
+declare function getLangfuseTracer(): _opentelemetry_api.Tracer;
+
+/**
+ * Options for starting observations (spans, generations, events).
+ *
+ * @public
+ */
+type StartObservationOptions = {
+    /** Custom start time for the observation */
+    startTime?: Date;
+    /** Parent span context to attach this observation to */
+    parentSpanContext?: SpanContext;
+};
+/**
+ * Options for starting an observations set to active in context
+ *
+ * Extends StartObservationOptions with additional context-specific configuration.
+ *
+ * @public
+ */
+type StartActiveObservationContext = StartObservationOptions & {
+    /** Whether to automatically end the observation when exiting the context. Default is true */
+    endOnExit?: boolean;
+};
+/**
+ * Options for startObservation function.
+ *
+ * @public
+ */
+type StartObservationOpts = StartObservationOptions & {
+    /** Type of observation to create. Defaults to 'span' */
+    asType?: LangfuseObservationType;
+};
+/**
+ * Options for startActiveObservation function.
+ *
+ * @public
+ */
+type StartActiveObservationOpts = StartActiveObservationContext & {
+    /** Type of observation to create. Defaults to 'span' */
+    asType?: LangfuseObservationType;
+};
+declare function startObservation(name: string, attributes: LangfuseGenerationAttributes, options: StartObservationOpts & {
+    asType: "generation";
+}): LangfuseGeneration;
+declare function startObservation(name: string, attributes: LangfuseEventAttributes, options: StartObservationOpts & {
+    asType: "event";
+}): LangfuseEvent;
+declare function startObservation(name: string, attributes: LangfuseAgentAttributes, options: StartObservationOpts & {
+    asType: "agent";
+}): LangfuseAgent;
+declare function startObservation(name: string, attributes: LangfuseToolAttributes, options: StartObservationOpts & {
+    asType: "tool";
+}): LangfuseTool;
+declare function startObservation(name: string, attributes: LangfuseChainAttributes, options: StartObservationOpts & {
+    asType: "chain";
+}): LangfuseChain;
+declare function startObservation(name: string, attributes: LangfuseRetrieverAttributes, options: StartObservationOpts & {
+    asType: "retriever";
+}): LangfuseRetriever;
+declare function startObservation(name: string, attributes: LangfuseEvaluatorAttributes, options: StartObservationOpts & {
+    asType: "evaluator";
+}): LangfuseEvaluator;
+declare function startObservation(name: string, attributes: LangfuseGuardrailAttributes, options: StartObservationOpts & {
+    asType: "guardrail";
+}): LangfuseGuardrail;
+declare function startObservation(name: string, attributes: LangfuseEmbeddingAttributes, options: StartObservationOpts & {
+    asType: "embedding";
+}): LangfuseEmbedding;
+declare function startObservation(name: string, attributes?: LangfuseSpanAttributes, options?: StartObservationOpts & {
+    asType?: "span";
+}): LangfuseSpan;
+declare function startActiveObservation<F extends (generation: LangfuseGeneration) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "generation";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (embedding: LangfuseEmbedding) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "embedding";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (agent: LangfuseAgent) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "agent";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (tool: LangfuseTool) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "tool";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (chain: LangfuseChain) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "chain";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (retriever: LangfuseRetriever) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "retriever";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (evaluator: LangfuseEvaluator) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "evaluator";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (guardrail: LangfuseGuardrail) => unknown>(name: string, fn: F, options: StartActiveObservationOpts & {
+    asType: "guardrail";
+}): ReturnType<F>;
+declare function startActiveObservation<F extends (span: LangfuseSpan) => unknown>(name: string, fn: F, options?: StartActiveObservationOpts & {
+    asType?: "span";
+}): ReturnType<F>;
+/**
+ * Updates the currently active trace with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span and updates
+ * it with trace-level attributes. If no active span is found, a warning is logged.
+ *
+ * @param attributes - Trace attributes to set
+ *
+ * @example
+ * ```typescript
+ * import { updateActiveTrace } from '@elasticdash/tracing';
+ *
+ * // Inside an active span context
+ * updateActiveTrace({
+ *   name: 'user-workflow',
+ *   userId: '123',
+ *   sessionId: 'session-456',
+ *   tags: ['production', 'critical'],
+ *   public: true
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function updateActiveTrace(attributes: LangfuseTraceAttributes): void;
+/**
+ * Updates the currently active observation with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span in the execution context
+ * and updates it with Langfuse-specific attributes. It supports all observation types
+ * through TypeScript overloads, providing type safety for attributes based on the
+ * specified `asType` parameter. If no active span exists, the update is skipped with a warning.
+ *
+ * ## Type Safety
+ * - Automatic type inference based on `asType` parameter
+ * - Compile-time validation of attribute compatibility
+ * - IntelliSense support for observation-specific attributes
+ *
+ * ## Context Requirements
+ * - Must be called within an active OpenTelemetry span context
+ * - Typically used inside `startActiveObservation` callbacks or manual span contexts
+ * - Relies on OpenTelemetry's context propagation mechanism
+ *
+ * ## Supported Observation Types
+ * - **span** (default): General-purpose operations and workflows
+ * - **generation**: LLM calls and AI model interactions
+ * - **agent**: AI agent workflows with tool usage
+ * - **tool**: Individual tool calls and API requests
+ * - **chain**: Multi-step processes and pipelines
+ * - **retriever**: Document retrieval and search operations
+ * - **evaluator**: Quality assessment and scoring
+ * - **guardrail**: Safety checks and content filtering
+ * - **embedding**: Text embedding and vector operations
+ *
+ * @param attributes - Observation-specific attributes to update (type varies by observation type)
+ * @param options - Configuration specifying observation type (defaults to 'span')
+ *
+ * @example
+ * ```typescript
+ * import { updateActiveObservation, startActiveObservation } from '@elasticdash/tracing';
+ *
+ * // Update active span (default)
+ * await startActiveObservation('data-processing', async (observation) => {
+ *   // Process data...
+ *   const result = await processData(inputData);
+ *
+ *   // Update with results
+ *   updateActiveObservation({
+ *     output: { processedRecords: result.count },
+ *     metadata: { processingTime: result.duration }
+ *   });
+ * });
+ *
+ * // Update active generation
+ * await startActiveObservation('llm-call', async () => {
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4',
+ *     messages: [{ role: 'user', content: 'Hello' }]
+ *   });
+ *
+ *   // Update with LLM-specific attributes
+ *   updateActiveObservation({
+ *     output: response.choices[0].message,
+ *     usageDetails: {
+ *       promptTokens: response.usage.prompt_tokens,
+ *       completionTokens: response.usage.completion_tokens,
+ *       totalTokens: response.usage.total_tokens
+ *     },
+ *     costDetails: {
+ *       totalCost: 0.025,
+ *       currency: 'USD'
+ *     }
+ *   }, { asType: 'generation' });
+ * }, {}, { asType: 'generation' });
+ *
+ * // Update active tool execution
+ * await startActiveObservation('web-search', async () => {
+ *   const results = await searchAPI('latest news');
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       results: results,
+ *       count: results.length,
+ *       relevanceScore: 0.89
+ *     },
+ *     metadata: {
+ *       searchLatency: 150,
+ *       cacheHit: false
+ *     }
+ *   }, { asType: 'tool' });
+ * }, {}, { asType: 'tool' });
+ *
+ * // Update active agent workflow
+ * await startActiveObservation('research-agent', async () => {
+ *   // Agent performs multiple operations...
+ *   const findings = await conductResearch();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       completed: true,
+ *       toolsUsed: ['web-search', 'summarizer'],
+ *       iterationsRequired: 3,
+ *       confidence: 0.92
+ *     },
+ *     metadata: {
+ *       efficiency: 0.85,
+ *       qualityScore: 0.88
+ *     }
+ *   }, { asType: 'agent' });
+ * }, {}, { asType: 'agent' });
+ *
+ * // Update active chain workflow
+ * await startActiveObservation('rag-pipeline', async () => {
+ *   // Execute multi-step RAG process...
+ *   const finalResponse = await executeRAGPipeline();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       finalResponse: finalResponse,
+ *       stepsCompleted: 4,
+ *       documentsRetrieved: 8,
+ *       qualityScore: 0.91
+ *     },
+ *     metadata: {
+ *       pipelineEfficiency: 0.87,
+ *       totalLatency: 3200
+ *     }
+ *   }, { asType: 'chain' });
+ * }, {}, { asType: 'chain' });
+ * ```
+ *
+ * @see {@link startActiveObservation} - For creating active observation contexts
+ * @see {@link updateActiveTrace} - For updating trace-level attributes
+ *
+ * @public
+ */
+declare function updateActiveObservation(attributes: LangfuseSpanAttributes, options?: {
+    asType: "span";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGenerationAttributes, options: {
+    asType: "generation";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseAgentAttributes, options: {
+    asType: "agent";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseToolAttributes, options: {
+    asType: "tool";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseChainAttributes, options: {
+    asType: "chain";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEmbeddingAttributes, options: {
+    asType: "embedding";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEvaluatorAttributes, options: {
+    asType: "evaluator";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGuardrailAttributes, options: {
+    asType: "guardrail";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseRetrieverAttributes, options: {
+    asType: "retriever";
+}): void;
+/**
+ * Options for the observe decorator function.
+ *
+ * @public
+ */
+interface ObserveOptions {
+    /** Name for the observation (defaults to function name) */
+    name?: string;
+    /** Type of observation to create */
+    asType?: LangfuseObservationType;
+    /** Whether to capture function input as observation input */
+    captureInput?: boolean;
+    /** Whether to capture function output as observation output */
+    captureOutput?: boolean;
+    /** Parent span context to attach this observation to */
+    parentSpanContext?: SpanContext;
+    /** Whether to automatically end the observation when exiting the context. Default is true */
+    endOnExit?: boolean;
+}
+/**
+ * Decorator function that automatically wraps any function with Langfuse observability.
+ *
+ * This higher-order function creates a traced version of your function that automatically
+ * handles observation lifecycle, input/output capture, and error tracking. It's perfect
+ * for instrumenting existing functions without modifying their internal logic.
+ *
+ * ## Key Features
+ * - **Zero Code Changes**: Wrap existing functions without modifying their implementation
+ * - **Automatic I/O Capture**: Optionally captures function arguments and return values
+ * - **Error Tracking**: Automatically captures exceptions and sets error status
+ * - **Type Preservation**: Maintains original function signature and return types
+ * - **Async Support**: Works seamlessly with both sync and async functions
+ * - **Flexible Configuration**: Control observation type, naming, and capture behavior
+ *
+ * ## Use Cases
+ * - Instrumenting business logic functions
+ * - Wrapping API calls and external service interactions
+ * - Adding observability to utility functions
+ * - Creating traced versions of third-party functions
+ * - Decorating class methods for observability
+ *
+ * @param fn - The function to wrap with observability (preserves original signature)
+ * @param options - Configuration for observation behavior and capture settings
+ * @returns An instrumented version of the function with identical behavior plus tracing
+ *
+ * @example
+ * ```typescript
+ * import { observe } from '@elasticdash/tracing';
+ *
+ * // Basic function wrapping with automatic I/O capture
+ * const processOrder = observe(
+ *   async (orderId: string, items: CartItem[]) => {
+ *     const validation = await validateOrder(orderId, items);
+ *     const payment = await processPayment(validation);
+ *     const shipping = await scheduleShipping(payment);
+ *     return { orderId, status: 'confirmed', trackingId: shipping.id };
+ *   },
+ *   {
+ *     name: 'process-order',
+ *     asType: 'span',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // LLM function with generation tracking
+ * const generateSummary = observe(
+ *   async (document: string, maxWords: number = 100) => {
+ *     const response = await openai.chat.completions.create({
+ *       model: 'gpt-4-turbo',
+ *       messages: [
+ *         { role: 'system', content: `Summarize in ${maxWords} words or less` },
+ *         { role: 'user', content: document }
+ *       ],
+ *       max_tokens: maxWords * 2
+ *     });
+ *     return response.choices[0].message.content;
+ *   },
+ *   {
+ *     name: 'document-summarizer',
+ *     asType: 'generation',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Database query with automatic error tracking
+ * const fetchUserProfile = observe(
+ *   async (userId: string) => {
+ *     const user = await db.users.findUnique({ where: { id: userId } });
+ *     if (!user) throw new Error(`User ${userId} not found`);
+ *
+ *     const preferences = await db.preferences.findMany({
+ *       where: { userId }
+ *     });
+ *
+ *     return { ...user, preferences };
+ *   },
+ *   {
+ *     name: 'fetch-user-profile',
+ *     asType: 'span',
+ *     captureInput: false, // Don't capture sensitive user IDs
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Vector search with retriever semantics
+ * const searchDocuments = observe(
+ *   async (query: string, topK: number = 5) => {
+ *     const embedding = await embedText(query);
+ *     const results = await vectorDb.search(embedding, topK);
+ *     return results.map(r => ({
+ *       content: r.metadata.content,
+ *       score: r.score,
+ *       source: r.metadata.source
+ *     }));
+ *   },
+ *   {
+ *     name: 'document-search',
+ *     asType: 'retriever',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Quality evaluation function
+ * const evaluateResponse = observe(
+ *   (response: string, reference: string, metric: string = 'similarity') => {
+ *     let score: number;
+ *
+ *     switch (metric) {
+ *       case 'similarity':
+ *         score = calculateCosineSimilarity(response, reference);
+ *         break;
+ *       case 'bleu':
+ *         score = calculateBleuScore(response, reference);
+ *         break;
+ *       default:
+ *         throw new Error(`Unknown metric: ${metric}`);
+ *     }
+ *
+ *     return {
+ *       score,
+ *       passed: score > 0.8,
+ *       metric,
+ *       grade: score > 0.9 ? 'excellent' : score > 0.7 ? 'good' : 'needs_improvement'
+ *     };
+ *   },
+ *   {
+ *     name: 'response-evaluator',
+ *     asType: 'evaluator',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Content moderation with guardrails
+ * const moderateContent = observe(
+ *   async (text: string, policies: string[] = ['profanity', 'spam']) => {
+ *     const violations = [];
+ *
+ *     for (const policy of policies) {
+ *       const result = await checkPolicy(text, policy);
+ *       if (result.violation) {
+ *         violations.push({ policy, severity: result.severity });
+ *       }
+ *     }
+ *
+ *     return {
+ *       allowed: violations.length === 0,
+ *       violations,
+ *       confidence: 0.95
+ *     };
+ *   },
+ *   {
+ *     name: 'content-moderator',
+ *     asType: 'guardrail',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // AI agent function with tool usage
+ * const researchAgent = observe(
+ *   async (query: string, maxSources: number = 3) => {
+ *     // Search for relevant documents
+ *     const documents = await searchDocuments(query, maxSources * 2);
+ *
+ *     // Filter and rank results
+ *     const topDocs = documents
+ *       .filter(d => d.score > 0.7)
+ *       .slice(0, maxSources);
+ *
+ *     // Generate comprehensive answer
+ *     const context = topDocs.map(d => d.content).join('\n\n');
+ *     const answer = await generateSummary(
+ *       `Based on: ${context}\n\nQuestion: ${query}`,
+ *       200
+ *     );
+ *
+ *     return {
+ *       answer,
+ *       sources: topDocs.map(d => d.source),
+ *       confidence: Math.min(...topDocs.map(d => d.score))
+ *     };
+ *   },
+ *   {
+ *     name: 'research-agent',
+ *     asType: 'agent',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Class method decoration
+ * class UserService {
+ *   private db: Database;
+ *
+ *   // Wrap methods during class construction
+ *   constructor(database: Database) {
+ *     this.db = database;
+ *     this.createUser = observe(this.createUser.bind(this), {
+ *       name: 'create-user',
+ *       asType: 'span',
+ *       captureInput: false, // Sensitive data
+ *       captureOutput: true
+ *     });
+ *   }
+ *
+ *   async createUser(userData: UserData) {
+ *     // Implementation automatically traced
+ *     return await this.db.users.create(userData);
+ *   }
+ * }
+ *
+ * // Chain composition - functions remain composable
+ * const processDocument = observe(
+ *   async (document: string) => {
+ *     const summary = await generateSummary(document, 150);
+ *     const moderation = await moderateContent(summary);
+ *     const evaluation = evaluateResponse(summary, document, 'similarity');
+ *
+ *     return {
+ *       summary: moderation.allowed ? summary : '[Content Filtered]',
+ *       safe: moderation.allowed,
+ *       quality: evaluation.score
+ *     };
+ *   },
+ *   {
+ *     name: 'document-processor',
+ *     asType: 'chain',
+ *     captureInput: true,
+ *     captureOutput: true
+ *   }
+ * );
+ *
+ * // Usage - functions work exactly as before, just with observability
+ * const order = await processOrder('ord_123', cartItems);
+ * const profile = await fetchUserProfile('user_456');
+ * const research = await researchAgent('What is quantum computing?');
+ * const processed = await processDocument(documentText);
+ * ```
+ *
+ * @see {@link startObservation} for manual observation creation
+ * @see {@link startActiveObservation} for function-scoped observations
+ *
+ * @public
+ */
+declare function observe<T extends (...args: any[]) => any>(fn: T, options?: ObserveOptions): T;
+/**
+ * Creates a trace ID for OpenTelemetry spans.
+ *
+ * @param seed - A seed string for deterministic trace ID generation.
+ *               If provided (non-empty), the same seed will always generate the same trace ID.
+ *               If empty or falsy, generates a random trace ID.
+ *
+ *               Using a seed is especially useful when trying to correlate external,
+ *               non-W3C compliant IDs with Langfuse trace IDs. This allows you to later
+ *               have a method available for scoring the Langfuse trace given only the
+ *               external ID by regenerating the same trace ID from the external ID.
+ *
+ * @returns A Promise that resolves to a 32-character lowercase hexadecimal string suitable for use as an OpenTelemetry trace ID.
+ *
+ * @example
+ * ```typescript
+ * // Deterministic trace ID from seed
+ * const traceId1 = await createTraceId("my-session-123");
+ * const traceId2 = await createTraceId("my-session-123");
+ * console.log(traceId1 === traceId2); // true
+ *
+ * // Random trace ID
+ * const randomId1 = await createTraceId("");
+ * const randomId2 = await createTraceId("");
+ * console.log(randomId1 === randomId2); // false
+ *
+ * // Use with spans
+ * const span = startObservation("my-span", {}, {
+ *   parentSpanContext: {
+ *     traceId: await createTraceId("session-456"),
+ *     spanId: "0123456789abcdef",
+ *     traceFlags: 1
+ *   }
+ * });
+ *
+ * // Correlating external IDs with Langfuse traces
+ * const externalId = "ext-12345-67890";
+ * const traceId = await createTraceId(externalId);
+ *
+ * // Later, when you need to score this trace, regenerate the same ID
+ * const scoringTraceId = await createTraceId(externalId);
+ * console.log(traceId === scoringTraceId); // true - can now find and score the trace
+ * ```
+ *
+ * @public
+ */
+declare function createTraceId(seed?: string): Promise<string>;
+/**
+ * Gets the current active trace ID.
+ *
+ * If there is no span in the current context, returns undefined.
+ *
+ * @returns The trace ID of the currently active span, or undefined if no span is active
+ *
+ * @public
+ */
+declare function getActiveTraceId(): string | undefined;
+/**
+ * Gets the current active observation ID.
+ *
+ * If there is no OTEL span in the current context, returns undefined.
+ *
+ * @returns The ID of the currently active OTEL span, or undefined if no OTEL span is active
+ *
+ * @public
+ */
+declare function getActiveSpanId(): string | undefined;
+
+export { LangfuseAgent, LangfuseChain, LangfuseEmbedding, LangfuseEvaluator, LangfuseEvent, type LangfuseEventAttributes, LangfuseGeneration, type LangfuseGenerationAttributes, LangfuseGuardrail, type LangfuseObservation, type LangfuseObservationAttributes, type LangfuseObservationType, LangfuseRetriever, LangfuseSpan, type LangfuseSpanAttributes, LangfuseTool, type LangfuseTraceAttributes, type ObservationLevel, type ObserveOptions, type StartActiveObservationContext, type StartActiveObservationOpts, type StartObservationOptions, type StartObservationOpts, createObservationAttributes, createTraceAttributes, createTraceId, getActiveSpanId, getActiveTraceId, getLangfuseTracer, getLangfuseTracerProvider, observe, setLangfuseTracerProvider, startActiveObservation, startObservation, updateActiveObservation, updateActiveTrace };