Class: Langfuse::Client

Inherits:
Object
  • Object
show all
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



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/langfuse/client.rb', line 35

def initialize(config)
  @config = config
  @config.validate!

  # Create cache if enabled
  cache = create_cache if cache_enabled?

  # Create API client with cache
  @api_client = ApiClient.new(
    public_key: config.public_key,
    secret_key: config.secret_key,
    base_url: config.base_url,
    timeout: config.timeout,
    logger: config.logger,
    cache: cache,
    cache_observer: config.prompt_cache_observer
  )

  @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

  # Initialize score client for batching score events
  @score_client = ScoreClient.new(api_client: @api_client, config: config)
end

Instance Attribute Details

#api_client ⇒ ApiClient (readonly)

Returns The underlying API client.

Returns:



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

def api_client
  @api_client
end

#config ⇒ Config (readonly)

Returns The client configuration.

Returns:

  • (Config) —

    The client configuration



26
27
28
 
# File 'lib/langfuse/client.rb', line 26

def config
  @config
end

Instance Method Details

#clear_prompt_cache ⇒ Integer?

Logically clear the whole Langfuse prompt cache namespace.

Returns:

  • (Integer, nil) —

    New global generation, or nil when cache is disabled



158
159
160
 
# File 'lib/langfuse/client.rb', line 158

def clear_prompt_cache
  api_client.clear_prompt_cache
end

#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



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/langfuse/client.rb', line 245

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:



516
517
518
519
 
# File 'lib/langfuse/client.rb', line 516

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:



600
601
602
603
604
605
606
607
608
609
 
# File 'lib/langfuse/client.rb', line 600

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(dataset_item_id:, run_name:, trace_id: nil, observation_id: nil, metadata: nil, run_description: nil) ⇒ Hash

Create a dataset run item (link a trace to a dataset item)

Parameters:

  • dataset_item_id (String) —

    Dataset item ID (required)

  • run_name (String) —

    Run name (required)

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

    Trace ID

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

    Observation ID

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

    Optional metadata

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

    Optional run description

Returns:

  • (Hash) —

    The created dataset run item data



681
682
683
684
685
686
687
688
689
690
691
 
# File 'lib/langfuse/client.rb', line 681

def create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil,
                            observation_id: nil, metadata: nil, run_description: nil)
  api_client.create_dataset_run_item(
    dataset_item_id: dataset_item_id,
    run_name: run_name,
    trace_id: trace_id,
    observation_id: observation_id,
    metadata: metadata,
    run_description: run_description
  )
end

#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



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/langfuse/client.rb', line 297

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)

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

  • 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 environment

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

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

  • 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



412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/langfuse/client.rb', line 412

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)
  @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



382
383
384
 
# File 'lib/langfuse/client.rb', line 382

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



373
374
375
 
# File 'lib/langfuse/client.rb', line 373

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:



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

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:



733
734
735
736
 
# File 'lib/langfuse/client.rb', line 733

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


491
492
493
 
# File 'lib/langfuse/client.rb', line 491

def flush_scores
  @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:



531
532
533
534
 
# File 'lib/langfuse/client.rb', line 531

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:



622
623
624
625
 
# File 'lib/langfuse/client.rb', line 622

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:) ⇒ Hash

Fetch a dataset run by dataset and run name

Parameters:

  • dataset_name (String) —

    Dataset name (required)

  • run_name (String) —

    Run name (required)

Returns:

  • (Hash) —

    The dataset run data, including linked run items

Raises:



701
702
703
 
# File 'lib/langfuse/client.rb', line 701

def get_dataset_run(dataset_name:, run_name:)
  api_client.get_dataset_run(dataset_name: dataset_name, run_name: run_name)
end

#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



82
83
84
85
86
87
88
89
90
91
 
# File 'lib/langfuse/client.rb', line 82

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



106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/langfuse/client.rb', line 106

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) ⇒ Hash

Fetch a trace by ID

Examples:

trace = client.get_trace("trace-uuid-123")

Parameters:

  • id (String) —

    Trace ID

Returns:

  • (Hash) —

    The trace data

Raises:



575
576
577
 
# File 'lib/langfuse/client.rb', line 575

def get_trace(id)
  api_client.get_trace(id)
end

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

Invalidate one exact logical prompt cache key.

Parameters:

  • name (String) —

    The prompt name

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

    Optional specific version number

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

    Optional label

Returns:



143
144
145
 
# File 'lib/langfuse/client.rb', line 143

def invalidate_prompt_cache(name, version: nil, label: nil)
  api_client.invalidate_prompt_cache(name, version: version, label: label)
end

#invalidate_prompt_cache_by_name(name) ⇒ Integer?

Invalidate all cached variants for one prompt name.

Parameters:

  • name (String) —

    The prompt name

Returns:

  • (Integer, nil) —

    New generation, or nil when cache is disabled



151
152
153
 
# File 'lib/langfuse/client.rb', line 151

def invalidate_prompt_cache_by_name(name)
  api_client.invalidate_prompt_cache_by_name(name)
end

#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:



643
644
645
646
647
648
649
650
651
652
653
654
655
 
# File 'lib/langfuse/client.rb', line 643

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:



716
717
718
719
720
721
722
 
# File 'lib/langfuse/client.rb', line 716

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) ⇒ Array<Hash>

List all datasets in the project

Examples:

datasets = client.list_datasets(page: 1, limit: 10)

Parameters:

  • 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 metadata hashes

Raises:



546
547
548
 
# File 'lib/langfuse/client.rb', line 546

def list_datasets(page: nil, limit: nil)
  api_client.list_datasets(page: page, limit: limit)
end

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

List all prompts in the Langfuse project

Fetches a list of all prompt names available in your project. Returns metadata only, not full prompt content.

Examples:

prompts = client.list_prompts
prompts.each do |prompt|
  puts "#{prompt['name']} (v#{prompt['version']})"
end

Parameters:

  • 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 prompt metadata hashes

Raises:



206
207
208
 
# File 'lib/langfuse/client.rb', line 206

def list_prompts(page: nil, limit: nil)
  api_client.list_prompts(page: page, limit: limit)
end

#list_traces(page: nil, limit: nil, **filters) ⇒ Array<Hash>

List traces in the project

Examples:

traces = client.list_traces(page: 1, limit: 10, name: "my-trace")

Parameters:

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

    Optional page number for pagination

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

    Optional limit per page

  • filters (Hash) —

    Additional filters (user_id, name, session_id, etc.)

Returns:

  • (Array<Hash>) —

    Array of trace hashes

Raises:



561
562
563
 
# File 'lib/langfuse/client.rb', line 561

def list_traces(page: nil, limit: nil, **filters)
  api_client.list_traces(page: page, limit: limit, **filters)
end

#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



351
352
353
354
355
 
# File 'lib/langfuse/client.rb', line 351

def project_id
  return @project_id if @project_id_fetched

  fetch_project_id
end

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

Inspect the logical and generated cache keys for a prompt.

Parameters:

  • name (String) —

    The prompt name

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

    Optional specific version number

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

    Optional label

Returns:



175
176
177
 
# File 'lib/langfuse/client.rb', line 175

def prompt_cache_key(name, version: nil, label: nil)
  api_client.prompt_cache_key(name, version: version, label: label)
end

#prompt_cache_stats ⇒ Hash

Return prompt cache statistics.

Returns:

  • (Hash) —

    Cache statistics



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

def prompt_cache_stats
  api_client.prompt_cache_stats
end

#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



132
133
134
135
 
# File 'lib/langfuse/client.rb', line 132

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) 


756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
 
# File 'lib/langfuse/client.rb', line 756

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)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



447
448
449
450
451
452
453
454
455
 
# File 'lib/langfuse/client.rb', line 447

def score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  @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)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



473
474
475
476
477
478
479
480
481
 
# File 'lib/langfuse/client.rb', line 473

def score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  @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).



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

def shutdown
  @score_client.shutdown
  @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



365
366
367
 
# File 'lib/langfuse/client.rb', line 365

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:



335
336
337
338
339
340
341
342
343
 
# File 'lib/langfuse/client.rb', line 335

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! ⇒ Boolean

Validate the configured prompt cache backend before first prompt fetch.

rubocop:disable Naming/PredicateMethod

Returns:

  • (Boolean) —

    true when the configured backend is usable

Raises:



184
185
186
187
 
# File 'lib/langfuse/client.rb', line 184

def validate_prompt_cache_backend!
  api_client.cache&.validate! if api_client.cache.respond_to?(:validate!)
  true
end