Class: Langfuse::DatasetClient

Inherits:
Object
  • Object
show all
Includes:
TimestampParser
Defined in:
lib/langfuse/dataset_client.rb

Overview

Client wrapper for a Langfuse dataset

Provides read access to dataset fields and the ability to run experiments against the dataset’s items. Returned by Client#get_dataset and Client#create_dataset.

Examples:

Fetching and iterating items

dataset = client.get_dataset("qa-pairs")
dataset.items.each { |item| puts item.input }

Running an experiment

dataset.run_experiment(name: "v1", task: ->(item) { llm_call(item.input) })

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(dataset_data, client: nil) ⇒ DatasetClient

Initialize a new dataset client from API response data

Parameters:

  • dataset_data (Hash) —

    Raw dataset data from the API (string keys)

  • client (Client, nil) (defaults to: nil) —

    Langfuse client for API operations

Raises:

  • (ArgumentError) —

    if dataset_data is not a Hash or missing required fields



43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/langfuse/dataset_client.rb', line 43

def initialize(dataset_data, client: nil)
  validate_dataset_data!(dataset_data)
  @id = dataset_data["id"]
  @name = dataset_data["name"]
  @description = dataset_data["description"]
  @metadata = dataset_data["metadata"] || {}
  @created_at = parse_timestamp(dataset_data["createdAt"])
  @updated_at = parse_timestamp(dataset_data["updatedAt"])
  @raw_items = dataset_data["items"] || []
  @client = client
end

Instance Attribute Details

#created_at ⇒ Time? (readonly)

Returns Timestamp when the dataset was created.

Returns:

  • (Time, nil) —

    Timestamp when the dataset was created



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

def created_at
  @created_at
end

#description ⇒ String? (readonly)

Returns Optional description of the dataset.

Returns:

  • (String, nil) —

    Optional description of the dataset



27
28
29
 
# File 'lib/langfuse/dataset_client.rb', line 27

def description
  @description
end

#id ⇒ String (readonly)

Returns Unique identifier for the dataset.

Returns:

  • (String) —

    Unique identifier for the dataset



21
22
23
 
# File 'lib/langfuse/dataset_client.rb', line 21

def id
  @id
end

#metadata ⇒ Hash (readonly)

Returns Additional metadata as key-value pairs.

Returns:

  • (Hash) —

    Additional metadata as key-value pairs



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

def metadata
  @metadata
end

#name ⇒ String (readonly)

Returns Human-readable name of the dataset.

Returns:

  • (String) —

    Human-readable name of the dataset



24
25
26
 
# File 'lib/langfuse/dataset_client.rb', line 24

def name
  @name
end

#updated_at ⇒ Time? (readonly)

Returns Timestamp when the dataset was last updated.

Returns:

  • (Time, nil) —

    Timestamp when the dataset was last updated



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

def updated_at
  @updated_at
end

Instance Method Details

#items ⇒ Array<DatasetItemClient>

Lazily-parsed dataset items

Returns:



58
59
60
61
62
63
64
 
# File 'lib/langfuse/dataset_client.rb', line 58

def items
  @items ||= if @raw_items.empty? && @client
               @client.list_dataset_items(dataset_name: @name)
             else
               @raw_items.map { |item_data| DatasetItemClient.new(item_data, client: @client) }
             end
end

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

Run an experiment against all items in this dataset

rubocop:disable Metrics/ParameterLists

Parameters:

  • name (String) —

    experiment/run name (required)

  • task (Proc) —

    callable receiving a Langfuse::DatasetItemClient, returning output

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

    optional run description

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

    item-level evaluators returning Evaluation or Array<Evaluation>

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

    run-level evaluators receiving all item results and returning Evaluation or Array<Evaluation>

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

    metadata attached to each trace

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

    explicit run name (defaults to “name - timestamp”)

Returns:

Raises:

  • (ArgumentError) —

    if client was not provided at initialization



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/langfuse/dataset_client.rb', line 88

def run_experiment(name:, task:, description: nil, evaluators: [], run_evaluators: [],
                   metadata: nil, run_name: nil)
  raise ArgumentError, "client is required for this operation" unless @client

  @client.run_experiment(
    name: name,
    data: items,
    task: task,
    evaluators: evaluators,
    run_evaluators: run_evaluators,
    metadata: metadata,
    description: description,
    run_name: run_name
  )
end

#url ⇒ String?

Generate URL for viewing this dataset in Langfuse UI

Returns:

  • (String, nil) —

    URL to view the dataset, or nil if client unavailable



69
70
71
72
73
 
# File 'lib/langfuse/dataset_client.rb', line 69

def url
  return nil unless @client

  @client.dataset_url(@id)
end