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

package/dist/index.cjs

@@ -20,13 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  LangfuseAgent: () => LangfuseAgent,
+  LangfuseChain: () => LangfuseChain,
+  LangfuseEmbedding: () => LangfuseEmbedding,
+  LangfuseEvaluator: () => LangfuseEvaluator,
   LangfuseEvent: () => LangfuseEvent,
   LangfuseGeneration: () => LangfuseGeneration,
+  LangfuseGuardrail: () => LangfuseGuardrail,
   LangfuseOtelSpanAttributes: () => import_core4.LangfuseOtelSpanAttributes,
+  LangfuseRetriever: () => LangfuseRetriever,
   LangfuseSpan: () => LangfuseSpan,
-  createEvent: () => createEvent,
-  createGenerationAttributes: () => createGenerationAttributes,
-  createSpanAttributes: () => createSpanAttributes,
+  LangfuseTool: () => LangfuseTool,
+  createObservationAttributes: () => createObservationAttributes,
   createTraceAttributes: () => createTraceAttributes,
   createTraceId: () => createTraceId,
   getActiveSpanId: () => getActiveSpanId,
@@ -35,12 +40,9 @@ __export(index_exports, {
   getLangfuseTracerProvider: () => getLangfuseTracerProvider,
   observe: () => observe,
   setLangfuseTracerProvider: () => setLangfuseTracerProvider,
-  startActiveGeneration: () => startActiveGeneration,
-  startActiveSpan: () => startActiveSpan,
-  startGeneration: () => startGeneration,
-  startSpan: () => startSpan,
-  updateActiveGeneration: () => updateActiveGeneration,
-  updateActiveSpan: () => updateActiveSpan,
+  startActiveObservation: () => startActiveObservation,
+  startObservation: () => startObservation,
+  updateActiveObservation: () => updateActiveObservation,
   updateActiveTrace: () => updateActiveTrace
 });
 module.exports = __toCommonJS(index_exports);
@@ -79,43 +81,23 @@ function createTraceAttributes({
     Object.entries(attributes).filter(([_, v]) => v != null)
   );
 }
-function createSpanAttributes({
-  metadata,
-  input,
-  output,
-  level,
-  statusMessage,
-  version
-}) {
-  const attributes = {
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: "span",
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: level,
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: statusMessage,
-    [import_core.LangfuseOtelSpanAttributes.VERSION]: version,
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_INPUT]: _serialize(input),
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]: _serialize(output),
-    ..._flattenAndSerializeMetadata(metadata, "observation")
-  };
-  return Object.fromEntries(
-    Object.entries(attributes).filter(([_, v]) => v != null)
-  );
-}
-function createGenerationAttributes({
-  completionStartTime,
-  metadata,
-  level,
-  statusMessage,
-  version,
-  model,
-  modelParameters,
-  input,
-  output,
-  usageDetails,
-  costDetails,
-  prompt
-}) {
-  const attributes = {
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: "generation",
+function createObservationAttributes(type, attributes) {
+  const {
+    metadata,
+    input,
+    output,
+    level,
+    statusMessage,
+    version,
+    completionStartTime,
+    model,
+    modelParameters,
+    usageDetails,
+    costDetails,
+    prompt
+  } = attributes;
+  let otelAttributes = {
+    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: type,
     [import_core.LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: level,
     [import_core.LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: statusMessage,
     [import_core.LangfuseOtelSpanAttributes.VERSION]: version,
@@ -133,28 +115,7 @@ function createGenerationAttributes({
     ..._flattenAndSerializeMetadata(metadata, "observation")
   };
   return Object.fromEntries(
-    Object.entries(attributes).filter(([_, v]) => v != null)
-  );
-}
-function createEventAttributes({
-  metadata,
-  input,
-  output,
-  level,
-  statusMessage,
-  version
-}) {
-  const attributes = {
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: "event",
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: level,
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: statusMessage,
-    [import_core.LangfuseOtelSpanAttributes.VERSION]: version,
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_INPUT]: _serialize(input),
-    [import_core.LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]: _serialize(output),
-    ..._flattenAndSerializeMetadata(metadata, "observation")
-  };
-  return Object.fromEntries(
-    Object.entries(attributes).filter(([_, v]) => v != null)
+    Object.entries(otelAttributes).filter(([_, v]) => v != null)
   );
 }
 function _serialize(obj) {
@@ -241,11 +202,17 @@ function getLangfuseTracer() {
 }
 
 // src/spanWrapper.ts
-var LangfuseSpanWrapper = class {
+var LangfuseBaseObservation = class {
   constructor(params) {
     this.otelSpan = params.otelSpan;
     this.id = params.otelSpan.spanContext().spanId;
     this.traceId = params.otelSpan.spanContext().traceId;
+    this.type = params.type;
+    if (params.attributes) {
+      this.otelSpan.setAttributes(
+        createObservationAttributes(params.type, params.attributes)
+      );
+    }
   }
   /** Gets the Langfuse OpenTelemetry tracer instance */
   get tracer() {
@@ -259,6 +226,11 @@ var LangfuseSpanWrapper = class {
   end(endTime) {
     this.otelSpan.end(endTime);
   }
+  updateOtelSpanAttributes(attributes) {
+    this.otelSpan.setAttributes(
+      createObservationAttributes(this.type, attributes)
+    );
+  }
   /**
    * Updates the parent trace with new attributes.
    *
@@ -272,13 +244,18 @@ var LangfuseSpanWrapper = class {
     this.otelSpan.setAttributes(createTraceAttributes(attributes));
     return this;
   }
+  startObservation(name, attributes, options) {
+    const { asType = "span" } = options || {};
+    return startObservation(name, attributes, {
+      asType,
+      // typecast necessary as ts cannot narrow the type correctly
+      parentSpanContext: this.otelSpan.spanContext()
+    });
+  }
 };
-var LangfuseSpan = class extends LangfuseSpanWrapper {
+var LangfuseSpan = class extends LangfuseBaseObservation {
   constructor(params) {
-    super(params);
-    if (params.attributes) {
-      this.otelSpan.setAttributes(createSpanAttributes(params.attributes));
-    }
+    super({ ...params, type: "span" });
   }
   /**
    * Updates this span with new attributes.
@@ -296,134 +273,178 @@ var LangfuseSpan = class extends LangfuseSpanWrapper {
    * ```
    */
   update(attributes) {
-    this.otelSpan.setAttributes(createSpanAttributes(attributes));
+    super.updateOtelSpanAttributes(attributes);
     return this;
   }
+};
+var LangfuseAgent = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "agent" });
+  }
   /**
-   * 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, attributes) {
-    return startSpan(name, attributes, {
-      parentSpanContext: this.otelSpan.spanContext()
-    });
+  update(attributes) {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+};
+var LangfuseTool = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "tool" });
   }
   /**
-   * 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, attributes) {
-    return startGeneration(name, attributes, {
-      parentSpanContext: this.otelSpan.spanContext()
-    });
+  update(attributes) {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+};
+var LangfuseChain = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "chain" });
   }
   /**
-   * 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, attributes) {
-    return createEvent(name, attributes, {
-      parentSpanContext: this.otelSpan.spanContext()
-    });
+  update(attributes) {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
   }
 };
-var LangfuseGeneration = class extends LangfuseSpanWrapper {
+var LangfuseRetriever = class extends LangfuseBaseObservation {
   constructor(params) {
-    super(params);
-    if (params.attributes) {
-      this.otelSpan.setAttributes(
-        createGenerationAttributes(params.attributes)
-      );
-    }
+    super({ ...params, type: "retriever" });
   }
   /**
-   * Updates this generation with new attributes.
-   *
-   * @param attributes - Generation attributes to set
-   * @returns This generation for method chaining
+   * Updates this retriever observation with new attributes.
    *
-   * @example
-   * ```typescript
-   * generation.update({
-   *   output: { role: 'assistant', content: 'Hello there!' },
-   *   usageDetails: {
-   *     promptTokens: 10,
-   *     completionTokens: 15,
-   *     totalTokens: 25
-   *   },
-   *   costDetails: { totalCost: 0.001 }
-   * });
-   * ```
+   * @param attributes - Retriever attributes to set
+   * @returns This retriever for method chaining
    */
   update(attributes) {
-    this.otelSpan.setAttributes(createGenerationAttributes(attributes));
+    super.updateOtelSpanAttributes(attributes);
     return this;
   }
+};
+var LangfuseEvaluator = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "evaluator" });
+  }
   /**
-   * Creates a new event within this generation.
+   * Updates this evaluator observation with new attributes.
    *
-   * Events are point-in-time occurrences and are automatically ended.
+   * @param attributes - Evaluator attributes to set
+   * @returns This evaluator for method chaining
+   */
+  update(attributes) {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+};
+var LangfuseGuardrail = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "guardrail" });
+  }
+  /**
+   * Updates this guardrail observation with new attributes.
    *
-   * @param name - Name of the event
-   * @param attributes - Optional event attributes
-   * @returns The created event (already ended)
+   * @param attributes - Guardrail attributes to set
+   * @returns This guardrail for method chaining
+   */
+  update(attributes) {
+    super.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+};
+var LangfuseGeneration = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "generation" });
+  }
+  update(attributes) {
+    this.updateOtelSpanAttributes(attributes);
+    return this;
+  }
+};
+var LangfuseEmbedding = class extends LangfuseBaseObservation {
+  constructor(params) {
+    super({ ...params, type: "embedding" });
+  }
+  /**
+   * Updates this embedding observation with new attributes.
    *
-   * @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, attributes) {
-    return createEvent(name, attributes, {
-      parentSpanContext: this.otelSpan.spanContext()
-    });
+  update(attributes) {
+    this.updateOtelSpanAttributes(attributes);
+    return this;
   }
 };
-var LangfuseEvent = class extends LangfuseSpanWrapper {
+var LangfuseEvent = class extends LangfuseBaseObservation {
   constructor(params) {
-    super(params);
-    if (params.attributes) {
-      this.otelSpan.setAttributes(createEventAttributes(params.attributes));
-    }
+    super({ ...params, type: "event" });
     this.otelSpan.end(params.timestamp);
   }
 };
@@ -461,73 +482,145 @@ function wrapPromise(promise, span, endOnExit) {
     }
   );
 }
-function startSpan(name, attributes, options) {
-  const otelSpan = createOtelSpan({
-    name,
-    ...options
-  });
-  return new LangfuseSpan({ otelSpan, attributes });
-}
-function startGeneration(name, attributes, options) {
-  const otelSpan = createOtelSpan({
-    name,
-    ...options
-  });
-  return new LangfuseGeneration({ otelSpan, attributes });
-}
-function createEvent(name, attributes, options) {
+function startObservation(name, attributes, options) {
   var _a;
-  const timestamp = (_a = options == null ? void 0 : options.startTime) != null ? _a : /* @__PURE__ */ new Date();
+  const { asType = "span", ...observationOptions } = options || {};
   const otelSpan = createOtelSpan({
     name,
-    ...options,
-    startTime: timestamp
+    ...observationOptions
   });
-  return new LangfuseEvent({ otelSpan, attributes, timestamp });
+  switch (asType) {
+    case "generation":
+      return new LangfuseGeneration({
+        otelSpan,
+        attributes
+      });
+    case "embedding":
+      return new LangfuseEmbedding({
+        otelSpan,
+        attributes
+      });
+    case "agent":
+      return new LangfuseAgent({
+        otelSpan,
+        attributes
+      });
+    case "tool":
+      return new LangfuseTool({
+        otelSpan,
+        attributes
+      });
+    case "chain":
+      return new LangfuseChain({
+        otelSpan,
+        attributes
+      });
+    case "retriever":
+      return new LangfuseRetriever({
+        otelSpan,
+        attributes
+      });
+    case "evaluator":
+      return new LangfuseEvaluator({
+        otelSpan,
+        attributes
+      });
+    case "guardrail":
+      return new LangfuseGuardrail({
+        otelSpan,
+        attributes
+      });
+    case "event": {
+      const timestamp = (_a = observationOptions == null ? void 0 : observationOptions.startTime) != null ? _a : /* @__PURE__ */ new Date();
+      return new LangfuseEvent({
+        otelSpan,
+        attributes,
+        timestamp
+      });
+    }
+    case "span":
+    default:
+      return new LangfuseSpan({
+        otelSpan,
+        attributes
+      });
+  }
 }
-function startActiveSpan(name, fn, options) {
+function startActiveObservation(name, fn, options) {
   var _a;
+  const { asType = "span", ...observationOptions } = options || {};
   return getLangfuseTracer().startActiveSpan(
     name,
-    { startTime: options == null ? void 0 : options.startTime },
-    (_a = createParentContext(options == null ? void 0 : options.parentSpanContext)) != null ? _a : import_api2.context.active(),
+    { startTime: observationOptions == null ? void 0 : observationOptions.startTime },
+    (_a = createParentContext(observationOptions == null ? void 0 : observationOptions.parentSpanContext)) != null ? _a : import_api2.context.active(),
     (span) => {
+      var _a2;
       try {
-        const result = fn(new LangfuseSpan({ otelSpan: span }));
-        if (result instanceof Promise) {
-          return wrapPromise(result, span, options == null ? void 0 : options.endOnExit);
-        } else {
-          if ((options == null ? void 0 : options.endOnExit) !== false) {
-            span.end();
+        let observation;
+        switch (asType) {
+          case "generation":
+            observation = new LangfuseGeneration({
+              otelSpan: span
+            });
+            break;
+          case "embedding":
+            observation = new LangfuseEmbedding({
+              otelSpan: span
+            });
+            break;
+          case "agent":
+            observation = new LangfuseAgent({
+              otelSpan: span
+            });
+            break;
+          case "tool":
+            observation = new LangfuseTool({
+              otelSpan: span
+            });
+            break;
+          case "chain":
+            observation = new LangfuseChain({
+              otelSpan: span
+            });
+            break;
+          case "retriever":
+            observation = new LangfuseRetriever({
+              otelSpan: span
+            });
+            break;
+          case "evaluator":
+            observation = new LangfuseEvaluator({
+              otelSpan: span
+            });
+            break;
+          case "guardrail":
+            observation = new LangfuseGuardrail({
+              otelSpan: span
+            });
+            break;
+          case "event": {
+            const timestamp = (_a2 = observationOptions == null ? void 0 : observationOptions.startTime) != null ? _a2 : /* @__PURE__ */ new Date();
+            observation = new LangfuseEvent({
+              otelSpan: span,
+              timestamp
+            });
+            break;
           }
-          return result;
-        }
-      } catch (err) {
-        span.setStatus({
-          code: import_api2.SpanStatusCode.ERROR,
-          message: err instanceof Error ? err.message : "Unknown error"
-        });
-        if ((options == null ? void 0 : options.endOnExit) !== false) {
-          span.end();
+          case "span":
+          default:
+            observation = new LangfuseSpan({
+              otelSpan: span
+            });
         }
-        throw err;
-      }
-    }
-  );
-}
-function startActiveGeneration(name, fn, options) {
-  var _a;
-  return getLangfuseTracer().startActiveSpan(
-    name,
-    { startTime: options == null ? void 0 : options.startTime },
-    (_a = createParentContext(options == null ? void 0 : options.parentSpanContext)) != null ? _a : import_api2.context.active(),
-    (span) => {
-      try {
-        const result = fn(new LangfuseGeneration({ otelSpan: span }));
+        const result = fn(observation);
         if (result instanceof Promise) {
-          return wrapPromise(result, span, options == null ? void 0 : options.endOnExit);
+          return wrapPromise(
+            result,
+            span,
+            observationOptions == null ? void 0 : observationOptions.endOnExit
+          );
         } else {
-          if ((options == null ? void 0 : options.endOnExit) !== false) {
+          if ((observationOptions == null ? void 0 : observationOptions.endOnExit) !== false) {
             span.end();
           }
           return result;
@@ -537,7 +630,7 @@ function startActiveGeneration(name, fn, options) {
           code: import_api2.SpanStatusCode.ERROR,
           message: err instanceof Error ? err.message : "Unknown error"
         });
-        if ((options == null ? void 0 : options.endOnExit) !== false) {
+        if ((observationOptions == null ? void 0 : observationOptions.endOnExit) !== false) {
           span.end();
         }
         throw err;
@@ -555,7 +648,7 @@ function updateActiveTrace(attributes) {
   }
   span.setAttributes(createTraceAttributes(attributes));
 }
-function updateActiveSpan(attributes) {
+function updateActiveObservation(currentType, attributes) {
   const span = import_api2.trace.getActiveSpan();
   if (!span) {
     (0, import_core3.getGlobalLogger)().warn(
@@ -563,17 +656,7 @@ function updateActiveSpan(attributes) {
     );
     return;
   }
-  span.setAttributes(createSpanAttributes(attributes));
-}
-function updateActiveGeneration(attributes) {
-  const span = import_api2.trace.getActiveSpan();
-  if (!span) {
-    (0, import_core3.getGlobalLogger)().warn(
-      "No active OTEL span in context. Skipping generation update."
-    );
-    return;
-  }
-  span.setAttributes(createGenerationAttributes(attributes));
+  span.setAttributes(createObservationAttributes(currentType, attributes));
 }
 function observe(fn, options = {}) {
   const {
@@ -585,11 +668,15 @@ function observe(fn, options = {}) {
   } = options;
   const wrappedFunction = function(...args) {
     const inputData = captureInput ? _captureArguments(args) : void 0;
-    const observation = asType === "generation" ? startGeneration(name, inputData ? { input: inputData } : {}, {
-      parentSpanContext
-    }) : startSpan(name, inputData ? { input: inputData } : {}, {
-      parentSpanContext
-    });
+    const observation = startObservation(
+      name,
+      inputData ? { input: inputData } : {},
+      {
+        asType,
+        // typecast necessary as ts cannot narrow down type
+        parentSpanContext
+      }
+    );
     const activeContext = import_api2.trace.setSpan(import_api2.context.active(), observation.otelSpan);
     try {
       const result = import_api2.context.with(activeContext, () => fn.apply(this, args));
@@ -680,13 +767,18 @@ function getActiveSpanId() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  LangfuseAgent,
+  LangfuseChain,
+  LangfuseEmbedding,
+  LangfuseEvaluator,
   LangfuseEvent,
   LangfuseGeneration,
+  LangfuseGuardrail,
   LangfuseOtelSpanAttributes,
+  LangfuseRetriever,
   LangfuseSpan,
-  createEvent,
-  createGenerationAttributes,
-  createSpanAttributes,
+  LangfuseTool,
+  createObservationAttributes,
   createTraceAttributes,
   createTraceId,
   getActiveSpanId,
@@ -695,12 +787,9 @@ function getActiveSpanId() {
   getLangfuseTracerProvider,
   observe,
   setLangfuseTracerProvider,
-  startActiveGeneration,
-  startActiveSpan,
-  startGeneration,
-  startSpan,
-  updateActiveGeneration,
-  updateActiveSpan,
+  startActiveObservation,
+  startObservation,
+  updateActiveObservation,
   updateActiveTrace
 });
 //# sourceMappingURL=index.cjs.map