Class: Langfuse::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/langfuse/client.rb

Overview

Main client for Langfuse SDK

Provides a unified interface for interacting with the Langfuse API. Handles prompt fetching and returns the appropriate prompt client (TextPromptClient or ChatPromptClient) based on the prompt type.

rubocop:disable Metrics/ClassLength

Examples:

config = Langfuse::Config.new(
  public_key: "pk_...",
  secret_key: "sk_...",
  cache_ttl: 120
)
client = Langfuse::Client.new(config)
prompt = client.get_prompt("greeting")
compiled = prompt.compile(name: "Alice")

Constant Summary collapse

DATASET_ITEMS_PAGE_SIZE =

Returns Default page size when fetching all dataset items.

Returns:

  • (Integer) —

    Default page size when fetching all dataset items

50

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ Client

Initialize a new Langfuse client

Parameters:

  • config (Config) —

    Configuration object



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/langfuse/client.rb', line 79

def initialize(config)
  @config = config
  @api_client_mutex = Mutex.new
  @score_client_mutex = Mutex.new
  @project_id = nil
  # One-shot lookup: avoids repeated blocking API calls in URL helpers
  # (trace_url, dataset_url, dataset_run_url) when the project endpoint is down.
  @project_id_fetched = false
  if telemetry_enabled?
    config.validate!
    @api_client = build_api_client
    @score_client = build_score_client
  else
    config.validate_telemetry_disabled!
  end
end

Instance Attribute Details

#config ⇒ Config (readonly)

Returns The client configuration.

Returns:

  • (Config) —

    The client configuration



30
31
32
 
# File 'lib/langfuse/client.rb', line 30

def config
  @config
end

Instance Method Details

#api_client ⇒ ApiClient

Return the underlying API client, building it on first non-telemetry use.

Returns:

Raises:



36
37
38
 
# File 'lib/langfuse/client.rb', line 36

def api_client
  @api_client || @api_client_mutex.synchronize { @api_client ||= build_validated_api_client }
end

#clear_prompt_cache ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil) ⇒ String, Array<Hash>

Convenience method: fetch and compile a prompt in one call

This is a shorthand for calling get_prompt followed by compile. Returns the compiled prompt ready to use with your LLM.

rubocop:disable Metrics/ParameterLists

Examples:

Compile a text prompt

text = client.compile_prompt("greeting", variables: { name: "Alice" })
# => "Hello Alice!"

Compile a chat prompt

messages = client.compile_prompt("support-bot", variables: { company: "Acme" })
# => [{ role: :system, content: "You are a support agent for Acme" }]

With fallback

text = client.compile_prompt(
  "greeting",
  variables: { name: "Alice" },
  fallback: "Hello {{name}}!",
  type: :text
)

Parameters:

  • name (String) —

    The name of the prompt

  • variables (Hash) (defaults to: {}) —

    Variables to substitute in the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., "production", "latest")

  • fallback (String, Array, nil) (defaults to: nil) —

    Optional fallback prompt to use on error

  • type (Symbol, nil) (defaults to: nil) —

    Required when fallback is provided (:text or :chat)

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override for this fetch

Returns:

  • (String, Array<Hash>) —

    Compiled prompt (String for text, Array for chat)

Raises:

  • (ArgumentError) —

    if both version and label are provided

  • (ArgumentError) —

    if fallback is provided without type

  • (NotFoundError) —

    if the prompt is not found and no fallback provided

  • (UnauthorizedError) —

    if authentication fails and no fallback provided

  • (ApiError) —

    for other API errors and no fallback provided



206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/langfuse/client.rb', line 206

def compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
  prompt = get_prompt(
    name,
    version: version,
    label: label,
    fallback: fallback,
    type: type,
    cache_ttl: cache_ttl
  )
  prompt.compile(**variables)
end

#create_dataset(name:, description: nil, metadata: nil) ⇒ DatasetClient

Create a new dataset

Examples:

dataset = client.create_dataset(name: "my-dataset", description: "QA evaluation set")

Parameters:

  • name (String) —

    Dataset name (required)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

Returns:

Raises:



526
527
528
529
 
# File 'lib/langfuse/client.rb', line 526

def create_dataset(name:, description: nil, metadata: nil)
  data = api_client.create_dataset(name: name, description: description, metadata: metadata)
  DatasetClient.new(data, client: self)
end

#create_dataset_item(dataset_name:, input: nil, expected_output: nil, metadata: nil, id: nil, source_trace_id: nil, source_observation_id: nil, status: nil) ⇒ DatasetItemClient

Create a new dataset item

rubocop:disable Metrics/ParameterLists

Examples:

item = client.create_dataset_item(
  dataset_name: "my-dataset",
  input: { query: "What is Ruby?" },
  expected_output: { answer: "A programming language" }
)

Parameters:

  • dataset_name (String) —

    Name of the dataset to add item to (required)

  • input (Object, nil) (defaults to: nil) —

    Input data for the item

  • expected_output (Object, nil) (defaults to: nil) —

    Expected output for evaluation

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

  • id (String, nil) (defaults to: nil) —

    Optional ID for upsert behavior

  • source_trace_id (String, nil) (defaults to: nil) —

    Link to source trace

  • source_observation_id (String, nil) (defaults to: nil) —

    Link to source observation

  • status (Symbol, nil) (defaults to: nil) —

    Item status (:active or :archived)

Returns:

Raises:



567
568
569
570
571
572
573
574
575
576
 
# File 'lib/langfuse/client.rb', line 567

def create_dataset_item(dataset_name:, input: nil, expected_output: nil,
                        metadata: nil, id: nil, source_trace_id: nil,
                        source_observation_id: nil, status: nil)
  data = api_client.create_dataset_item(
    dataset_name: dataset_name, input: input, expected_output: expected_output,
    metadata: metadata, id: id, source_trace_id: source_trace_id,
    source_observation_id: source_observation_id, status: status
  )
  DatasetItemClient.new(data, client: self)
end

#create_dataset_run_item(**) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil) ⇒ TextPromptClient, ChatPromptClient

Create a new prompt (or new version if name already exists)

Creates a new prompt in Langfuse. If a prompt with the same name already exists, this creates a new version of that prompt.

rubocop:disable Metrics/ParameterLists

Examples:

Create a text prompt

prompt = client.create_prompt(
  name: "greeting",
  prompt: "Hello {{name}}!",
  type: :text,
  labels: ["production"],
  config: { model: "gpt-4o", temperature: 0.7 }
)

Create a chat prompt

prompt = client.create_prompt(
  name: "support-bot",
  prompt: [
    { role: "system", content: "You are a {{role}} assistant" },
    { role: "user", content: "{{question}}" }
  ],
  type: :chat,
  labels: ["staging"]
)

Parameters:

  • name (String) —

    The prompt name (required)

  • prompt (String, Array<Hash>) —

    The prompt content (required)

    • For text prompts: a string with {variable} placeholders
    • For chat prompts: array of message hashes with role and content
  • type (Symbol) —

    Prompt type (:text or :chat) (required)

  • config (Hash) (defaults to: {}) —

    Optional configuration (model parameters, tools, etc.)

  • labels (Array<String>) (defaults to: []) —

    Optional labels (e.g., ["production"])

  • tags (Array<String>) (defaults to: []) —

    Optional tags for categorization

  • commit_message (String, nil) (defaults to: nil) —

    Optional commit message

Returns:

Raises:

  • (ArgumentError) —

    if required parameters are missing or invalid

  • (UnauthorizedError) —

    if authentication fails

  • (ApiError) —

    for other API errors



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/langfuse/client.rb', line 258

def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
  validate_prompt_type!(type)
  validate_prompt_content!(prompt, type)

  prompt_data = api_client.create_prompt(
    name: name,
    prompt: normalize_prompt_content(prompt, type),
    type: type.to_s,
    config: config,
    labels: labels,
    tags: tags,
    commit_message: commit_message
  )

  build_prompt_client(prompt_data)
end

#create_score(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil, metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil) ⇒ void

This method returns an undefined value.

Create a score event and queue it for batching

rubocop:disable Metrics/ParameterLists

Examples:

Numeric score

client.create_score(name: "quality", value: 0.85, trace_id: "abc123")

Boolean score

client.create_score(name: "passed", value: true, trace_id: "abc123", data_type: :boolean)

Categorical score

client.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)

Text score (1 to 500 characters)

client.create_score(name: "reviewer_notes", value: "Helpful but verbose",
                    trace_id: "abc123", data_type: :text)

Corrected output (conventionally named "output")

client.create_score(name: "output", value: "The corrected output", trace_id: "abc123",
                    observation_id: "def456", data_type: :correction)

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value (type depends on data_type)

  • id (String, nil) (defaults to: nil) —

    Score ID; use a stable value as an idempotency key

  • trace_id (String, nil) (defaults to: nil) —

    Trace ID to associate with the score

  • session_id (String, nil) (defaults to: nil) —

    Session ID to associate with the score

  • observation_id (String, nil) (defaults to: nil) —

    Observation ID to associate with the score

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • environment (String, nil) (defaults to: nil) —

    Optional per-score environment override

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical, :text, :correction)

  • dataset_run_id (String, nil) (defaults to: nil) —

    Optional dataset run ID to associate with the score

  • config_id (String, nil) (defaults to: nil) —

    Optional score config ID

Raises:

  • (ArgumentError) —

    if validation fails



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/langfuse/client.rb', line 381

def create_score(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
                 metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
  active_score_client&.create(
    name: name,
    value: value,
    id: id,
    trace_id: trace_id,
    session_id: session_id,
    observation_id: observation_id,
    comment: comment,
    metadata: metadata,
    environment: environment,
    data_type: data_type,
    dataset_run_id: dataset_run_id,
    config_id: config_id
  )
end

#create_score!(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil, metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil) ⇒ String?

Create a score immediately through the Scores API. See ScoreClient#create!.

rubocop:disable Metrics/ParameterLists

Examples:

Create a score with an idempotency key

client.create_score!(id: "feedback-abc123", name: "quality", value: 0.85, trace_id: "abc123")

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value (type depends on data_type)

  • id (String, nil) (defaults to: nil) —

    Score ID; use a stable value as an idempotency key

  • trace_id (String, nil) (defaults to: nil) —

    Trace ID to associate with the score

  • session_id (String, nil) (defaults to: nil) —

    Session ID to associate with the score

  • observation_id (String, nil) (defaults to: nil) —

    Observation ID to associate with the score

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • environment (String, nil) (defaults to: nil) —

    Optional per-score environment override

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical, :text, :correction)

  • dataset_run_id (String, nil) (defaults to: nil) —

    Optional dataset run ID to associate with the score

  • config_id (String, nil) (defaults to: nil) —

    Optional score config ID

Returns:

  • (String, nil) —

    ID of the created score, or nil when telemetry is disabled

Raises:

  • (ArgumentError) —

    if validation fails

  • (UnauthorizedError) —

    if authentication fails

  • (ApiError) —

    if the API request fails



422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/langfuse/client.rb', line 422

def create_score!(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
                  metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
  active_score_client&.create!(
    name: name,
    value: value,
    id: id,
    trace_id: trace_id,
    session_id: session_id,
    observation_id: observation_id,
    comment: comment,
    metadata: metadata,
    environment: environment,
    data_type: data_type,
    dataset_run_id: dataset_run_id,
    config_id: config_id
  )
end

#dataset_run_url(dataset_id:, dataset_run_id:) ⇒ String?

Generate URL for viewing a dataset run in Langfuse UI

Parameters:

  • dataset_id (String) —

    The dataset ID

  • dataset_run_id (String) —

    The dataset run ID

Returns:

  • (String, nil) —

    URL to view the dataset run, or nil if project ID unavailable



343
344
345
 
# File 'lib/langfuse/client.rb', line 343

def dataset_run_url(dataset_id:, dataset_run_id:)
  project_url("datasets/#{dataset_id}/runs/#{dataset_run_id}")
end

#dataset_url(dataset_id) ⇒ String?

Generate URL for viewing a dataset in Langfuse UI

Parameters:

  • dataset_id (String) —

    The dataset ID

Returns:

  • (String, nil) —

    URL to view the dataset, or nil if project ID unavailable



334
335
336
 
# File 'lib/langfuse/client.rb', line 334

def dataset_url(dataset_id)
  project_url("datasets/#{dataset_id}")
end

#delete_dataset_item(id) ⇒ nil

Note:

404 responses are treated as success to keep DELETE idempotent across retries

Delete a dataset item by ID

Examples:

client.delete_dataset_item("item-uuid-123")

Parameters:

  • id (String) —

    Dataset item ID

Returns:

  • (nil)

Raises:



634
635
636
637
 
# File 'lib/langfuse/client.rb', line 634

def delete_dataset_item(id)
  api_client.delete_dataset_item(id)
  nil
end

#delete_dataset_run(dataset_name:, run_name:) ⇒ nil

Note:

404 responses raise NotFoundError to preserve strict delete semantics

Delete a dataset run by name

Parameters:

  • dataset_name (String) —

    Dataset name (required)

  • run_name (String) —

    Run name (required)

Returns:

  • (nil)

Raises:



667
668
669
670
 
# File 'lib/langfuse/client.rb', line 667

def delete_dataset_run(dataset_name:, run_name:)
  api_client.delete_dataset_run(dataset_name: dataset_name, run_name: run_name)
  nil
end

#flush_scores ⇒ void

This method returns an undefined value.

Force flush all queued score events

Sends all queued score events to the API immediately.

Examples:

client.flush_scores


501
502
503
 
# File 'lib/langfuse/client.rb', line 501

def flush_scores
  active_score_client&.flush
end

#get_dataset(name) ⇒ DatasetClient

Fetch a dataset by name

Examples:

dataset = client.get_dataset("my-dataset")

Parameters:

  • name (String) —

    Dataset name (supports folder paths like "evaluation/qa-dataset")

Returns:

Raises:



541
542
543
544
 
# File 'lib/langfuse/client.rb', line 541

def get_dataset(name)
  data = api_client.get_dataset(name)
  DatasetClient.new(data, client: self)
end

#get_dataset_item(id) ⇒ DatasetItemClient

Fetch a dataset item by ID

Examples:

item = client.get_dataset_item("item-uuid-123")

Parameters:

  • id (String) —

    Dataset item ID

Returns:

Raises:



589
590
591
592
 
# File 'lib/langfuse/client.rb', line 589

def get_dataset_item(id)
  data = api_client.get_dataset_item(id)
  DatasetItemClient.new(data, client: self)
end

#get_dataset_run(dataset_name:, run_name:) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#get_prompt(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil) ⇒ TextPromptClient, ChatPromptClient

Fetch a prompt and return the appropriate client

Fetches the prompt from the Langfuse API and returns either a TextPromptClient or ChatPromptClient based on the prompt type.

Examples:

With fallback for graceful degradation

prompt = client.get_prompt("greeting", fallback: "Hello {{name}}!", type: :text)

Parameters:

  • name (String) —

    The name of the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., "production", "latest")

  • fallback (String, Array, nil) (defaults to: nil) —

    Optional fallback prompt to use on error

  • type (Symbol, nil) (defaults to: nil) —

    Required when fallback is provided (:text or :chat)

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override for this fetch

Returns:

Raises:

  • (ArgumentError) —

    if both version and label are provided

  • (ArgumentError) —

    if fallback is provided without type

  • (NotFoundError) —

    if the prompt is not found and no fallback provided

  • (UnauthorizedError) —

    if authentication fails and no fallback provided

  • (ApiError) —

    for other API errors and no fallback provided



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/langfuse/client.rb', line 116

def get_prompt(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
  get_prompt_result(
    name,
    version: version,
    label: label,
    fallback: fallback,
    type: type,
    cache_ttl: cache_ttl
  ).prompt
end

#get_prompt_result(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil) ⇒ PromptFetchResult

Fetch a prompt and return cache metadata.

Parameters:

  • name (String) —

    The name of the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., "production", "latest")

  • fallback (String, Array, nil) (defaults to: nil) —

    Optional fallback prompt to use on error

  • type (Symbol, nil) (defaults to: nil) —

    Required when fallback is provided (:text or :chat)

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override for this fetch

Returns:

Raises:

  • (ArgumentError) —

    if fallback is provided without type

  • (NotFoundError) —

    if the prompt is not found and no fallback provided

  • (UnauthorizedError) —

    if authentication fails and no fallback provided

  • (ApiError) —

    for other API errors and no fallback provided



140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/langfuse/client.rb', line 140

def get_prompt_result(name, version: nil, label: nil, fallback: nil, type: nil, cache_ttl: nil)
  validate_fallback_usage!(fallback, type)

  api_result = api_client.get_prompt_result(name, version: version, label: label, cache_ttl: cache_ttl)
  build_client_fetch_result(api_result, build_prompt_client(api_result.prompt))
rescue ApiError, NotFoundError, UnauthorizedError => e
  # If no fallback, re-raise the error
  raise e unless fallback

  # Log warning and return fallback
  config.logger.warn("Langfuse API error for prompt '#{name}': #{e.message}. Using fallback.")
  key = api_client.prompt_cache_key(name, version: version, label: label)
  build_fallback_prompt_result(key, fallback: fallback, type: type, cache_ttl: cache_ttl, error: e)
end

#get_trace(id) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#invalidate_prompt_cache(name, version: nil, label: nil) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#invalidate_prompt_cache_by_name(name) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#list_dataset_items(dataset_name:, page: nil, limit: nil, source_trace_id: nil, source_observation_id: nil) ⇒ Array<DatasetItemClient>

List items in a dataset

When page is nil (default), auto-paginates to fetch all items. When page is provided, returns only that single page.

Examples:

items = client.list_dataset_items(dataset_name: "my-dataset", limit: 50)

Parameters:

  • dataset_name (String) —

    Name of the dataset (required)

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

  • source_trace_id (String, nil) (defaults to: nil) —

    Filter by source trace ID

  • source_observation_id (String, nil) (defaults to: nil) —

    Filter by source observation ID

Returns:

Raises:



610
611
612
613
614
615
616
617
618
619
620
621
622
 
# File 'lib/langfuse/client.rb', line 610

def list_dataset_items(dataset_name:, page: nil, limit: nil,
                       source_trace_id: nil, source_observation_id: nil)
  filters = { dataset_name: dataset_name, source_trace_id: source_trace_id,
              source_observation_id: source_observation_id }

  items = if page
            fetch_dataset_items_page(page: page, limit: limit, **filters)
          else
            fetch_all_dataset_items(limit: limit, **filters)
          end

  items.map { |data| DatasetItemClient.new(data, client: self) }
end

#list_dataset_runs(dataset_name:, page: nil, limit: nil) ⇒ Array<Hash>

List dataset runs for a dataset

When page is nil (default), auto-paginates to fetch all runs. When page is provided, returns only that single page.

Parameters:

  • dataset_name (String) —

    Dataset name (required)

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

Returns:

  • (Array<Hash>) —

    Array of dataset run hashes

Raises:



650
651
652
653
654
655
656
 
# File 'lib/langfuse/client.rb', line 650

def list_dataset_runs(dataset_name:, page: nil, limit: nil)
  if page
    fetch_dataset_runs_page(dataset_name: dataset_name, page: page, limit: limit)
  else
    fetch_all_dataset_runs(dataset_name: dataset_name, limit: limit)
  end
end

#list_datasets(page: nil, limit: nil) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#list_observations(**options) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#list_prompts(page: nil, limit: nil) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#list_scores(**options) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#list_traces(**options) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#project_id ⇒ String?

Lazily-fetched project ID for URL generation

Fetches the project ID from the API on first access and caches it. Returns nil if the API call fails (URL generation is non-critical).

Returns:

  • (String, nil) —

    The Langfuse project ID



312
313
314
315
316
 
# File 'lib/langfuse/client.rb', line 312

def project_id
  return @project_id if @project_id_fetched

  fetch_project_id
end

#prompt_cache_key(name, version: nil, label: nil) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#prompt_cache_stats ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#query_metrics(query:) ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item

#refresh_prompt(name, version: nil, label: nil, cache_ttl: nil) ⇒ PromptFetchResult

Refresh a prompt from the API, optionally writing through to cache.

Parameters:

  • name (String) —

    The name of the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., "production", "latest")

  • cache_ttl (Integer, nil) (defaults to: nil) —

    Optional TTL override for this refresh

Returns:

Raises:

  • (ArgumentError) —

    if both version and label are provided

  • (NotFoundError) —

    if the prompt is not found

  • (UnauthorizedError) —

    if authentication fails

  • (ApiError) —

    for other API errors



166
167
168
169
 
# File 'lib/langfuse/client.rb', line 166

def refresh_prompt(name, version: nil, label: nil, cache_ttl: nil)
  api_result = api_client.refresh_prompt(name, version: version, label: label, cache_ttl: cache_ttl)
  build_client_fetch_result(api_result, build_prompt_client(api_result.prompt))
end

#run_experiment(name:, task:, data: nil, dataset_name: nil, description: nil, evaluators: [], run_evaluators: [], metadata: nil, run_name: nil) ⇒ ExperimentResult

Run an experiment against local data or a named dataset

rubocop:disable Metrics/ParameterLists

Parameters:

  • name (String) —

    Experiment/run name (required)

  • data (Array<Hash, DatasetItemClient>, nil) (defaults to: nil) —

    Local data items (each Hash with :input/:expected_output or "input"/"expected_output"; also accepts DatasetItemClient objects, e.g. when called from DatasetClient#run_experiment)

  • dataset_name (String, nil) (defaults to: nil) —

    Dataset name to fetch items from

  • task (Proc) —

    Callable receiving a single argument (the item). The item is a DatasetItemClient (when using dataset_name:) or ExperimentItem (when using data:). Tracing is handled automatically; use DatasetItemClient#run for direct span access.

  • description (String, nil) (defaults to: nil) —

    Optional run description

  • evaluators (Array<Proc>) (defaults to: []) —

    Item-level evaluators

  • run_evaluators (Array<Proc>) (defaults to: []) —

    Run-level evaluators

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

  • run_name (String, nil) (defaults to: nil) —

    Explicit run name (defaults to "name - timestamp")

Returns:

Raises:

  • (ArgumentError) 


690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
 
# File 'lib/langfuse/client.rb', line 690

def run_experiment(name:, task:, data: nil, dataset_name: nil, description: nil,
                   evaluators: [], run_evaluators: [], metadata: nil, run_name: nil)
  raise ArgumentError, "Provide either data: or dataset_name:, not both" if data && dataset_name
  raise ArgumentError, "Provide data: or dataset_name:" unless data || dataset_name

  items = resolve_experiment_items(data, dataset_name)

  ExperimentRunner.new(
    client: self,
    name: name,
    items: items,
    task: task,
    evaluators: evaluators,
    run_evaluators: run_evaluators,
    metadata: metadata,
    description: description,
    run_name: run_name
  ).execute
end

#score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric) ⇒ void

This method returns an undefined value.

Create a score for the currently active observation (from OTel span)

Extracts observation_id and trace_id from the active OpenTelemetry span.

Examples:

Langfuse.observe("operation") do |obs|
  client.score_active_observation(name: "accuracy", value: 0.92)
end

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical, :text, :correction)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



457
458
459
460
461
462
463
464
465
 
# File 'lib/langfuse/client.rb', line 457

def score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  active_score_client&.score_active_observation(
    name: name,
    value: value,
    comment: comment,
    metadata: metadata,
    data_type: data_type
  )
end

#score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric) ⇒ void

This method returns an undefined value.

Create a score for the currently active trace (from OTel span)

Extracts trace_id from the active OpenTelemetry span.

Examples:

Langfuse.observe("operation") do |obs|
  client.score_active_trace(name: "overall_quality", value: 5)
end

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical, :text, :correction)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



483
484
485
486
487
488
489
490
491
 
# File 'lib/langfuse/client.rb', line 483

def score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  active_score_client&.score_active_trace(
    name: name,
    value: value,
    comment: comment,
    metadata: metadata,
    data_type: data_type
  )
end

#shutdown ⇒ void

This method returns an undefined value.

Shutdown the client and flush any pending scores

Also shuts down the cache if it supports shutdown (e.g., SWR thread pool).



510
511
512
513
 
# File 'lib/langfuse/client.rb', line 510

def shutdown
  @score_client&.shutdown
  @api_client_mutex.synchronize { @api_client }&.shutdown
end

#trace_url(trace_id) ⇒ String?

Generate URL for viewing a trace in Langfuse UI

Examples:

url = client.trace_url("abc123...")
puts "View trace at: #{url}"

Parameters:

  • trace_id (String) —

    The trace ID (hex-encoded, 32 characters)

Returns:

  • (String, nil) —

    URL to view the trace, or nil if project ID unavailable



326
327
328
 
# File 'lib/langfuse/client.rb', line 326

def trace_url(trace_id)
  project_url("traces/#{trace_id}")
end

#update_prompt(name:, version:, labels:) ⇒ TextPromptClient, ChatPromptClient

Update an existing prompt version's metadata

Updates the labels of an existing prompt version. Note: The prompt content itself cannot be changed after creation.

Examples:

Update labels to promote to production

prompt = client.update_prompt(
  name: "greeting",
  version: 2,
  labels: ["production"]
)

Parameters:

  • name (String) —

    The prompt name (required)

  • version (Integer) —

    The version number to update (required)

  • labels (Array<String>) —

    New labels (replaces existing). Required.

Returns:

Raises:



296
297
298
299
300
301
302
303
304
 
# File 'lib/langfuse/client.rb', line 296

def update_prompt(name:, version:, labels:)
  prompt_data = api_client.update_prompt(
    name: name,
    version: version,
    labels: labels
  )

  build_prompt_client(prompt_data)
end

#validate_prompt_cache_backend! ⇒ Object

Pure pass-throughs to ApiClient. See ApiClient for parameter and return-value documentation; the public surface here is identical.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/langfuse/client.rb', line 58

def_delegators :api_client,
:list_prompts,
:invalidate_prompt_cache,
:invalidate_prompt_cache_by_name,
:clear_prompt_cache,
:prompt_cache_stats,
:prompt_cache_key,
:validate_prompt_cache_backend!,
:list_traces,
:get_trace,
:list_observations,
:query_metrics,
:list_scores,
:list_datasets,
:get_dataset_run,
:create_dataset_run_item