Class: Langfuse::DatasetItemClient

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

Overview

Client wrapper for a single Langfuse dataset item

Provides read access to item fields and operations to link items to traces or run tasks within a traced context. Returned by Client#get_dataset_item, Client#create_dataset_item, and Langfuse::DatasetClient#items.

Examples:

Linking to an existing trace

item.link(trace_id: "abc123", run_name: "eval-v1")

Running a task with auto-linking

item.run(run_name: "eval-v1") do |span|
  my_llm_call(item.input)
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(item_data, client: nil) ⇒ DatasetItemClient

Initialize a new dataset item client from API response data

Parameters:

  • item_data (Hash) —

    Raw item data from the API (string keys)

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

    Langfuse client for API operations

Raises:

  • (ArgumentError) —

    if item_data is not a Hash or missing required fields



56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/langfuse/dataset_item_client.rb', line 56

def initialize(item_data, client: nil)
  validate_item_data!(item_data)
  @id = item_data["id"]
  @dataset_id = item_data["datasetId"]
  @input = item_data["input"]
  @expected_output = item_data["expectedOutput"]
  @metadata = item_data["metadata"] || {}
  @source_trace_id = item_data["sourceTraceId"]
  @source_observation_id = item_data["sourceObservationId"]
  @status = item_data["status"] || "ACTIVE"
  @created_at = parse_timestamp(item_data["createdAt"])
  @updated_at = parse_timestamp(item_data["updatedAt"])
  @client = client
end

Instance Attribute Details

#created_at ⇒ Time? (readonly)

Returns Timestamp when the item was created.

Returns:

  • (Time, nil) —

    Timestamp when the item was created



46
47
48
 
# File 'lib/langfuse/dataset_item_client.rb', line 46

def created_at
  @created_at
end

#dataset_id ⇒ String (readonly)

Returns Identifier of the parent dataset.

Returns:

  • (String) —

    Identifier of the parent dataset



25
26
27
 
# File 'lib/langfuse/dataset_item_client.rb', line 25

def dataset_id
  @dataset_id
end

#expected_output ⇒ Object? (readonly)

Returns Expected output for evaluation.

Returns:

  • (Object, nil) —

    Expected output for evaluation



31
32
33
 
# File 'lib/langfuse/dataset_item_client.rb', line 31

def expected_output
  @expected_output
end

#id ⇒ String (readonly)

Returns Unique identifier for the dataset item.

Returns:

  • (String) —

    Unique identifier for the dataset item



22
23
24
 
# File 'lib/langfuse/dataset_item_client.rb', line 22

def id
  @id
end

#input ⇒ Object? (readonly)

Returns Input data for the dataset item.

Returns:

  • (Object, nil) —

    Input data for the dataset item



28
29
30
 
# File 'lib/langfuse/dataset_item_client.rb', line 28

def input
  @input
end

#metadata ⇒ Hash (readonly)

Returns Additional metadata as key-value pairs.

Returns:

  • (Hash) —

    Additional metadata as key-value pairs



34
35
36
 
# File 'lib/langfuse/dataset_item_client.rb', line 34

def metadata
  @metadata
end

#source_observation_id ⇒ String? (readonly)

Returns Observation ID that produced this item.

Returns:

  • (String, nil) —

    Observation ID that produced this item



40
41
42
 
# File 'lib/langfuse/dataset_item_client.rb', line 40

def source_observation_id
  @source_observation_id
end

#source_trace_id ⇒ String? (readonly)

Returns Trace ID that produced this item.

Returns:

  • (String, nil) —

    Trace ID that produced this item



37
38
39
 
# File 'lib/langfuse/dataset_item_client.rb', line 37

def source_trace_id
  @source_trace_id
end

#status ⇒ String (readonly)

Returns Item status (ACTIVE or ARCHIVED).

Returns:

  • (String) —

    Item status (ACTIVE or ARCHIVED)



43
44
45
 
# File 'lib/langfuse/dataset_item_client.rb', line 43

def status
  @status
end

#updated_at ⇒ Time? (readonly)

Returns Timestamp when the item was last updated.

Returns:

  • (Time, nil) —

    Timestamp when the item was last updated



49
50
51
 
# File 'lib/langfuse/dataset_item_client.rb', line 49

def updated_at
  @updated_at
end

Instance Method Details

#active? ⇒ Boolean

Returns true if the item is active.

Returns:

  • (Boolean) —

    true if the item is active



72
 
# File 'lib/langfuse/dataset_item_client.rb', line 72

def active? = status == "ACTIVE"

#archived? ⇒ Boolean

Returns true if the item is archived.

Returns:

  • (Boolean) —

    true if the item is archived



75
 
# File 'lib/langfuse/dataset_item_client.rb', line 75

def archived? = status == "ARCHIVED"

#link(trace_id:, run_name:, observation_id: nil, metadata: nil, run_description: nil) ⇒ Hash

Link this dataset item to a trace within a named run

Parameters:

  • trace_id (String) —

    trace ID to link

  • run_name (String) —

    run name for grouping

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

    optional 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

Raises:

  • (ArgumentError) —

    if client was not provided at initialization



86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/langfuse/dataset_item_client.rb', line 86

def link(trace_id:, run_name:, observation_id: nil, metadata: nil, run_description: nil)
  require_client!
  @client.create_dataset_run_item(
    dataset_item_id: @id,
    run_name: run_name,
    trace_id: trace_id,
    observation_id: observation_id,
    metadata: metadata,
    run_description: run_description
  )
end

#run(run_name:, run_description: nil, run_metadata: nil) {|span| ... } ⇒ Object

Run a block within a traced context and auto-link to this dataset item

Lower-level alternative to Client#run_experiment for single-item execution with direct span access. Matches Python SDK’s ‘item.run()` context manager pattern.

Executes the block inside an observed span, flushes the trace, then creates a dataset run item linking this item to the resulting trace.

Parameters:

  • run_name (String) —

    run name for grouping

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

    optional run description

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

    optional metadata for the trace

Yields:

  • (span) —

    block executed within the traced context

Yield Parameters:

Returns:

  • (Object) —

    the block’s return value

Raises:

  • (ArgumentError) —

    if client was not provided or block is missing

  • (StandardError) —

    re-raises any error from the block after flushing and linking



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

def run(run_name:, run_description: nil, run_metadata: nil, &block)
  require_client!
  raise ArgumentError, "block is required" unless block

  output, trace_id, observation_id, task_error = execute_in_trace(run_name, run_metadata, &block)
  Langfuse.force_flush(timeout: FLUSH_TIMEOUT)

  link(trace_id: trace_id, observation_id: observation_id, run_name: run_name,
       run_description: run_description, metadata: run_metadata)
  raise task_error if task_error

  output
end