Class: Langsmith::Run

Inherits:
Object
  • Object
show all
Defined in:
lib/langsmith/run.rb

Overview

Represents a single trace run/span in LangSmith. All run types (chain, llm, tool, etc.) use this same class with different run_type values.

Examples:

Creating a run

run = Langsmith::Run.new(name: "my_operation", run_type: "chain")
run.add_metadata(user_id: "123")
run.finish(outputs: { result: "success" })

Constant Summary collapse

VALID_RUN_TYPES =

Valid run types supported by LangSmith

%w[chain llm tool retriever prompt parser].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, run_type: "chain", inputs: nil, parent_run_id: nil, session_name: nil, metadata: nil, tags: nil, extra: nil, id: nil, tenant_id: nil, trace_id: nil, parent_dotted_order: nil, reference_example_id: nil, session_id: nil) ⇒ Run

Creates a new Run instance.

Parameters:

  • name (String) —

    name of the operation

  • run_type (String) (defaults to: "chain") —

    type of run ("chain", "llm", "tool", etc.)

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

    input data

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

    parent run ID for nested traces

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

    project/session name

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

    additional metadata

  • tags (Array<String>, nil) (defaults to: nil) —

    tags for filtering

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

    extra data

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

    custom ID (auto-generated if not provided)

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

    tenant ID for multi-tenant scenarios

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

    trace ID (defaults to own ID for root runs)

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

    parent's dotted order for tree ordering

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

    dataset example ID (for evaluations)

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

    experiment session ID (overrides project routing)

Raises:

  • (ArgumentError) —

    if run_type is invalid



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/langsmith/run.rb', line 94

def initialize(
  name:,
  run_type: "chain",
  inputs: nil,
  parent_run_id: nil,
  session_name: nil,
  metadata: nil,
  tags: nil,
  extra: nil,
  id: nil,
  tenant_id: nil,
  trace_id: nil,
  parent_dotted_order: nil,
  reference_example_id: nil,
  session_id: nil
)
  @id = id || SecureRandom.uuid
  @name = name
  @run_type = validate_run_type(run_type)
  @inputs = inputs || {}
  @outputs = nil
  @error = nil
  @parent_run_id = parent_run_id
  @session_name = session_name || Langsmith.configuration.project
  @tenant_id = tenant_id || Langsmith.configuration.tenant_id
  # trace_id is the root run's ID; for root runs it equals the run's own ID
  @trace_id = trace_id || @id
  @start_time = Time.now.utc
  @end_time = nil
  @metadata = metadata || {}
  @tags = tags || []
  @extra = extra || {}
  @events = []
  @reference_example_id = reference_example_id
  @session_id = session_id
  # dotted_order is used for ordering runs in the trace tree
  @dotted_order = build_dotted_order(parent_dotted_order)
end

Instance Attribute Details

#dotted_order ⇒ String (readonly)

Returns dotted order for trace tree ordering.

Returns:

  • (String) —

    dotted order for trace tree ordering



50
51
52
 
# File 'lib/langsmith/run.rb', line 50

def dotted_order
  @dotted_order
end

#end_time ⇒ Time?

Returns when the run ended.

Returns:

  • (Time, nil) —

    when the run ended



62
63
64
 
# File 'lib/langsmith/run.rb', line 62

def end_time
  @end_time
end

#error ⇒ String?

Returns error message if run failed.

Returns:

  • (String, nil) —

    error message if run failed



59
60
61
 
# File 'lib/langsmith/run.rb', line 59

def error
  @error
end

#events ⇒ Array<Hash>

Returns events that occurred during the run.

Returns:

  • (Array<Hash>) —

    events that occurred during the run



71
72
73
 
# File 'lib/langsmith/run.rb', line 71

def events
  @events
end

#extra ⇒ Hash

Returns extra data (e.g., token usage).

Returns:

  • (Hash) —

    extra data (e.g., token usage)



68
69
70
 
# File 'lib/langsmith/run.rb', line 68

def extra
  @extra
end

#id ⇒ String (readonly)

Returns unique identifier for this run.

Returns:

  • (String) —

    unique identifier for this run



20
21
22
 
# File 'lib/langsmith/run.rb', line 20

def id
  @id
end

#inputs ⇒ Hash

Returns input data.

Returns:

  • (Hash) —

    input data



53
54
55
 
# File 'lib/langsmith/run.rb', line 53

def inputs
  @inputs
end

#metadata ⇒ Hash

Returns additional metadata.

Returns:

  • (Hash) —

    additional metadata



65
66
67
 
# File 'lib/langsmith/run.rb', line 65

def metadata
  @metadata
end

#name ⇒ String (readonly)

Returns name of the operation.

Returns:

  • (String) —

    name of the operation



23
24
25
 
# File 'lib/langsmith/run.rb', line 23

def name
  @name
end

#outputs ⇒ Hash?

Returns output data.

Returns:

  • (Hash, nil) —

    output data



56
57
58
 
# File 'lib/langsmith/run.rb', line 56

def outputs
  @outputs
end

#parent_run_id ⇒ String? (readonly)

Returns parent run ID for nested traces.

Returns:

  • (String, nil) —

    parent run ID for nested traces



29
30
31
 
# File 'lib/langsmith/run.rb', line 29

def parent_run_id
  @parent_run_id
end

#reference_example_id ⇒ String? (readonly)

Returns links this run to a dataset example (for evaluations).

Returns:

  • (String, nil) —

    links this run to a dataset example (for evaluations)



41
42
43
 
# File 'lib/langsmith/run.rb', line 41

def reference_example_id
  @reference_example_id
end

#run_type ⇒ String (readonly)

Returns type of run (chain, llm, tool, etc.).

Returns:

  • (String) —

    type of run (chain, llm, tool, etc.)



26
27
28
 
# File 'lib/langsmith/run.rb', line 26

def run_type
  @run_type
end

#session_id ⇒ String? (readonly)

Returns links this run to an experiment session (overrides project routing).

Returns:

  • (String, nil) —

    links this run to an experiment session (overrides project routing)



44
45
46
 
# File 'lib/langsmith/run.rb', line 44

def session_id
  @session_id
end

#session_name ⇒ String (readonly)

Returns project/session name.

Returns:

  • (String) —

    project/session name



32
33
34
 
# File 'lib/langsmith/run.rb', line 32

def session_name
  @session_name
end

#start_time ⇒ Time (readonly)

Returns when the run started.

Returns:

  • (Time) —

    when the run started



35
36
37
 
# File 'lib/langsmith/run.rb', line 35

def start_time
  @start_time
end

#tags ⇒ Array<String>

Returns tags for filtering.

Returns:

  • (Array<String>) —

    tags for filtering



74
75
76
 
# File 'lib/langsmith/run.rb', line 74

def tags
  @tags
end

#tenant_id ⇒ String? (readonly)

Returns tenant ID for multi-tenant scenarios.

Returns:

  • (String, nil) —

    tenant ID for multi-tenant scenarios



38
39
40
 
# File 'lib/langsmith/run.rb', line 38

def tenant_id
  @tenant_id
end

#trace_id ⇒ String (readonly)

Returns trace ID (root run's ID).

Returns:

  • (String) —

    trace ID (root run's ID)



47
48
49
 
# File 'lib/langsmith/run.rb', line 47

def trace_id
  @trace_id
end

Instance Method Details

#add_event(name:, time: nil, **kwargs) ⇒ nil

Adds an event to the run.

Parameters:

  • name (String) —

    event name

  • time (Time, nil) (defaults to: nil) —

    event time (defaults to now)

  • kwargs (Hash) —

    additional event data

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



169
170
171
172
173
174
175
176
 
# File 'lib/langsmith/run.rb', line 169

def add_event(name:, time: nil, **kwargs)
  @events << {
    name: name,
    time: (time || Time.now.utc).iso8601(3),
    **kwargs
  }
  nil
end

#add_metadata(new_metadata) ⇒ nil

Adds metadata to the run.

Parameters:

  • new_metadata (Hash) —

    metadata to merge

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



149
150
151
152
 
# File 'lib/langsmith/run.rb', line 149

def add_metadata(new_metadata)
  @metadata.merge!(new_metadata)
  nil
end

#add_tags(*new_tags) ⇒ nil

Adds tags to the run.

Parameters:

  • new_tags (Array<String>) —

    tags to add

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



158
159
160
161
 
# File 'lib/langsmith/run.rb', line 158

def add_tags(*new_tags)
  @tags.concat(new_tags.flatten)
  nil
end

#duration_ms ⇒ Float?

Returns the duration in milliseconds.

Returns:

  • (Float, nil) —

    duration in ms, or nil if not finished



238
239
240
241
242
 
# File 'lib/langsmith/run.rb', line 238

def duration_ms
  return nil unless end_time

  ((end_time - start_time) * 1000).round(2)
end

#finish(outputs: nil, error: nil) ⇒ self

Marks the run as finished.

Parameters:

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

    output data

  • error (Exception, String, nil) (defaults to: nil) —

    error if the run failed

Returns:

  • (self) 


138
139
140
141
142
143
 
# File 'lib/langsmith/run.rb', line 138

def finish(outputs: nil, error: nil)
  @end_time = Time.now.utc
  @outputs = outputs if outputs
  @error = format_error(error) if error
  self
end

#finished? ⇒ Boolean

Returns whether the run has finished.

Returns:

  • (Boolean) 


232
233
234
 
# File 'lib/langsmith/run.rb', line 232

def finished?
  !end_time.nil?
end

#set_model(model:, provider: nil) ⇒ nil

Sets LLM model metadata. The model name should be stored in extra.metadata for LangSmith to display it.

Parameters:

  • model (String) —

    the model name/identifier

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

    the model provider (e.g., "openai", "anthropic")

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



205
206
207
208
209
210
 
# File 'lib/langsmith/run.rb', line 205

def set_model(model:, provider: nil)
  @extra[:metadata] ||= {}
  @extra[:metadata][:ls_model_name] = model
  @extra[:metadata][:ls_provider] = provider if provider
  nil
end

#set_streaming_metrics(time_to_first_token: nil, chunk_count: nil, tokens_per_second: nil) ⇒ nil

Sets streaming metrics for LLM runs. Useful for tracking performance of streaming responses.

Parameters:

  • time_to_first_token (Float, nil) (defaults to: nil) —

    time in seconds until first token received

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

    total number of chunks received

  • tokens_per_second (Float, nil) (defaults to: nil) —

    throughput in tokens per second

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



219
220
221
222
223
224
225
226
227
228
 
# File 'lib/langsmith/run.rb', line 219

def set_streaming_metrics(time_to_first_token: nil, chunk_count: nil, tokens_per_second: nil)
  @extra[:metadata] ||= {}
  @extra[:metadata][:streaming_metrics] = {
    time_to_first_token_s: time_to_first_token,
    chunk_count: chunk_count,
    tokens_per_second: tokens_per_second
  }.compact

  nil
end

#set_token_usage(input_tokens: nil, output_tokens: nil, total_tokens: nil) ⇒ nil

Sets token usage for LLM runs. Follows the Python SDK pattern: tokens are stored in extra.metadata.usage_metadata with keys: input_tokens, output_tokens, total_tokens

Parameters:

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

    number of input/prompt tokens

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

    number of output/completion tokens

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

    total tokens (calculated if not provided)

Returns:

  • (nil) —

    returns nil to prevent circular reference when used as last line



186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/langsmith/run.rb', line 186

def set_token_usage(input_tokens: nil, output_tokens: nil, total_tokens: nil)
  calculated_total = total_tokens || ((input_tokens || 0) + (output_tokens || 0))

  @extra[:metadata] ||= {}
  @extra[:metadata][:usage_metadata] = {
    input_tokens: input_tokens,
    output_tokens: output_tokens,
    total_tokens: calculated_total
  }.compact

  nil # Return nil to prevent circular reference if used as last line of trace block
end

#to_h ⇒ Hash

Convert to hash for JSON serialization to LangSmith API (full run for POST). Token usage is stored in extra.metadata.usage_metadata following Python SDK pattern.

Returns:

  • (Hash) 


248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/langsmith/run.rb', line 248

def to_h
  {
    id:,
    name:,
    run_type:,
    inputs:,
    outputs:,
    error:,
    parent_run_id:,
    reference_example_id:,
    session_id:,
    trace_id:,
    dotted_order:,
    session_name:,
    start_time: start_time.iso8601(3),
    end_time: end_time&.iso8601(3),
    extra: extra.empty? ? nil : extra,
    events: events.empty? ? nil : events,
    tags: tags.empty? ? nil : tags,
    serialized: { name: },
    **(metadata.empty? ? {} : { metadata: })
  }.compact
end

#to_json(*args) ⇒ String

Convert to JSON string.

Returns:

  • (String) 


297
298
299
 
# File 'lib/langsmith/run.rb', line 297

def to_json(*args)
  to_h.to_json(*args)
end

#to_update_h ⇒ Hash

Convert to hash for PATCH requests (only fields that change on completion). Note: parent_run_id is required for LangSmith to validate dotted_order correctly. Token usage is included in extra.metadata.usage_metadata. Metadata and tags are included as they may be added during execution.

Returns:

  • (Hash) 


278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/langsmith/run.rb', line 278

def to_update_h
  {
    id:,
    trace_id:,
    parent_run_id:,
    dotted_order:,
    end_time: end_time&.iso8601(3),
    outputs:,
    error:,
    events: events.empty? ? nil : events,
    extra: extra.empty? ? nil : extra,
    tags: tags.empty? ? nil : tags,
    **(metadata.empty? ? {} : { metadata: })
  }.compact
end