@langfuse/tracing 4.0.0-beta.6 → 4.0.0-beta.8

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { LangfuseOtelSpanAttributes } from '@langfuse/core';
  *
  * @public
  */
-type LangfuseObservationType = "span" | "generation" | "event";
+type LangfuseObservationType = "span" | "generation" | "event" | "embedding" | "agent" | "tool" | "chain" | "retriever" | "evaluator" | "guardrail";
 /**
  * Severity levels for observations in Langfuse.
  *
@@ -49,15 +49,6 @@ type LangfuseSpanAttributes = {
     /** Environment where the operation is running (e.g., 'production', 'staging') */
     environment?: string;
 };
-/**
- * Attributes for Langfuse event observations.
- *
- * Events represent point-in-time occurrences or log entries within a trace.
- * Unlike spans, they don't have duration and are automatically ended when created.
- *
- * @public
- */
-type LangfuseEventAttributes = LangfuseSpanAttributes;
 /**
  * Attributes for Langfuse generation observations.
  *
@@ -70,10 +61,10 @@ 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 | null;
+    model?: string;
     /** Parameters passed to the model (temperature, max_tokens, etc.) */
     modelParameters?: {
-        [key: string]: string | number | null;
+        [key: string]: string | number;
     };
     /** Token usage and other model-specific usage metrics */
     usageDetails?: {
@@ -93,6 +84,14 @@ type LangfuseGenerationAttributes = LangfuseSpanAttributes & {
         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.
  *
@@ -100,7 +99,7 @@ type LangfuseGenerationAttributes = LangfuseSpanAttributes & {
  *
  * @public
  */
-type LangfuseAttributes = LangfuseSpanAttributes | LangfuseGenerationAttributes | LangfuseEventAttributes;
+type LangfuseObservationAttributes = LangfuseSpanAttributes & LangfuseGenerationAttributes & LangfuseEventAttributes & LangfuseAgentAttributes & LangfuseToolAttributes & LangfuseChainAttributes & LangfuseRetrieverAttributes & LangfuseEvaluatorAttributes & LangfuseGuardrailAttributes;
 /**
  * Attributes for Langfuse traces.
  *
@@ -137,38 +136,121 @@ type LangfuseTraceAttributes = {
 /**
  * Union type representing any Langfuse observation wrapper.
  *
- * Used when you need to accept any type of Langfuse observation
- * (span, generation, or event).
+ * 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;
+type LangfuseObservation = LangfuseSpan | LangfuseGeneration | LangfuseEvent | LangfuseAgent | LangfuseTool | LangfuseChain | LangfuseRetriever | LangfuseEvaluator | LangfuseGuardrail | LangfuseEmbedding;
 /**
- * Parameters for creating a Langfuse span wrapper.
+ * Parameters for creating a Langfuse observation wrapper.
  *
  * @internal
  */
-type LangfuseSpanWrapperParams = {
+type LangfuseObservationParams = {
     otelSpan: Span;
+    type: LangfuseObservationType;
     attributes?: LangfuseSpanAttributes | LangfuseGenerationAttributes | LangfuseEventAttributes;
 };
 /**
- * Base class for all Langfuse observation wrappers.
+ * 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' }
+ * });
  *
- * Provides common functionality for spans, generations, and events including
- * access to the underlying OpenTelemetry span, span ID, trace ID, and basic
- * operations like ending the observation and updating trace attributes.
+ * // End observations
+ * child.end();
+ * observation.end();
+ * ```
  *
  * @internal
  */
-declare abstract class LangfuseSpanWrapper {
+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: LangfuseSpanWrapperParams);
+    constructor(params: LangfuseObservationParams);
     /** Gets the Langfuse OpenTelemetry tracer instance */
     protected get tracer(): _opentelemetry_api.Tracer;
     /**
@@ -177,6 +259,7 @@ declare abstract class LangfuseSpanWrapper {
      * @param endTime - Optional end time, defaults to current time
      */
     end(endTime?: TimeInput): void;
+    updateOtelSpanAttributes(attributes: LangfuseObservationAttributes): void;
     /**
      * Updates the parent trace with new attributes.
      *
@@ -187,26 +270,289 @@ declare abstract class LangfuseSpanWrapper {
      * @returns This observation for method chaining
      */
     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;
 }
-/**
- * Parameters for creating a Langfuse span.
- *
- * @internal
- */
 type LangfuseSpanParams = {
     otelSpan: Span;
     attributes?: LangfuseSpanAttributes;
 };
 /**
- * Langfuse span wrapper for general-purpose tracing.
+ * 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
  *
- * Spans are used to track operations, functions, or logical units of work.
- * They can contain other spans, generations, or events as children and have
- * a duration from start to end.
+ * @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 LangfuseSpanWrapper {
+declare class LangfuseSpan extends LangfuseBaseObservation {
     constructor(params: LangfuseSpanParams);
     /**
      * Updates this span with new attributes.
@@ -224,57 +570,574 @@ declare class LangfuseSpan extends LangfuseSpanWrapper {
      * ```
      */
     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);
     /**
-     * Starts a new child span within this span.
+     * Updates this agent observation with new attributes.
      *
-     * @param name - Name of the child span
-     * @param attributes - Optional attributes for the child span
-     * @returns The new child span
+     * @param attributes - Agent attributes to set
+     * @returns This agent for method chaining
      *
      * @example
      * ```typescript
-     * const childSpan = parentSpan.startSpan('database-query', {
-     *   input: { query: 'SELECT * FROM users' },
-     *   metadata: { database: 'primary' }
+     * 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 }
+     *   }
      * });
      * ```
      */
-    startSpan(name: string, attributes?: LangfuseSpanAttributes): LangfuseSpan;
+    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);
     /**
-     * Starts a new child generation within this span.
+     * Updates this tool observation with new attributes.
      *
-     * @param name - Name of the generation (typically the model name)
-     * @param attributes - Optional generation-specific attributes
-     * @returns The new child generation
+     * @param attributes - Tool attributes to set
+     * @returns This tool for method chaining
      *
      * @example
      * ```typescript
-     * const generation = parentSpan.startGeneration('gpt-4', {
-     *   input: [{ role: 'user', content: 'Hello!' }],
-     *   model: 'gpt-4',
-     *   modelParameters: { temperature: 0.7 }
+     * tool.update({
+     *   output: {
+     *     result: searchResults,
+     *     count: searchResults.length,
+     *     relevanceScore: 0.89,
+     *     executionTime: 1250
+     *   },
+     *   metadata: {
+     *     cacheHit: false,
+     *     apiCost: 0.025,
+     *     rateLimitRemaining: 950
+     *   }
      * });
      * ```
      */
-    startGeneration(name: string, attributes?: LangfuseGenerationAttributes): LangfuseGeneration;
+    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);
     /**
-     * Creates a new event within this span.
+     * Updates this chain observation with new attributes.
      *
-     * Events are point-in-time occurrences and are automatically ended.
-     *
-     * @param name - Name of the event
-     * @param attributes - Optional event attributes
-     * @returns The created event (already ended)
+     * @param attributes - Chain attributes to set
+     * @returns This chain for method chaining
      *
      * @example
      * ```typescript
-     * parentSpan.createEvent('user-action', {
-     *   input: { action: 'click', button: 'submit' },
-     *   metadata: { userId: '123' }
+     * 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']
+     *   }
      * });
      * ```
      */
-    createEvent(name: string, attributes?: LangfuseEventAttributes): LangfuseEvent;
+    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.
@@ -286,53 +1149,196 @@ type LangfuseGenerationParams = {
     attributes?: LangfuseGenerationAttributes;
 };
 /**
- * Langfuse generation wrapper for tracking LLM interactions.
+ * 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
  *
- * Generations are specialized observations for tracking language model
- * calls, including model parameters, usage metrics, costs, and prompts.
+ * @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 LangfuseSpanWrapper {
+declare class LangfuseGeneration extends LangfuseBaseObservation {
     constructor(params: LangfuseGenerationParams);
-    /**
-     * Updates this generation with new attributes.
-     *
-     * @param attributes - Generation attributes to set
-     * @returns This generation for method chaining
-     *
-     * @example
-     * ```typescript
-     * generation.update({
-     *   output: { role: 'assistant', content: 'Hello there!' },
-     *   usageDetails: {
-     *     promptTokens: 10,
-     *     completionTokens: 15,
-     *     totalTokens: 25
-     *   },
-     *   costDetails: { totalCost: 0.001 }
-     * });
-     * ```
-     */
     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);
     /**
-     * Creates a new event within this generation.
-     *
-     * Events are point-in-time occurrences and are automatically ended.
+     * Updates this embedding observation with new attributes.
      *
-     * @param name - Name of the event
-     * @param attributes - Optional event attributes
-     * @returns The created event (already ended)
-     *
-     * @example
-     * ```typescript
-     * generation.createEvent('token-limit-reached', {
-     *   level: 'WARNING',
-     *   metadata: { requestedTokens: 2000, maxTokens: 1500 }
-     * });
-     * ```
+     * @param attributes - Embedding attributes to set
+     * @returns This embedding for method chaining
      */
-    createEvent(name: string, attributes?: LangfuseEventAttributes): LangfuseEvent;
+    update(attributes: LangfuseEmbeddingAttributes): LangfuseEmbedding;
 }
 /**
  * Parameters for creating a Langfuse event.
@@ -353,7 +1359,7 @@ type LangfuseEventParams = {
  *
  * @public
  */
-declare class LangfuseEvent extends LangfuseSpanWrapper {
+declare class LangfuseEvent extends LangfuseBaseObservation {
     constructor(params: LangfuseEventParams);
 }
 
@@ -384,65 +1390,7 @@ declare class LangfuseEvent extends LangfuseSpanWrapper {
  * @public
  */
 declare function createTraceAttributes({ name, userId, sessionId, version, release, input, output, metadata, tags, environment, public: isPublic, }?: LangfuseTraceAttributes): Attributes;
-/**
- * Creates OpenTelemetry attributes from Langfuse span attributes.
- *
- * Converts user-friendly span attributes into the internal OpenTelemetry
- * attribute format required by the span processor.
- *
- * @param attributes - Langfuse span attributes to convert
- * @returns OpenTelemetry attributes object with non-null values
- *
- * @example
- * ```typescript
- * import { createSpanAttributes } from '@langfuse/tracing';
- *
- * const otelAttributes = createSpanAttributes({
- *   input: { query: 'SELECT * FROM users' },
- *   output: { rowCount: 42 },
- *   level: 'DEFAULT',
- *   metadata: { database: 'prod' }
- * });
- *
- * span.setAttributes(otelAttributes);
- * ```
- *
- * @public
- */
-declare function createSpanAttributes({ metadata, input, output, level, statusMessage, version, }: LangfuseSpanAttributes): Attributes;
-/**
- * Creates OpenTelemetry attributes from Langfuse generation attributes.
- *
- * Converts user-friendly generation attributes into the internal OpenTelemetry
- * attribute format required by the span processor. Includes special handling
- * for LLM-specific fields like model parameters, usage, and costs.
- *
- * @param attributes - Langfuse generation attributes to convert
- * @returns OpenTelemetry attributes object with non-null values
- *
- * @example
- * ```typescript
- * import { createGenerationAttributes } from '@langfuse/tracing';
- *
- * const otelAttributes = createGenerationAttributes({
- *   input: [{ role: 'user', content: 'Hello!' }],
- *   output: { role: 'assistant', content: 'Hi there!' },
- *   model: 'gpt-4',
- *   modelParameters: { temperature: 0.7 },
- *   usageDetails: {
- *     promptTokens: 10,
- *     completionTokens: 15,
- *     totalTokens: 25
- *   },
- *   costDetails: { totalCost: 0.001 }
- * });
- *
- * span.setAttributes(otelAttributes);
- * ```
- *
- * @public
- */
-declare function createGenerationAttributes({ completionStartTime, metadata, level, statusMessage, version, model, modelParameters, input, output, usageDetails, costDetails, prompt, }: LangfuseGenerationAttributes): Attributes;
+declare function createObservationAttributes(type: LangfuseObservationType, attributes: LangfuseObservationAttributes): Attributes;
 
 /**
  * Sets an isolated TracerProvider for Langfuse tracing operations.
@@ -551,201 +1499,80 @@ type StartActiveObservationContext = StartObservationOptions & {
     endOnExit?: boolean;
 };
 /**
- * Creates and starts a new Langfuse span for general-purpose tracing.
- *
- * Spans are used to track operations, functions, or logical units of work.
- * They can contain other spans or generations as children.
- *
- * @param name - Name of the span
- * @param attributes - Optional attributes to set on the span
- * @param options - Optional configuration for the span
- * @returns A LangfuseSpan instance
- *
- * @example
- * ```typescript
- * import { startSpan } from '@langfuse/tracing';
- *
- * const span = startSpan('data-processing', {
- *   input: { userId: '123', data: {...} },
- *   metadata: { version: '1.0' },
- *   level: 'DEFAULT'
- * });
- *
- * try {
- *   // Do some work
- *   const result = await processData();
- *
- *   span.update({ output: result });
- * } catch (error) {
- *   span.update({
- *     level: 'ERROR',
- *     statusMessage: error.message
- *   });
- * } finally {
- *   span.end();
- * }
- * ```
- *
- * @public
- */
-declare function startSpan(name: string, attributes?: LangfuseSpanAttributes, options?: {
-    startTime?: TimeInput;
-    parentSpanContext?: SpanContext;
-}): LangfuseSpan;
-/**
- * Creates and starts a new Langfuse generation for tracking LLM calls.
- *
- * Generations are specialized observations for tracking language model
- * interactions, including model parameters, usage metrics, and costs.
- *
- * @param name - Name of the generation (typically the model or operation)
- * @param attributes - Optional generation-specific attributes
- * @param options - Optional configuration for the generation
- * @returns A LangfuseGeneration instance
- *
- * @example
- * ```typescript
- * import { startGeneration } from '@langfuse/tracing';
- *
- * const generation = startGeneration('openai-gpt-4', {
- *   input: [{ role: 'user', content: 'Hello, world!' }],
- *   model: 'gpt-4',
- *   modelParameters: {
- *     temperature: 0.7,
- *     max_tokens: 150
- *   },
- *   metadata: { feature: 'chat' }
- * });
- *
- * try {
- *   const response = await callOpenAI(messages);
- *
- *   generation.update({
- *     output: response.choices[0].message,
- *     usageDetails: {
- *       promptTokens: response.usage.prompt_tokens,
- *       completionTokens: response.usage.completion_tokens,
- *       totalTokens: response.usage.total_tokens
- *     }
- *   });
- * } finally {
- *   generation.end();
- * }
- * ```
- *
- * @public
- */
-declare function startGeneration(name: string, attributes?: LangfuseGenerationAttributes, options?: StartObservationOptions): LangfuseGeneration;
-/**
- * Creates a Langfuse event for point-in-time occurrences.
- *
- * Events are used to capture instantaneous occurrences or log entries
- * within a trace. Unlike spans, they represent a single point in time.
- *
- * @param name - Name of the event
- * @param attributes - Optional attributes for the event
- * @param options - Optional configuration for the event
- * @returns A LangfuseEvent instance (automatically ended)
- *
- * @example
- * ```typescript
- * import { createEvent } from '@langfuse/tracing';
- *
- * // Log a user action
- * createEvent('user-click', {
- *   input: { buttonId: 'submit', userId: '123' },
- *   metadata: { page: '/checkout' },
- *   level: 'DEFAULT'
- * });
- *
- * // Log an error
- * createEvent('api-error', {
- *   level: 'ERROR',
- *   statusMessage: 'Failed to fetch user data',
- *   metadata: { endpoint: '/api/users/123', statusCode: 500 }
- * });
- * ```
- *
- * @public
- */
-declare function createEvent(name: string, attributes?: LangfuseEventAttributes, options?: StartObservationOptions): LangfuseEvent;
-/**
- * Starts an active span and executes a function within its context.
- *
- * This function creates a span, sets it as the active span in the OpenTelemetry
- * context, executes the provided function, and automatically ends the span.
- * Perfect for wrapping operations where you want child spans to be automatically
- * linked.
- *
- * @param name - Name of the span
- * @param fn - Function to execute within the span context
- * @param options - Optional configuration for the span
- * @returns The return value of the executed function
- *
- * @example
- * ```typescript
- * import { startActiveSpan } from '@langfuse/tracing';
- *
- * // Synchronous function
- * const result = startActiveSpan('calculate-metrics', (span) => {
- *   span.update({ input: { data: rawData } });
- *
- *   const metrics = calculateMetrics(rawData);
- *   span.update({ output: metrics });
- *
- *   return metrics;
- * });
- *
- * // Asynchronous function
- * const data = await startActiveSpan('fetch-user-data', async (span) => {
- *   span.update({ input: { userId: '123' } });
- *
- *   const userData = await api.getUser('123');
- *   span.update({ output: userData });
- *
- *   return userData;
- * });
- * ```
+ * Options for startObservation function.
  *
  * @public
  */
-declare function startActiveSpan<F extends (span: LangfuseSpan) => unknown>(name: string, fn: F, options?: StartActiveObservationContext): ReturnType<F>;
+type StartObservationOpts = StartObservationOptions & {
+    /** Type of observation to create. Defaults to 'span' */
+    asType?: LangfuseObservationType;
+};
 /**
- * Starts an active generation and executes a function within its context.
- *
- * Similar to startActiveSpan but creates a generation for tracking LLM calls.
- * The generation is automatically ended when the function completes.
- *
- * @param name - Name of the generation
- * @param fn - Function to execute within the generation context
- * @param options - Optional configuration for the generation
- * @returns The return value of the executed function
- *
- * @example
- * ```typescript
- * import { startActiveGeneration } from '@langfuse/tracing';
- *
- * const response = await startActiveGeneration('openai-completion', async (generation) => {
- *   generation.update({
- *     input: { messages: [...] },
- *     model: 'gpt-4',
- *     modelParameters: { temperature: 0.7 }
- *   });
- *
- *   const result = await openai.chat.completions.create({...});
- *
- *   generation.update({
- *     output: result.choices[0].message,
- *     usageDetails: result.usage
- *   });
- *
- *   return result;
- * });
- * ```
+ * Options for startActiveObservation function.
  *
  * @public
  */
-declare function startActiveGeneration<F extends (span: LangfuseGeneration) => unknown>(name: string, fn: F, options?: StartActiveObservationContext): ReturnType<F>;
+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.
  *
@@ -771,55 +1598,15 @@ declare function startActiveGeneration<F extends (span: LangfuseGeneration) => u
  * @public
  */
 declare function updateActiveTrace(attributes: LangfuseTraceAttributes): void;
-/**
- * Updates the currently active span with new attributes.
- *
- * This function finds the currently active OpenTelemetry span and updates
- * it with span-level attributes. If no active span is found, a warning is logged.
- *
- * @param attributes - Span attributes to set
- *
- * @example
- * ```typescript
- * import { updateActiveSpan } from '@langfuse/tracing';
- *
- * // Inside an active span context
- * updateActiveSpan({
- *   level: 'WARNING',
- *   statusMessage: 'Operation completed with warnings',
- *   metadata: { warningCount: 3 }
- * });
- * ```
- *
- * @public
- */
-declare function updateActiveSpan(attributes: LangfuseSpanAttributes): void;
-/**
- * Updates the currently active generation with new attributes.
- *
- * This function finds the currently active OpenTelemetry span and updates
- * it with generation-level attributes. If no active span is found, a warning is logged.
- *
- * @param attributes - Generation attributes to set
- *
- * @example
- * ```typescript
- * import { updateActiveGeneration } from '@langfuse/tracing';
- *
- * // Inside an active generation context
- * updateActiveGeneration({
- *   usageDetails: {
- *     promptTokens: 50,
- *     completionTokens: 100,
- *     totalTokens: 150
- *   },
- *   costDetails: { totalCost: 0.003 }
- * });
- * ```
- *
- * @public
- */
-declare function updateActiveGeneration(attributes: LangfuseGenerationAttributes): void;
+declare function updateActiveObservation(currentType: "span", attributes: LangfuseSpanAttributes): void;
+declare function updateActiveObservation(currentType: "generation", attributes: LangfuseGenerationAttributes): void;
+declare function updateActiveObservation(currentType: "agent", attributes: LangfuseAgentAttributes): void;
+declare function updateActiveObservation(currentType: "tool", attributes: LangfuseToolAttributes): void;
+declare function updateActiveObservation(currentType: "chain", attributes: LangfuseChainAttributes): void;
+declare function updateActiveObservation(currentType: "embedding", attributes: LangfuseEmbeddingAttributes): void;
+declare function updateActiveObservation(currentType: "evaluator", attributes: LangfuseEvaluatorAttributes): void;
+declare function updateActiveObservation(currentType: "guardrail", attributes: LangfuseGuardrailAttributes): void;
+declare function updateActiveObservation(currentType: "retriever", attributes: LangfuseRetrieverAttributes): void;
 /**
  * Options for the observe decorator function.
  *
@@ -829,7 +1616,7 @@ interface ObserveOptions {
     /** Name for the observation (defaults to function name) */
     name?: string;
     /** Type of observation to create */
-    asType?: "span" | "generation";
+    asType?: LangfuseObservationType;
     /** Whether to capture function input as observation input */
     captureInput?: boolean;
     /** Whether to capture function output as observation output */
@@ -840,58 +1627,252 @@ interface ObserveOptions {
     endOnExit?: boolean;
 }
 /**
- * Decorator function that automatically wraps a function with Langfuse tracing.
- *
- * This function creates a wrapper around the provided function that automatically:
- * - Creates a span or generation when the function is called
- * - Captures input arguments (if enabled)
- * - Captures return value/output (if enabled)
- * - Handles errors and sets appropriate status
- * - Ends the observation when the function completes
- *
- * @param fn - The function to wrap with tracing
- * @param options - Configuration options for the observation
- * @returns A wrapped version of the function that includes tracing
+ * 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 '@langfuse/tracing';
  *
- * // Wrap a regular function
- * const processData = observe(
- *   async (userId: string, data: any) => {
- *     // Function implementation
- *     return await processUserData(userId, data);
+ * // 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-user-data',
+ *     name: 'process-order',
  *     asType: 'span',
  *     captureInput: true,
  *     captureOutput: true
  *   }
  * );
  *
- * // Wrap an LLM call
- * const generateText = observe(
- *   async (prompt: string) => {
- *     return await openai.chat.completions.create({
- *       model: 'gpt-4',
- *       messages: [{ role: 'user', content: prompt }]
+ * // 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: 'openai-generation',
+ *     name: 'document-summarizer',
  *     asType: 'generation',
  *     captureInput: true,
  *     captureOutput: true
  *   }
  * );
  *
- * // Usage
- * const result = await processData('123', { key: 'value' });
- * const text = await generateText('Hello, world!');
+ * // 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: unknown[]) => unknown>(fn: T, options?: ObserveOptions): T;
@@ -922,7 +1903,7 @@ declare function observe<T extends (...args: unknown[]) => unknown>(fn: T, optio
  * console.log(randomId1 === randomId2); // false
  *
  * // Use with spans
- * const span = startSpan("my-span", {}, {
+ * const span = startObservation("my-span", {}, {
  *   parentSpanContext: {
  *     traceId: await createTraceId("session-456"),
  *     spanId: "0123456789abcdef",
@@ -963,4 +1944,4 @@ declare function getActiveTraceId(): string | undefined;
  */
 declare function getActiveSpanId(): string | undefined;
 
-export { type LangfuseAttributes, LangfuseEvent, type LangfuseEventAttributes, LangfuseGeneration, type LangfuseGenerationAttributes, type LangfuseObservation, type LangfuseObservationType, LangfuseSpan, type LangfuseSpanAttributes, type LangfuseTraceAttributes, type ObservationLevel, type ObserveOptions, type StartActiveObservationContext, type StartObservationOptions, createEvent, createGenerationAttributes, createSpanAttributes, createTraceAttributes, createTraceId, getActiveSpanId, getActiveTraceId, getLangfuseTracer, getLangfuseTracerProvider, observe, setLangfuseTracerProvider, startActiveGeneration, startActiveSpan, startGeneration, startSpan, updateActiveGeneration, updateActiveSpan, updateActiveTrace };
+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 };