@langfuse/client 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/index.cjs

@@ -46,9 +46,44 @@ var import_core5 = require("@langfuse/core");
 
 // src/dataset/index.ts
 var DatasetManager = class {
+  /**
+   * Creates a new DatasetManager instance.
+   *
+   * @param params - Configuration object containing the API client
+   * @internal
+   */
   constructor(params) {
     this.apiClient = params.apiClient;
   }
+  /**
+   * Retrieves a dataset by name along with all its items.
+   *
+   * This method automatically handles pagination to fetch all dataset items
+   * and enhances each item with a `link` function for easy experiment tracking.
+   *
+   * @param name - The name of the dataset to retrieve
+   * @param options - Optional configuration for fetching
+   * @param options.fetchItemsPageSize - Number of items to fetch per page (default: 50)
+   *
+   * @returns Promise that resolves to the dataset with enhanced items
+   *
+   * @example
+   * ```typescript
+   * const dataset = await langfuse.dataset.get("my-dataset");
+   *
+   * for (const item of dataset.items) {
+   *   // Use the item data for your experiment
+   *   const result = await processItem(item.input);
+   *
+   *   // Link the result to the dataset item
+   *   await item.link(
+   *     { otelSpan: currentSpan },
+   *     "experiment-run-1",
+   *     { description: "Testing new model" }
+   *   );
+   * }
+   * ```
+   */
   async get(name, options) {
     var _a;
     const dataset = await this.apiClient.datasets.get(name);
@@ -75,6 +110,13 @@ var DatasetManager = class {
     };
     return returnDataset;
   }
+  /**
+   * Creates a link function for a specific dataset item.
+   *
+   * @param item - The dataset item to create a link function for
+   * @returns A function that can link the item to OpenTelemetry spans
+   * @internal
+   */
   createDatasetItemLinkFunction(item) {
     const linkFunction = async (obj, runName, runArgs) => {
       return await this.apiClient.datasetRunItems.create({
@@ -92,24 +134,27 @@ var DatasetManager = class {
 // src/media/index.ts
 var import_core = require("@langfuse/core");
 var MediaManager = class _MediaManager {
+  /**
+   * Creates a new MediaManager instance.
+   *
+   * @param params - Configuration object containing the API client
+   * @internal
+   */
   constructor(params) {
     this.apiClient = params.apiClient;
   }
   /**
-   * Replaces the media reference strings in an object with base64 data URIs for the media content.
+   * Replaces media reference strings in an object with base64 data URIs.
    *
-   * This method recursively traverses an object (up to a maximum depth of 10) looking for media reference strings
-   * in the format "@@@langfuseMedia:...@@@". When found, it fetches the actual media content using the provided
-   * Langfuse client and replaces the reference string with a base64 data URI.
+   * This method recursively traverses an object looking for media reference strings
+   * in the format "@@@langfuseMedia:...@@@". When found, it fetches the actual media
+   * content from Langfuse and replaces the reference string with a base64 data URI.
    *
-   * If fetching media content fails for a reference string, a warning is logged and the reference string is left unchanged.
+   * If fetching media content fails for a reference string, a warning is logged
+   * and the reference string is left unchanged.
    *
    * @param params - Configuration object
-   * @param params.obj - The object to process. Can be a primitive value, array, or nested object
-   * @param params.resolveWith - The representation of the media content to replace the media reference string with. Currently only "base64DataUri" is supported.
-   * @param params.maxDepth - Optional. Default is 10. The maximum depth to traverse the object.
-   *
-   * @returns A deep copy of the input object with all media references replaced with base64 data URIs where possible
+   * @returns A deep copy of the input object with media references resolved
    *
    * @example
    * ```typescript
@@ -120,9 +165,9 @@ var MediaManager = class _MediaManager {
    *   }
    * };
    *
-   * const result = await LangfuseMedia.resolveMediaReferences({
+   * const result = await langfuse.media.resolveReferences({
    *   obj,
-   *   langfuseClient
+   *   resolveWith: "base64DataUri"
    * });
    *
    * // Result:
@@ -331,6 +376,14 @@ import_mustache.default.escape = function(text) {
   return text;
 };
 var BasePromptClient = class {
+  /**
+   * Creates a new BasePromptClient instance.
+   *
+   * @param prompt - The base prompt data
+   * @param isFallback - Whether this is fallback content
+   * @param type - The prompt type
+   * @internal
+   */
   constructor(prompt, isFallback = false, type) {
     this.name = prompt.name;
     this.version = prompt.version;
@@ -398,14 +451,51 @@ var BasePromptClient = class {
   }
 };
 var TextPromptClient = class extends BasePromptClient {
+  /**
+   * Creates a new TextPromptClient instance.
+   *
+   * @param prompt - The text prompt data
+   * @param isFallback - Whether this is fallback content
+   */
   constructor(prompt, isFallback = false) {
     super(prompt, isFallback, "text");
     this.promptResponse = prompt;
     this.prompt = prompt.prompt;
   }
+  /**
+   * Compiles the text prompt by substituting variables.
+   *
+   * Uses Mustache templating to replace {{variable}} placeholders with provided values.
+   *
+   * @param variables - Key-value pairs for variable substitution
+   * @param _placeholders - Ignored for text prompts
+   * @returns The compiled text with variables substituted
+   *
+   * @example
+   * ```typescript
+   * const prompt = await langfuse.prompt.get("greeting", { type: "text" });
+   * const compiled = prompt.compile({ name: "Alice" });
+   * // If prompt is "Hello {{name}}!", result is "Hello Alice!"
+   * ```
+   */
   compile(variables, _placeholders) {
     return import_mustache.default.render(this.promptResponse.prompt, variables != null ? variables : {});
   }
+  /**
+   * Converts the prompt to LangChain PromptTemplate format.
+   *
+   * Transforms Mustache-style {{variable}} syntax to LangChain's {variable} format.
+   *
+   * @param _options - Ignored for text prompts
+   * @returns The prompt string compatible with LangChain PromptTemplate
+   *
+   * @example
+   * ```typescript
+   * const prompt = await langfuse.prompt.get("greeting", { type: "text" });
+   * const langchainFormat = prompt.getLangchainPrompt();
+   * // Transforms "Hello {{name}}!" to "Hello {name}!"
+   * ```
+   */
   getLangchainPrompt(_options) {
     return this._transformToLangchainVariables(this.prompt);
   }
@@ -423,6 +513,12 @@ var TextPromptClient = class extends BasePromptClient {
   }
 };
 var ChatPromptClient = class _ChatPromptClient extends BasePromptClient {
+  /**
+   * Creates a new ChatPromptClient instance.
+   *
+   * @param prompt - The chat prompt data
+   * @param isFallback - Whether this is fallback content
+   */
   constructor(prompt, isFallback = false) {
     const normalizedPrompt = _ChatPromptClient.normalizePrompt(prompt.prompt);
     const typedPrompt = {
@@ -445,6 +541,26 @@ var ChatPromptClient = class _ChatPromptClient extends BasePromptClient {
       }
     });
   }
+  /**
+   * Compiles the chat prompt by replacing placeholders and variables.
+   *
+   * First resolves placeholders with provided values, then applies variable substitution
+   * to message content using Mustache templating. Unresolved placeholders remain
+   * as placeholder objects in the output.
+   *
+   * @param variables - Key-value pairs for Mustache variable substitution in message content
+   * @param placeholders - Key-value pairs where keys are placeholder names and values are ChatMessage arrays
+   * @returns Array of ChatMessage objects and unresolved placeholder objects
+   *
+   * @example
+   * ```typescript
+   * const prompt = await langfuse.prompt.get("conversation", { type: "chat" });
+   * const compiled = prompt.compile(
+   *   { user_name: "Alice" },
+   *   { examples: [{ role: "user", content: "Hello" }, { role: "assistant", content: "Hi!" }] }
+   * );
+   * ```
+   */
   compile(variables, placeholders) {
     const messagesWithPlaceholdersReplaced = [];
     const placeholderValues = placeholders != null ? placeholders : {};
@@ -485,6 +601,25 @@ var ChatPromptClient = class _ChatPromptClient extends BasePromptClient {
       }
     });
   }
+  /**
+   * Converts the prompt to LangChain ChatPromptTemplate format.
+   *
+   * Resolves placeholders with provided values and converts unresolved ones
+   * to LangChain MessagesPlaceholder objects. Transforms variables from
+   * {{var}} to {var} format without rendering them.
+   *
+   * @param options - Configuration object
+   * @param options.placeholders - Key-value pairs for placeholder resolution
+   * @returns Array of ChatMessage objects and LangChain MessagesPlaceholder objects
+   *
+   * @example
+   * ```typescript
+   * const prompt = await langfuse.prompt.get("conversation", { type: "chat" });
+   * const langchainFormat = prompt.getLangchainPrompt({
+   *   placeholders: { examples: [{ role: "user", content: "Hello" }] }
+   * });
+   * ```
+   */
   getLangchainPrompt(options) {
     var _a;
     const messagesWithPlaceholdersReplaced = [];
@@ -545,6 +680,12 @@ var ChatPromptClient = class _ChatPromptClient extends BasePromptClient {
 
 // src/prompt/promptManager.ts
 var PromptManager = class {
+  /**
+   * Creates a new PromptManager instance.
+   *
+   * @param params - Configuration object containing the API client
+   * @internal
+   */
   constructor(params) {
     const { apiClient } = params;
     this.apiClient = apiClient;
@@ -553,6 +694,35 @@ var PromptManager = class {
   get logger() {
     return (0, import_core3.getGlobalLogger)();
   }
+  /**
+   * Creates a new prompt in Langfuse.
+   *
+   * Supports both text and chat prompts. Chat prompts can include placeholders
+   * for dynamic content insertion.
+   *
+   * @param body - The prompt data to create
+   * @returns Promise that resolves to the appropriate prompt client
+   *
+   * @example
+   * ```typescript
+   * // Create a text prompt
+   * const textPrompt = await langfuse.prompt.create({
+   *   name: "greeting",
+   *   prompt: "Hello {{name}}!",
+   *   type: "text"
+   * });
+   *
+   * // Create a chat prompt
+   * const chatPrompt = await langfuse.prompt.create({
+   *   name: "conversation",
+   *   type: "chat",
+   *   prompt: [
+   *     { role: "system", content: "You are a helpful assistant." },
+   *     { role: "user", content: "{{user_message}}" }
+   *   ]
+   * });
+   * ```
+   */
   async create(body) {
     var _a;
     const requestBody = body.type === "chat" ? {
@@ -577,6 +747,25 @@ var PromptManager = class {
     }
     return new TextPromptClient(promptResponse);
   }
+  /**
+   * Updates the labels of an existing prompt version.
+   *
+   * @param params - Update parameters
+   * @param params.name - Name of the prompt to update
+   * @param params.version - Version number of the prompt to update
+   * @param params.newLabels - New labels to apply to the prompt version
+   *
+   * @returns Promise that resolves to the updated prompt
+   *
+   * @example
+   * ```typescript
+   * const updatedPrompt = await langfuse.prompt.update({
+   *   name: "my-prompt",
+   *   version: 1,
+   *   newLabels: ["production", "v2"]
+   * });
+   * ```
+   */
   async update(params) {
     const { name, version, newLabels } = params;
     const newPrompt = await this.apiClient.promptVersion.update(name, version, {
@@ -585,6 +774,40 @@ var PromptManager = class {
     this.cache.invalidate(name);
     return newPrompt;
   }
+  /**
+   * Retrieves a prompt by name with intelligent caching.
+   *
+   * This method implements sophisticated caching behavior:
+   * - Fresh prompts are returned immediately from cache
+   * - Expired prompts are returned from cache while being refreshed in background
+   * - Cache misses trigger immediate fetch with optional fallback support
+   *
+   * @param name - Name of the prompt to retrieve
+   * @param options - Optional retrieval configuration
+   * @returns Promise that resolves to the appropriate prompt client
+   *
+   * @example
+   * ```typescript
+   * // Get latest version with caching
+   * const prompt = await langfuse.prompt.get("my-prompt");
+   *
+   * // Get specific version
+   * const v2Prompt = await langfuse.prompt.get("my-prompt", {
+   *   version: 2
+   * });
+   *
+   * // Get with label filter
+   * const prodPrompt = await langfuse.prompt.get("my-prompt", {
+   *   label: "production"
+   * });
+   *
+   * // Get with fallback
+   * const promptWithFallback = await langfuse.prompt.get("my-prompt", {
+   *   type: "text",
+   *   fallback: "Hello {{name}}!"
+   * });
+   * ```
+   */
   async get(name, options) {
     var _a;
     const cacheKey = this.cache.createKey({
@@ -701,6 +924,12 @@ var import_api = require("@opentelemetry/api");
 var MAX_QUEUE_SIZE = 1e5;
 var MAX_BATCH_SIZE = 100;
 var ScoreManager = class {
+  /**
+   * Creates a new ScoreManager instance.
+   *
+   * @param params - Configuration object containing the API client
+   * @internal
+   */
   constructor(params) {
     this.eventQueue = [];
     this.flushPromise = null;
@@ -714,6 +943,25 @@ var ScoreManager = class {
   get logger() {
     return (0, import_core4.getGlobalLogger)();
   }
+  /**
+   * Creates a new score event and adds it to the processing queue.
+   *
+   * Scores are queued and sent in batches for efficiency. The score will be
+   * automatically sent when the queue reaches the flush threshold or after
+   * the flush interval expires.
+   *
+   * @param data - The score data to create
+   *
+   * @example
+   * ```typescript
+   * langfuse.score.create({
+   *   name: "quality",
+   *   value: 0.85,
+   *   traceId: "trace-123",
+   *   comment: "High quality response"
+   * });
+   * ```
+   */
   create(data) {
     var _a, _b;
     const scoreData = {
@@ -742,6 +990,26 @@ var ScoreManager = class {
       }, this.flushIntervalSeconds * 1e3);
     }
   }
+  /**
+   * Creates a score for a specific observation using its OpenTelemetry span.
+   *
+   * This method automatically extracts the trace ID and observation ID from
+   * the provided span context.
+   *
+   * @param observation - Object containing the OpenTelemetry span
+   * @param data - Score data (traceId and observationId will be auto-populated)
+   *
+   * @example
+   * ```typescript
+   * import { startSpan } from '@langfuse/tracing';
+   *
+   * const span = startSpan({ name: "my-operation" });
+   * langfuse.score.observation(
+   *   { otelSpan: span },
+   *   { name: "accuracy", value: 0.92 }
+   * );
+   * ```
+   */
   observation(observation, data) {
     const { spanId, traceId } = observation.otelSpan.spanContext();
     this.create({
@@ -750,6 +1018,26 @@ var ScoreManager = class {
       observationId: spanId
     });
   }
+  /**
+   * Creates a score for a trace using an OpenTelemetry span.
+   *
+   * This method automatically extracts the trace ID from the provided
+   * span context and creates a trace-level score.
+   *
+   * @param observation - Object containing the OpenTelemetry span
+   * @param data - Score data (traceId will be auto-populated)
+   *
+   * @example
+   * ```typescript
+   * import { startSpan } from '@langfuse/tracing';
+   *
+   * const span = startSpan({ name: "my-operation" });
+   * langfuse.score.trace(
+   *   { otelSpan: span },
+   *   { name: "overall_quality", value: 0.88 }
+   * );
+   * ```
+   */
   trace(observation, data) {
     const { traceId } = observation.otelSpan.spanContext();
     this.create({
@@ -757,6 +1045,28 @@ var ScoreManager = class {
       traceId
     });
   }
+  /**
+   * Creates a score for the currently active observation.
+   *
+   * This method automatically detects the active OpenTelemetry span and
+   * creates an observation-level score. If no active span is found,
+   * a warning is logged and the operation is skipped.
+   *
+   * @param data - Score data (traceId and observationId will be auto-populated)
+   *
+   * @example
+   * ```typescript
+   * import { startActiveSpan } from '@langfuse/tracing';
+   *
+   * startActiveSpan({ name: "my-operation" }, (span) => {
+   *   // Inside the active span
+   *   langfuse.score.activeObservation({
+   *     name: "relevance",
+   *     value: 0.95
+   *   });
+   * });
+   * ```
+   */
   activeObservation(data) {
     const currentOtelSpan = import_api.trace.getActiveSpan();
     if (!currentOtelSpan) {
@@ -770,6 +1080,29 @@ var ScoreManager = class {
       observationId: spanId
     });
   }
+  /**
+   * Creates a score for the currently active trace.
+   *
+   * This method automatically detects the active OpenTelemetry span and
+   * creates a trace-level score. If no active span is found,
+   * a warning is logged and the operation is skipped.
+   *
+   * @param data - Score data (traceId will be auto-populated)
+   *
+   * @example
+   * ```typescript
+   * import { startActiveSpan } from '@langfuse/tracing';
+   *
+   * startActiveSpan({ name: "my-operation" }, (span) => {
+   *   // Inside the active span
+   *   langfuse.score.activeTrace({
+   *     name: "user_satisfaction",
+   *     value: 4,
+   *     comment: "User rated 4 out of 5 stars"
+   *   });
+   * });
+   * ```
+   */
   activeTrace(data) {
     const currentOtelSpan = import_api.trace.getActiveSpan();
     if (!currentOtelSpan) {
@@ -809,10 +1142,38 @@ var ScoreManager = class {
       this.flushPromise = null;
     }
   }
+  /**
+   * Flushes all pending score events to the Langfuse API.
+   *
+   * This method ensures all queued scores are sent immediately rather than
+   * waiting for the automatic flush interval or batch size threshold.
+   *
+   * @returns Promise that resolves when all pending scores have been sent
+   *
+   * @example
+   * ```typescript
+   * langfuse.score.create({ name: "quality", value: 0.8 });
+   * await langfuse.score.flush(); // Ensures the score is sent immediately
+   * ```
+   */
   async flush() {
     var _a;
     return (_a = this.flushPromise) != null ? _a : this.handleFlush();
   }
+  /**
+   * Gracefully shuts down the score manager by flushing all pending scores.
+   *
+   * This method should be called before your application exits to ensure
+   * all score data is sent to Langfuse.
+   *
+   * @returns Promise that resolves when shutdown is complete
+   *
+   * @example
+   * ```typescript
+   * // Before application exit
+   * await langfuse.score.shutdown();
+   * ```
+   */
   async shutdown() {
     await this.flush();
   }
@@ -820,6 +1181,26 @@ var ScoreManager = class {
 
 // src/LangfuseClient.ts
 var LangfuseClient = class {
+  /**
+   * Creates a new LangfuseClient instance.
+   *
+   * @param params - Configuration parameters. If not provided, will use environment variables.
+   *
+   * @throws Will log warnings if required credentials are not provided
+   *
+   * @example
+   * ```typescript
+   * // With explicit configuration
+   * const client = new LangfuseClient({
+   *   publicKey: "pk_...",
+   *   secretKey: "sk_...",
+   *   baseUrl: "https://your-instance.langfuse.com"
+   * });
+   *
+   * // Using environment variables
+   * const client = new LangfuseClient();
+   * ```
+   */
   constructor(params) {
     this.projectId = null;
     var _a, _b, _c, _d, _e, _f, _g;
@@ -878,12 +1259,53 @@ var LangfuseClient = class {
     this.fetchMedia = this.api.media.get;
     this.resolveMediaReferences = this.media.resolveReferences;
   }
+  /**
+   * Flushes any pending score events to the Langfuse API.
+   *
+   * This method ensures all queued scores are sent immediately rather than
+   * waiting for the automatic flush interval or batch size threshold.
+   *
+   * @returns Promise that resolves when all pending scores have been sent
+   *
+   * @example
+   * ```typescript
+   * langfuse.score.create({ name: "quality", value: 0.8 });
+   * await langfuse.flush(); // Ensures the score is sent immediately
+   * ```
+   */
   async flush() {
     return this.score.flush();
   }
+  /**
+   * Gracefully shuts down the client by flushing all pending data.
+   *
+   * This method should be called before your application exits to ensure
+   * all data is sent to Langfuse.
+   *
+   * @returns Promise that resolves when shutdown is complete
+   *
+   * @example
+   * ```typescript
+   * // Before application exit
+   * await langfuse.shutdown();
+   * ```
+   */
   async shutdown() {
     return this.score.shutdown();
   }
+  /**
+   * Generates a URL to view a specific trace in the Langfuse UI.
+   *
+   * @param traceId - The ID of the trace to generate a URL for
+   * @returns Promise that resolves to the trace URL
+   *
+   * @example
+   * ```typescript
+   * const traceId = "trace-123";
+   * const url = await langfuse.getTraceUrl(traceId);
+   * console.log(`View trace at: ${url}`);
+   * ```
+   */
   async getTraceUrl(traceId) {
     let projectId = this.projectId;
     if (!projectId) {