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



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/langfuse/client.rb', line 68

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:



33
34
35
 
# File 'lib/langfuse/client.rb', line 33

def api_client
  @api_client
end

#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

#clear_prompt_cache ⇒ Object

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



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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



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

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:



476
477
478
479
 
# File 'lib/langfuse/client.rb', line 476

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:



517
518
519
520
521
522
523
524
525
526
 
# File 'lib/langfuse/client.rb', line 517

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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



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

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



372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/langfuse/client.rb', line 372

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



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

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



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

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:



584
585
586
587
 
# File 'lib/langfuse/client.rb', line 584

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:



617
618
619
620
 
# File 'lib/langfuse/client.rb', line 617

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


451
452
453
 
# File 'lib/langfuse/client.rb', line 451

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:



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

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:



539
540
541
542
 
# File 'lib/langfuse/client.rb', line 539

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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



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

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



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

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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



560
561
562
563
564
565
566
567
568
569
570
571
572
 
# File 'lib/langfuse/client.rb', line 560

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:



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

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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



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

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_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



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

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) 


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

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



407
408
409
410
411
412
413
414
415
 
# File 'lib/langfuse/client.rb', line 407

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



433
434
435
436
437
438
439
440
441
 
# File 'lib/langfuse/client.rb', line 433

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



460
461
462
463
 
# File 'lib/langfuse/client.rb', line 460

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



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

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:



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

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/langfuse/client.rb', line 50

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_datasets,
:get_dataset_run,
:create_dataset_run_item