### Codex Cloud Setup Script

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Execute the setup script for Codex cloud environment.

```bash
bash scripts/codex/setup.sh
```

--------------------------------

### Manage Prompts

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Examples for getting, compiling, creating, updating, and deleting prompts. Supports fetching specific versions or labels.

```typescript
// Get prompt
const prompt = await langfuse.prompt.get("prompt-name");
const compiled = prompt.compile({ variable: "value" });

// Get specific version/label
const v2 = await langfuse.prompt.get("prompt-name", { version: 2 });
const prod = await langfuse.prompt.get("prompt-name", { label: "production" });

// Create prompt
const newPrompt = await langfuse.prompt.create({
  name: "greeting",
  type: "text",
  prompt: "Hello {{name}}!"
});

// Update labels
await langfuse.prompt.update({
  name: "greeting",
  version: 1,
  newLabels: ["production"]
});

// Delete prompt
await langfuse.prompt.delete("greeting");
```

--------------------------------

### Install Langfuse Client with Tracing

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Install the core Langfuse client along with the tracing package for observability.

```bash
npm install @langfuse/client @langfuse/tracing
```

--------------------------------

### Install Langfuse Browser SDK

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Install the Langfuse SDK specifically for browser environments.

```bash
npm install @langfuse/browser
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/langfuse/langfuse-js/blob/main/README.md

Commands to install project dependencies, build all packages, run tests, and execute the full CI suite using pnpm.

```bash
pnpm install

pnpm build

pnpm test

pnpm ci
```

--------------------------------

### Install Langfuse Client with LangChain Integration

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Install the core Langfuse client and the package for LangChain integration.

```bash
npm install @langfuse/client @langfuse/langchain
```

--------------------------------

### Install Dependencies

Source: https://github.com/langfuse/langfuse-js/blob/main/CONTRIBUTING.md

Installs all project dependencies using pnpm. Ensure Node.js 20+ and pnpm 10.33.0 are installed.

```bash
pnpm install
```

--------------------------------

### Install Langfuse Client with OpenAI Integration

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Install the core Langfuse client and the package for OpenAI integration.

```bash
npm install @langfuse/client @langfuse/openai
```

--------------------------------

### Install Langfuse Core Client

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Install the core Langfuse client package using npm.

```bash
npm install @langfuse/client
```

--------------------------------

### Example: Get Dataset with Custom Page Size

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/configuration.md

Demonstrates fetching a dataset with a custom page size, overriding the default.

```typescript
// Get latest dataset with custom page size
const dataset = await langfuse.dataset.get("my-dataset", {
  fetchItemsPageSize: 100
});
```

--------------------------------

### Example: Get Historical Dataset Version

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/configuration.md

Shows how to retrieve a dataset as it existed at a specific point in time using a version timestamp.

```typescript
// Get dataset as it was at specific time
const historicalDataset = await langfuse.dataset.get("my-dataset", {
  version: "2026-01-21T14:35:42Z"
});
```

--------------------------------

### Example Usage of LangfuseSpan

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Demonstrates starting an observation, updating it with input and output, and then ending the span.

```typescript
const span = startObservation('my-task', {
  input: { data: 'test' }
});
span.update({ output: { result: 'success' } });
span.end();
```

--------------------------------

### Execute a Simple Experiment

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-experiment-manager.md

Demonstrates a basic experiment setup with data, a task function, and item-level evaluators. Ensure LangfuseClient is initialized.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

const result = await langfuse.experiment.run({
  name: "Translation Quality Test",
  data: [
    { input: "Hello world", expectedOutput: "Hola mundo" },
    { input: "Good morning", expectedOutput: "Buenos días" }
  ],
  task: async ({ input }) => {
    return await translateText(input, 'es');
  },
  evaluators: [
    async ({ output, expectedOutput }) => ({
      name: "bleu_score",
      value: calculateBleuScore(output, expectedOutput)
    })
  ]
});

console.log(await result.format());
```

--------------------------------

### Run an Experiment with Configuration

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/configuration.md

Example of executing an experiment with specified parameters, including custom metadata, concurrency limits, and evaluators.

```typescript
const result = await langfuse.experiment.run({
  name: "Model Evaluation",
  description: "Testing new model version",
  metadata: { modelVersion: "v1.5" },
  data: testData,
  task: async ({ input }) => await model.predict(input),
  maxConcurrency: 10,  // Process 10 items at a time
  evaluators: [accuracyEvaluator],
  runEvaluators: [averageEvaluator]
});
```

--------------------------------

### LangfuseTool Example

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Demonstrates creating, updating, and ending a LangfuseTool observation. Use this to track individual tool or API calls.

```typescript
const tool = startObservation('weather-api', {
  input: { location: 'San Francisco' }
}, { asType: 'tool' });

tool.update({
  output: { temperature: 72, condition: 'Sunny' }
});
tool.end();
```

--------------------------------

### StartObservationOptions Interface

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/types.md

Options for initiating an observation, including optional start time and parent span context.

```typescript
interface StartObservationOptions {
  startTime?: Date;
  parentSpanContext?: SpanContext;
}
```

--------------------------------

### Create Chat Prompt with Placeholders

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

This example demonstrates creating a chat prompt that includes a placeholder for dynamic content insertion, alongside user-defined placeholders.

```typescript
const withPlaceholders = await langfuse.prompt.create({
  name: "rag-prompt",
  type: "chat",
  prompt: [
    { role: "system", content: "Answer based on context." },
    { type: "placeholder", name: "examples" },
    { role: "user", content: "{{question}}" }
  ]
});
```

--------------------------------

### Media Reference String Examples

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-media-manager.md

Examples of the media reference string format used by Langfuse, including different content types and sources.

```text
@@@langfuseMedia:type=image/jpeg|id=550e8400-e29b-41d4-a716-446655440000|source=bytes@@@
@@@langfuseMedia:type=application/pdf|id=abc123|source=bytes@@@
@@@langfuseMedia:type=text/plain|id=doc-456|source=base64DataUri@@@
```

--------------------------------

### Create and Manage Scores

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Examples for creating scores directly, scoring observations, and scoring traces. Includes flushing scores immediately.

```typescript
// Direct score creation
langfuse.score.create({
  name: "quality",
  value: 0.85,
  traceId: "trace-123"
});

// Score for observation
langfuse.score.observation(
  { otelSpan: span },
  { name: "accuracy", value: 0.9 }
);

// Score for trace
langfuse.score.trace(
  { otelSpan: span },
  { name: "overall_quality", value: 0.88 }
);

// Flush scores immediately
await langfuse.score.flush();
```

--------------------------------

### StartObservationOpts Interface

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/types.md

Extends StartObservationOptions with an optional `asType` field to specify the observation type when starting.

```typescript
interface StartObservationOpts extends StartObservationOptions {
  asType?: LangfuseObservationType;
}
```

--------------------------------

### LangfuseChain Example

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Demonstrates creating, updating, and ending a LangfuseChain observation. Use this for multi-step processes like RAG pipelines.

```typescript
const chain = startObservation('rag-pipeline', {
  input: { question: 'What is AI?' }
}, { asType: 'chain' });

chain.update({
  output: { answer: 'AI is...', sources: 5 }
});
chain.end();
```

--------------------------------

### Start Active Observation (General)

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Starts an observation, executes a function within its context, and automatically manages its lifecycle. Useful for general operations where automatic cleanup is desired.

```typescript
function startActiveObservation<F extends (...args: any[]) => unknown>(
  name: string,
  fn: F,
  options?: StartActiveObservationOpts
): ReturnType<F>

// Span for general operations (default)
const result = startActiveObservation('user-checkout', (span) => {
  span.update({ input: { userId: '123' } });
  
  // Child observations created here inherit this span's context
  const validation = processPayment(paymentData);
  
  span.update({ output: { orderId: 'ord_456', success: true } });
  return validation;
});
```

--------------------------------

### StartActiveObservationContext Interface

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/types.md

Options for starting an active observation, inheriting from StartObservationOptions and adding `endOnExit`.

```typescript
interface StartActiveObservationContext extends StartObservationOptions {
  endOnExit?: boolean;
}
```

--------------------------------

### Import Langfuse Tracing Utilities

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Import essential functions for starting, updating, and observing traces and spans.

```typescript
// Tracing
import {
  startObservation,
  startActiveObservation,
  updateActiveObservation,
  observe,
  createTraceId,
  getActiveTraceId,
  getActiveSpanId
} from "@langfuse/tracing";
```

--------------------------------

### Start Active Observation (Async Generation)

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Starts an observation for asynchronous operations like LLM calls, with automatic lifecycle management and error handling. Use the 'generation' type for LLM-specific data.

```typescript
// Async generation with error handling
const response = await startActiveObservation(
  'openai-completion',
  async (generation) => {
    generation.update({
      input: { messages: [{ role: 'user', content: 'Hello' }] },
      model: 'gpt-4-turbo'
    });
    
    try {
      const result = await openai.chat.completions.create({...});
      generation.update({ output: result.choices[0].message });
      return result;
    } catch (error) {
      generation.update({ level: 'ERROR', statusMessage: error.message });
      throw error;
    }
  },
  { asType: 'generation' }
);
```

--------------------------------

### Import Tracing Functions

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Import the necessary functions from the @langfuse/tracing package to start instrumenting your code.

```APIDOC
## Import Tracing Functions

### Description
Import the necessary functions from the @langfuse/tracing package to start instrumenting your code.

### Code
```typescript
import {
  startObservation,
  startActiveObservation,
  updateActiveObservation,
  observe,
  createTraceId,
  getActiveTraceId,
  getActiveSpanId
} from "@langfuse/tracing";
```
```

--------------------------------

### startObservation()

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Creates and starts a new Langfuse observation. It supports various observation types like spans, generations, and tools, with automatic type inference and detailed parameter options.

```APIDOC
## startObservation()

### Description
Creates and starts a new Langfuse observation with automatic TypeScript type inference. This is the primary method for creating observations in Langfuse. It supports multiple observation types with full TypeScript type safety - the return type is automatically inferred based on the `asType` parameter.

### Function Signature
```typescript
function startObservation(
  name: string,
  attributes?: LangfuseSpanAttributes | LangfuseGenerationAttributes | ..., 
  options?: StartObservationOpts
): LangfuseObservation
```

### Parameters
#### Parameters
- **name** (string) - Required - Descriptive name for the observation (e.g., 'openai-gpt-4', 'vector-search')
- **attributes** (LangfuseSpanAttributes | ... ) - Optional - Type-specific attributes (input, output, metadata, etc.)
- **options** (StartObservationOpts) - Optional - Configuration options including observation type and timing
  - **options.asType** (LangfuseObservationType) - Optional - Type of observation to create. Defaults to 'span'
  - **options.startTime** (Date) - Optional - Custom start time for the observation
  - **options.parentSpanContext** (SpanContext) - Optional - Parent span context to attach this observation to

### Returns
Strongly-typed observation object based on `asType` parameter

### Supported Observation Types
- **span** (default): General-purpose operations, functions, or workflows
- **generation**: LLM calls, text generation, or AI model interactions
- **embedding**: Text embedding generation or vector operations
- **agent**: AI agent workflows with tool usage and decision making
- **tool**: Individual tool calls, API requests, or function invocations
- **chain**: Multi-step processes like RAG pipelines or sequential operations
- **retriever**: Document retrieval, vector search, or knowledge base queries
- **evaluator**: Quality assessment, scoring, or evaluation operations
- **guardrail**: Safety checks, content filtering, or validation operations
- **event**: Point-in-time occurrences or log entries (automatically ended)

### Example
```typescript
import { startObservation } from '@langfuse/tracing';

// Span for general operations (default)
const span = startObservation('user-workflow', {
  input: { userId: '123', action: 'checkout' },
  metadata: { version: '2.1.0' }
});
span.update({ output: { success: true, orderId: '456' } });
span.end();

// Generation for LLM interactions
const generation = startObservation('openai-gpt-4', {
  input: [{ role: 'user', content: 'Explain quantum computing' }],
  model: 'gpt-4-turbo',
  modelParameters: { temperature: 0.7, maxTokens: 500 }
}, { asType: 'generation' });
generation.update({
  output: { role: 'assistant', content: 'Quantum computing...' }
});
generation.end();

// Tool for API calls
const tool = startObservation('weather-api', {
  input: { location: 'San Francisco' }
}, { asType: 'tool' });
tool.end();
```
```

--------------------------------

### get()

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves a prompt by name with intelligent caching. Implements sophisticated caching behavior: Fresh prompts are returned immediately from cache, expired prompts are returned from cache while being refreshed in background, and cache misses trigger immediate fetch with optional fallback support.

```APIDOC
## get()

### Description
Retrieves a prompt by name with intelligent caching. Implements sophisticated caching behavior: Fresh prompts are returned immediately from cache, expired prompts are returned from cache while being refreshed in background, and cache misses trigger immediate fetch with optional fallback support.

### Method
`GET`

### Endpoint
`/prompts/{name}`

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of the prompt to retrieve

#### Query Parameters
- **version** (number) - Optional - Specific version to retrieve (defaults to latest)
- **label** (string) - Optional - Label to filter by
- **cacheTtlSeconds** (number) - Optional - Cache TTL in seconds (0 to disable caching)
- **fallback** (string | ChatMessage[]) - Optional - Fallback content if prompt fetch fails
- **maxRetries** (number) - Optional - Maximum retry attempts for failed requests
- **type** (string) - Optional - Prompt type (`text` or `chat`, auto-detected if not specified)
- **fetchTimeoutMs** (number) - Optional - Request timeout in milliseconds

### Response
#### Success Response (200)
- **TextPromptClient** or **ChatPromptClient** - Depending on prompt type

#### Response Example
```json
{
  "id": "prompt-id-123",
  "name": "greeting",
  "type": "text",
  "prompt": "Hello {{name}}!",
  "version": 1,
  "createdAt": "2023-01-01T12:00:00Z",
  "updatedAt": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### startActiveObservation

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Starts an active observation and executes a function within its context with automatic lifecycle management. It creates an observation, sets it as the active span in the OpenTelemetry context, executes the provided function, and handles cleanup automatically.

```APIDOC
## startActiveObservation()

### Description
Starts an active observation and executes a function within its context with automatic lifecycle management. This function creates an observation, sets it as the active span in the OpenTelemetry context, executes your function with the observation instance, and automatically handles cleanup.

### Parameters
#### Path Parameters
- **name** (string) - Required - Descriptive name for the observation
- **fn** (Function) - Required - Function to execute within the observation context (receives typed observation instance)
- **options** (StartActiveObservationOpts) - Optional - Configuration options including observation type and lifecycle settings
  - **options.asType** (LangfuseObservationType) - Optional - Type of observation to create. Defaults to 'span'
  - **options.startTime** (Date) - Optional - Custom start time for the observation
  - **options.parentSpanContext** (SpanContext) - Optional - Parent span context to attach this observation to
  - **options.endOnExit** (boolean) - Optional - Whether to automatically end the observation when exiting the context. Default is true

### Returns
The exact return value of the executed function (preserves type and async behavior)

### Example
```typescript
// Span for general operations (default)
const result = startActiveObservation('user-checkout', (span) => {
  span.update({ input: { userId: '123' } });
  
  // Child observations created here inherit this span's context
  const validation = processPayment(paymentData);
  
  span.update({ output: { orderId: 'ord_456', success: true } });
  return validation;
});

// Async generation with error handling
const response = await startActiveObservation(
  'openai-completion',
  async (generation) => {
    generation.update({
      input: { messages: [{ role: 'user', content: 'Hello' }] },
      model: 'gpt-4-turbo'
    });
    
    try {
      const result = await openai.chat.completions.create({...});
      generation.update({ output: result.choices[0].message });
      return result;
    } catch (error) {
      generation.update({ level: 'ERROR', statusMessage: error.message });
      throw error;
    }
  },
  { asType: 'generation' }
);

// Nested observations with parent context
const parentSpan = startObservation('ai-pipeline');
const childRetriever = startActiveObservation(
  'doc-search',
  (retriever) => {
    retriever.update({ input: { query: 'AI safety' } });
    return search('AI safety');
  },
  {
    asType: 'retriever',
    parentSpanContext: parentSpan.otelSpan.spanContext()
  }
);
```
```

--------------------------------

### Start Basic Observation with Langfuse Tracing

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/README.md

Initiates a new observation span for tracking operations. Use this for general-purpose timing and data logging within your application. Ensure `@langfuse/tracing` is imported.

```typescript
import { startObservation } from "@langfuse/tracing";

const span = startObservation("operation", { input: data });
span.update({ output: result });
span.end();
```

--------------------------------

### LLM Application Tracing with OpenAI Wrapper

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Traces LLM calls using OpenAI client, starting an active observation for the generation. Requires @langfuse/tracing and @langfuse/openai.

```typescript
import { startActiveObservation } from "@langfuse/tracing";
import { wrapOpenAiClient } from "@langfuse/openai";

const response = await startActiveObservation(
  "llm-call",
  async (gen) => {
    const result = await openai.chat.completions.create({...});
    return result;
  },
  { asType: "generation" }
);
```

--------------------------------

### Experiment with Evaluations using Langfuse

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Run experiments with custom evaluators using Langfuse. This example demonstrates setting up a task, defining multiple evaluators (exact match, semantic similarity), and run evaluators for aggregation.

```typescript
const result = await langfuse.experiment.run({
  name: "Model A vs B",
  data: testDataset,
  task: async ({ input, metadata }) => {
    const modelVersion = metadata?.modelVersion || "A";
    return await models[modelVersion].predict(input);
  },
  evaluators: [
    async ({ output, expectedOutput }) => ({
      name: "exact_match",
      value: output === expectedOutput ? 1 : 0
    }),
    async ({ output, expectedOutput }) => ({
      name: "semantic_similarity",
      value: calculateSimilarity(output, expectedOutput)
    })
  ],
  runEvaluators: [
    async ({ itemResults }) => {
      const avgScore = itemResults
        .flatMap(r => r.evaluations)
        .reduce((a, b) => a + b.value, 0) / itemResults.length;
      return { name: "average_score", value: avgScore };
    }
  ]
});

```

--------------------------------

### Get Prompt with Label Filter

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves a prompt that matches the specified label. This is useful for filtering prompts, for example, to get a production-ready version.

```typescript
// Get with label filter
const prodPrompt = await langfuse.prompt.get("my-prompt", {
  label: "production"
});
```

--------------------------------

### RAG Pipeline with Langfuse Tracing

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Trace a Retrieval-Augmented Generation (RAG) pipeline using Langfuse. This example demonstrates tracing 'vector-search' and 'answer-generation' steps within a main 'rag-pipeline' observation.

```typescript
const answer = await startActiveObservation(
  "rag-pipeline",
  async (chain) => {
    // Retrieve
    const docs = await startActiveObservation(
      "vector-search",
      async (retriever) => {
        retriever.update({ input: { query: question } });
        const results = await vectorDb.search(question);
        retriever.update({ output: { count: results.length } });
        return results;
      },
      { asType: "retriever" }
    );

    // Generate
    const answer = await startActiveObservation(
      "answer-generation",
      async (gen) => {
        const context = docs.map(d => d.content).join("\n");
        gen.update({ input: { question, context }, model: "gpt-4" });
        const result = await llm.generate(context);
        gen.update({ output: result });
        return result;
      },
      { asType: "generation" }
    );

    chain.update({ output: { answer, sources: docs.length } });
    return answer;
  },
  { asType: "chain" }
);

```

--------------------------------

### Build All Packages with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Execute this command to build all packages in the monorepo.

```bash
pnpm build
```

--------------------------------

### LangfuseClient Initialization and Lifecycle

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/README.md

Documentation for the main LangfuseClient, covering its initialization and lifecycle management methods.

```APIDOC
## LangfuseClient

### Description
Provides methods for initializing and managing the lifecycle of the Langfuse client.

### Usage
```typescript
import { Langfuse } from '@langfuse/client';

const langfuse = new Langfuse({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
  // Other configuration options
});

// Use langfuse client for SDK operations
```

### Configuration Options
Refer to the [Configuration](./configuration.md) documentation for a complete list of constructor parameters and environment variables.
```

--------------------------------

### Get Active Trace ID

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Gets the current active trace ID. Returns undefined if there is no span in the current context.

```typescript
function getActiveTraceId(): string | undefined
```

--------------------------------

### Get Active Span ID

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Gets the current active observation ID. Returns undefined if there is no OTEL span in the current context.

```typescript
function getActiveSpanId(): string | undefined
```

--------------------------------

### TextPromptClient Constructor

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-clients.md

Initializes a new TextPromptClient instance with prompt data and an optional fallback flag.

```APIDOC
## TextPromptClient Constructor

### Description
Creates a new TextPromptClient instance.

### Signature
```typescript
constructor(prompt: Prompt.Text, isFallback?: boolean): TextPromptClient
```

### Parameters
#### Path Parameters
- **prompt** (Prompt.Text) - Required - The text prompt data returned from the API
- **isFallback** (boolean) - Optional - Whether this is fallback content (defaults to false)
```

--------------------------------

### Run Unit Tests with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Use this command to run all unit tests for the project.

```bash
pnpm test
```

--------------------------------

### Build Packages

Source: https://github.com/langfuse/langfuse-js/blob/main/CONTRIBUTING.md

Builds all packages in the monorepo. Use the --watch flag for continuous building during development.

```bash
# Build all packages
pnpm build

# Build and watch for changes
pnpm build --watch
```

--------------------------------

### Start Active Observation (Nested with Parent Context)

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-tracing.md

Starts a nested observation, explicitly linking it to a parent span's context. Useful for structuring complex workflows and ensuring correct trace hierarchy.

```typescript
// Nested observations with parent context
const parentSpan = startObservation('ai-pipeline');
const childRetriever = startActiveObservation(
  'doc-search',
  (retriever) => {
    retriever.update({ input: { query: 'AI safety' } });
    return search('AI safety');
  },
  {
    asType: 'retriever',
    parentSpanContext: parentSpan.otelSpan.spanContext()
  }
);
```

--------------------------------

### Initialize LangfuseClient Using Environment Variables

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/configuration.md

Instantiate the LangfuseClient without explicit parameters, relying on environment variables for configuration.

```typescript
import { LangfuseClient } from "@langfuse/client";

// Using environment variables
const client = new LangfuseClient();
```

--------------------------------

### Full CI Check with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Run a comprehensive check that mimics the CI environment.

```bash
pnpm ci
```

--------------------------------

### Integration Behavior Verification

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Verify integration behavior by running integration tests. Ensure packages are built first if necessary.

```bash
pnpm build
pnpm test:integration
```

--------------------------------

### Get All Prompts

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves all prompts managed by Langfuse. Ensure you have initialized the Langfuse client before calling this method.

```typescript
import { init } from "@langfuse/client";

const langfuse = init({
  public_key: "YOUR_PUBLIC_KEY",
  secret_key: "YOUR_SECRET_KEY",
});

async function getAllPrompts() {
  const prompts = await langfuse.prompt.getAll();
  console.log(prompts);
}

getAllPrompts();
```

--------------------------------

### Initialize Langfuse Client and Use Managers

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Instantiate the Langfuse client with your public and secret keys. Use the provided managers for prompt, dataset, and experiment operations.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_..."
});

// Use managers
const prompt = await langfuse.prompt.get("my-prompt");
const dataset = await langfuse.dataset.get("my-dataset");

// Create experiments
const result = await langfuse.experiment.run({
  name: "Model Test",
  data: [...],
  task: async (item) => { ... }
});
```

--------------------------------

### Get Prompt by ID

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Fetches a specific prompt using its unique ID. This is useful for accessing details of a single prompt.

```typescript
import { init } from "@langfuse/client";

const langfuse = init({
  public_key: "YOUR_PUBLIC_KEY",
  secret_key: "YOUR_SECRET_KEY",
});

async function getPromptById(promptId: string) {
  const prompt = await langfuse.prompt.get(promptId);
  console.log(prompt);
}

getPromptById("YOUR_PROMPT_ID");
```

--------------------------------

### Configuration

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/MANIFEST.md

Configuration options for various SDK components.

```APIDOC
## Configuration

### LangfuseClient Constructor Parameters

- **`baseUrl`** (string): The base URL for the Langfuse API.
- **`apiKey`** (string): Your Langfuse API key.
- **`projectKey`** (string): Your Langfuse project key.
- **`debug`** (boolean): Enable debug logging.
- **`instance`** (object): Optional custom fetch instance.

### ScoreManager Environment Variables

- **`FLUSH_AT`** (string): Threshold for flushing scores.
- **`FLUSH_INTERVAL`** (string): Interval for flushing scores.

### PromptManager.get() Options

- **`limit`** (number): Number of prompts to retrieve.
- **`page`** (number): Page number for pagination.
- **`where`** (object): Filtering criteria.
- **`orderBy`** (string): Field to order by.
- **`order`** (string): Order direction (ASC/DESC).
- **`datasetId`** (string): Filter by dataset ID.
- **`datasetName`** (string): Filter by dataset name.
- **`promptName`** (string): Filter by prompt name.

### DatasetManager.get() Options

- **`limit`** (number): Number of datasets to retrieve.
- **`page`** (number): Page number for pagination.

### MediaManager.resolveReferences() Options

- **`baseUrl`** (string): Base URL for resolving references.
- **`apiKey`** (string): API key for authentication.
- **`projectKey`** (string): Project key for authentication.

### Observation Type Attribute Options

All observation types accept specific attribute options relevant to their function (e.g., `input`, `output`, `model`, `temperature` for `LangfuseGeneration`).

### ExperimentManager.run() Config Parameters

- **`experimentId`** (string): The ID of the experiment to run.
- **`datasetId`** (string): The ID of the dataset to use for the experiment.
- **`model`** (string): The model to use for the experiment.
- **`promptName`** (string): The name of the prompt to use.
- **`evaluator`** (Evaluator): The evaluator function to use.
- **`run`** (object): Configuration for the experiment run.
```

--------------------------------

### Get Specific Prompt Version

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves a specific version of a prompt by providing the version number in the options. Caching is applied.

```typescript
// Get specific version
const v2Prompt = await langfuse.prompt.get("my-prompt", {
  version: 2
});
```

--------------------------------

### Create Prompt

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Creates a new prompt with the provided details.

```APIDOC
## POST /prompts

### Description
Creates a new prompt.

### Method
POST

### Endpoint
/prompts

### Request Body
- **body** (CreatePromptBody) - Required - The details of the prompt to create.

  - **{string} name** - Required - The name of the prompt.
  - **{string} promptName** - Required - The name of the prompt (alias for name).
  - **{string} content** - Required - The content of the prompt.
  - **{string} [template]** - Optional - The template of the prompt.
  - **{string} [model]** - Optional - The model to use for the prompt.
  - **{string} [modelVersion]** - Optional - The version of the model.
  - **{string} [datasetId]** - Optional - The ID of the dataset associated with the prompt.
  - **{string} [datasetName]** - Optional - The name of the dataset associated with the prompt.
  - **{string} [tags]** - Optional - An array of tags for the prompt.
  - **{string} [userId]** - Optional - The ID of the user who created the prompt.
  - **{string} [metadata]** - Optional - Additional metadata for the prompt.

### Request Example
```json
{
  "name": "My Prompt",
  "content": "This is the content of my prompt.",
  "template": "{{input}}",
  "model": "gpt-4",
  "tags": ["example", "test"]
}
```

### Response
#### Success Response (201)
- **{Prompt}** - The created prompt object.
```

--------------------------------

### ChatPromptClient Constructor

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-clients.md

Initializes a new ChatPromptClient instance with prompt data and an optional fallback flag.

```APIDOC
## ChatPromptClient Constructor

### Description
Creates a new ChatPromptClient instance.

### Parameters
#### Path Parameters
- **prompt** (Prompt.Chat) - Required - The chat prompt data returned from the API
- **isFallback** (boolean) - Optional - Whether this is fallback content (defaults to false)
```

--------------------------------

### Run Integration Tests with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Execute integration tests after building the packages.

```bash
pnpm test:integration
```

--------------------------------

### Get Prompt Versions

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves all versions of a specific prompt identified by its ID. This helps in managing and comparing different prompt iterations.

```typescript
import { init } from "@langfuse/client";

const langfuse = init({
  public_key: "YOUR_PUBLIC_KEY",
  secret_key: "YOUR_SECRET_KEY",
});

async function getPromptVersions(promptId: string) {
  const versions = await langfuse.prompt.getAllVersions(promptId);
  console.log(versions);
}

getPromptVersions("YOUR_PROMPT_ID");
```

--------------------------------

### LangfuseClient Initialization

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Initialize the Langfuse client with your public key, secret key, base URL, and optional timeout.

```APIDOC
## LangfuseClient Initialization

### Description
Initialize the Langfuse client with your public key, secret key, base URL, and optional timeout.

### Method
```typescript
new LangfuseClient({ publicKey: "pk_...", secretKey: "sk_...", baseUrl: "https://cloud.langfuse.com", timeout: 5 })
```
```

--------------------------------

### Manual Observation Lifecycle

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Use this pattern to manually control the lifecycle of an observation. Start an observation, update it with input and output, and then end it.

```typescript
const observation = startObservation('name', { 
  input: data 
}, { asType: 'type' });

observation.update({ 
  output: result,
  metadata: { additional: 'info' }
});

observation.end();
```

--------------------------------

### Check Formatting with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Verify that all code adheres to the project's formatting rules.

```bash
pnpm format:check
```

--------------------------------

### Start and Update Langfuse Embedding

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Initiates an embedding observation and updates it with output and token usage. Ensure to call `.end()` after updating.

```typescript
const embedding = startObservation('text-embeddings', {
  input: { texts: ['Hello', 'World'] },
  model: 'text-embedding-ada-002'
}, { asType: 'embedding' });

embedding.update({
  output: { embeddings: [[0.1, 0.2, ...], [0.3, 0.4, ...]] },
  usageDetails: { totalTokens: 8 }
});
embedding.end();
```

--------------------------------

### Update Currently Active Observation

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Update the currently active observation within a scope, useful for modifying an observation that was started with `startActiveObservation`.

```APIDOC
## Update Currently Active Observation

### Description
Update the currently active observation within a scope, useful for modifying an observation that was started with `startActiveObservation`.

### Code
```typescript
await startActiveObservation("task", (span) => {
  updateActiveObservation({ output: { data: "result" } });
});
```
```

--------------------------------

### create()

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Creates a new prompt in Langfuse. Supports both text and chat prompts. Chat prompts can include placeholders for dynamic content insertion.

```APIDOC
## create()

### Description
Creates a new prompt in Langfuse. Supports both text and chat prompts. Chat prompts can include placeholders for dynamic content insertion.

### Method
`POST`

### Endpoint
`/prompts`

### Parameters
#### Request Body
- **name** (string) - Required - Unique identifier for the prompt
- **type** (string) - Optional - Type of prompt (`text` or `chat`)
- **prompt** (string | ChatMessage[]) - Required - Prompt content (string for text, array of messages for chat)
- **version** (number) - Optional - Optional version number
- **labels** (string[]) - Optional - Optional labels/tags for versioning
- **config** (Record<string, any>) - Optional - Optional configuration object
- **tags** (string[]) - Optional - Optional tags for categorization

### Request Example
```json
{
  "name": "greeting",
  "prompt": "Hello {{name}}!",
  "type": "text"
}
```

### Response
#### Success Response (200)
- **TextPromptClient** or **ChatPromptClient** - Depending on prompt type

#### Response Example
```json
{
  "id": "prompt-id-123",
  "name": "greeting",
  "type": "text",
  "prompt": "Hello {{name}}!",
  "version": 1,
  "createdAt": "2023-01-01T12:00:00Z",
  "updatedAt": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### Retrieve a Dataset

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-dataset-manager.md

Fetches a dataset by name. Use this to get dataset details and items. The `fetchItemsPageSize` option can be adjusted for performance with large datasets.

```typescript
const dataset = await langfuse.dataset.get("my-evaluation-dataset");
console.log(`Dataset ${dataset.name} has ${dataset.items.length} items`);
console.log(dataset.description);
console.log(dataset.metadata);
```

```typescript
const largeDataset = await langfuse.dataset.get(
  "large-dataset",
  { fetchItemsPageSize: 100 }
);
```

--------------------------------

### Create a New Prompt

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Creates a new prompt in Langfuse. This requires a name and optionally a description and version.

```typescript
import { init } from "@langfuse/client";

const langfuse = init({
  public_key: "YOUR_PUBLIC_KEY",
  secret_key: "YOUR_SECRET_KEY",
});

async function createPrompt() {
  const prompt = await langfuse.prompt.create({
    name: "My New Prompt",
    description: "This is a test prompt.",
    version: "1.0.0",
  });
  console.log(prompt);
}

createPrompt();
```

--------------------------------

### Start and Update Langfuse Generation

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-observations.md

Initiates a generation observation and updates it with output, usage, and cost details. Ensure to call `.end()` after updating.

```typescript
const gen = startObservation('openai-gpt-4', {
  input: [{ role: 'user', content: 'Hello' }],
  model: 'gpt-4-turbo'
}, { asType: 'generation' });

gen.update({
  output: { role: 'assistant', content: 'Hi there!' },
  usageDetails: {
    promptTokens: 10,
    completionTokens: 5,
    totalTokens: 15
  },
  costDetails: { totalCost: 0.0005, currency: 'USD' }
});
gen.end();
```

--------------------------------

### Manual Local Release Commands

Source: https://github.com/langfuse/langfuse-js/blob/main/CONTRIBUTING.md

Use these commands for manual releases if GitHub Actions are unavailable. Ensure you have npm authentication and are on the main branch with a clean working directory.

```bash
pnpm release

pnpm release:alpha  # Alpha release
pnpm release:beta   # Beta release
pnpm release:rc     # Release candidate

pnpm release:dry
```

--------------------------------

### Serialize Chat Prompt Client to JSON

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-clients.md

Use this method to get a JSON string representation of the current prompt client, including its configuration and content.

```typescript
public toJSON(): string

```

--------------------------------

### Get Latest Prompt with Caching

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves the latest version of a prompt by its name. This method utilizes intelligent caching, returning fresh or background-refreshed prompts.

```typescript
// Get latest version with caching
const prompt = await langfuse.prompt.get("my-prompt");
```

--------------------------------

### TextPromptClient.getLangchainPrompt()

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-clients.md

Converts the prompt to LangChain PromptTemplate format, transforming Mustache syntax to LangChain's format.

```APIDOC
## TextPromptClient.getLangchainPrompt()

### Description
Converts the prompt to LangChain PromptTemplate format. Transforms Mustache-style `{{variable}}` syntax to LangChain's `{variable}` format.

### Signature
```typescript
public getLangchainPrompt(options?: { placeholders?: Record<string, any> }): string
```

### Parameters
#### Path Parameters
- **options.placeholders** (Record<string, any>) - Optional - Placeholders to resolve during conversion (ignored for text)

### Returns
- **string** - 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}!"
```
```

--------------------------------

### Get Trace URL

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-client.md

Generates a URL to view a specific trace in the Langfuse UI. The project ID is automatically fetched and cached on the first call.

```typescript
const traceId = "trace-123";
const url = await langfuse.getTraceUrl(traceId);
console.log(`View trace at: ${url}`);
```

--------------------------------

### Run E2E Tests with pnpm

Source: https://github.com/langfuse/langfuse-js/blob/main/AGENTS.md

Run end-to-end tests against a Langfuse server. Ensure Langfuse credentials are set.

```bash
pnpm test:e2e
```

--------------------------------

### LangfuseClient Constructor

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-client.md

Initializes a new LangfuseClient instance. Configuration can be provided via parameters or environment variables.

```APIDOC
## Constructor

```typescript
constructor(params?: LangfuseClientParams): LangfuseClient
```

Creates a new LangfuseClient instance with optional configuration parameters.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| params.publicKey | string | — | Public API key for authentication. Falls back to `LANGFUSE_PUBLIC_KEY` environment variable |
| params.secretKey | string | — | Secret API key for authentication. Falls back to `LANGFUSE_SECRET_KEY` environment variable |
| params.baseUrl | string | `https://cloud.langfuse.com` | Base URL of the Langfuse instance. Falls back to `LANGFUSE_BASE_URL` or `LANGFUSE_BASEURL` environment variable |
| params.timeout | number | 5 | Request timeout in seconds. Falls back to `LANGFUSE_TIMEOUT` environment variable |
| params.additionalHeaders | Record<string, string> | — | Additional HTTP headers to include with API requests |

### Example

```typescript
import { LangfuseClient } from "@langfuse/client";

// With explicit configuration
const client = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_...",
  baseUrl: "https://your-instance.langfuse.com",
  timeout: 10
});

// Using environment variables
const client = new LangfuseClient();
```
```

--------------------------------

### Update Currently Active Observation

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Modify the currently active observation within its scope using updateActiveObservation. This is useful for updating an observation that was started with startActiveObservation.

```typescript
await startActiveObservation("task", (span) => {
  updateActiveObservation({ output: { data: "result" } });
});
```

--------------------------------

### Initialize LangfuseClient with Explicit Configuration

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/configuration.md

Instantiate the LangfuseClient by providing configuration parameters directly in the constructor.

```typescript
import { LangfuseClient } from "@langfuse/client";

// With explicit configuration
const client = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_...",
  baseUrl: "https://your-instance.langfuse.com",
  timeout: 10
});
```

--------------------------------

### Manage Datasets

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/quick-reference.md

Retrieve datasets, iterate through their items, and link items to runs. Also shows how to run experiments on a dataset.

```typescript
// Get dataset with items
const dataset = await langfuse.dataset.get("dataset-name");

// Iterate items
for (const item of dataset.items) {
  console.log(item.input, item.expectedOutput);
  await item.link({ otelSpan: span }, "run-name");
}

// Run experiment on dataset
const result = await dataset.runExperiment({
  name: "Model Test",
  task: async ({ input }) => model.predict(input),
  evaluators: [evaluator]
});
```

--------------------------------

### Get Specific Prompt Version

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Fetches a particular version of a prompt using both the prompt ID and the version number. This allows for precise retrieval of historical prompt data.

```typescript
import { init } from "@langfuse/client";

const langfuse = init({
  public_key: "YOUR_PUBLIC_KEY",
  secret_key: "YOUR_SECRET_KEY",
});

async function getSpecificPromptVersion(promptId: string, version: string) {
  const promptVersion = await langfuse.prompt.getVersion(promptId, version);
  console.log(promptVersion);
}

getSpecificPromptVersion("YOUR_PROMPT_ID", "1.0.0");
```

--------------------------------

### Get Prompt with Custom Cache TTL

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves a prompt and allows customization of the cache Time-To-Live (TTL) in seconds. Setting `cacheTtlSeconds` to 0 disables caching for this request.

```typescript
// Get with custom cache TTL
const cachedPrompt = await langfuse.prompt.get("my-prompt", {
  cacheTtlSeconds: 300
});
```

--------------------------------

### Instantiate LangfuseClient

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-client.md

Create a new LangfuseClient instance. Configuration can be provided explicitly or by using environment variables.

```typescript
import { LangfuseClient } from "@langfuse/client";

// With explicit configuration
const client = new LangfuseClient({
  publicKey: "pk_...",
  secretKey: "sk_...",
  baseUrl: "https://your-instance.langfuse.com",
  timeout: 10
});

// Using environment variables
const client = new LangfuseClient();
```

--------------------------------

### Get Prompt with Fallback Content

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/langfuse-prompt-manager.md

Retrieves a prompt, providing fallback content in case the prompt fetch fails. This ensures a default prompt is used if the primary one cannot be loaded.

```typescript
// Get with fallback
const promptWithFallback = await langfuse.prompt.get("my-prompt", {
  type: "text",
  fallback: "Hello {{name}}!"
});
```

--------------------------------

### Langfuse Tracing: Manual and Active Observations

Source: https://github.com/langfuse/langfuse-js/blob/main/_autodocs/packages-overview.md

Create observations manually using `startObservation` or manage context with `startActiveObservation`. The latter is useful for LLM calls where you need to update the generation object.

```typescript
import { startObservation, startActiveObservation, observe } from "@langfuse/tracing";

// Manual observation creation
const span = startObservation("my-operation", { input: "data" });
span.update({ output: "result" });
span.end();

// Active observation with context
const result = await startActiveObservation(
  "llm-call",
  async (generation) => {
    generation.update({ model: "gpt-4" });
    const output = await llm.generate("prompt");
    generation.update({ output });
    return output;
  },
  { asType: "generation" }
);

// Function decorator
const myFunction = observe(
  async (input) => { ... },
  { name: "my-task", captureInput: true, captureOutput: true }
);
```

--------------------------------

### Run Integration Tests

Source: https://github.com/langfuse/langfuse-js/blob/main/CONTRIBUTING.md

Executes integration tests locally using a MockSpanExporter. Supports watch mode for continuous testing.

```bash
# Run integration tests
pnpm test:integration

# Run integration tests in watch mode
pnpm test:integration:watch
```