Module: Langsmith::Context

Defined in:
lib/langsmith/context.rb

Overview

Thread-local context manager for maintaining the current trace stack. This allows nested traces to automatically link to their parent runs.

Each thread maintains its own trace stack, ensuring proper isolation in concurrent environments.

Note: We use Thread.current instead of Fiber.storage for compatibility across Ruby versions. Fiber.storage behavior differs between Ruby versions and caused test failures on Ruby 3.2.

Class Method Summary collapse

Class Method Details

.active? ⇒ Boolean

Check if there's an active trace context

Returns:

  • (Boolean) 


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

def active?
  !run_stack.empty?
end

.clear! ⇒ Object

Clear the entire run stack and evaluation context (useful for testing)



57
58
59
60
61
62
 
# File 'lib/langsmith/context.rb', line 57

def clear!
  Thread.current[CONTEXT_KEY] = []
  Thread.current[EVALUATION_CONTEXT_KEY] = nil
  Thread.current[EVALUATION_ROOT_RUN_ID_KEY] = nil
  Thread.current[EVALUATION_ROOT_RUN_TENANT_ID_KEY] = nil
end

.current_parent_run_id ⇒ Object

Returns the current parent run ID for creating child runs



33
34
35
 
# File 'lib/langsmith/context.rb', line 33

def current_parent_run_id
  current_run&.id
end

.current_run ⇒ Object

Returns the current (topmost) run, or nil if no active trace



28
29
30
 
# File 'lib/langsmith/context.rb', line 28

def current_run
  run_stack.last
end

.depth ⇒ Object

Get the depth of the current trace (0 = root level)



70
71
72
 
# File 'lib/langsmith/context.rb', line 70

def depth
  run_stack.size
end

.evaluating? ⇒ Boolean

Returns true when evaluation context is set.

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/langsmith/context.rb', line 87

def evaluating?
  !evaluation_context.nil?
end

.evaluation_context ⇒ Hash?

Returns the current evaluation context, or nil when not in evaluation.

Returns:

  • (Hash, nil) —

    hash with :experiment_id and :example_id, or nil



81
82
83
 
# File 'lib/langsmith/context.rb', line 81

def evaluation_context
  Thread.current[EVALUATION_CONTEXT_KEY]
end

.evaluation_root_run_id ⇒ String?

Returns the root run ID for the current evaluation example, or nil.

Returns:

  • (String, nil) 


101
102
103
 
# File 'lib/langsmith/context.rb', line 101

def evaluation_root_run_id
  Thread.current[EVALUATION_ROOT_RUN_ID_KEY]
end

.evaluation_root_run_tenant_id ⇒ String?

Returns the root run tenant ID for the current evaluation example, or nil.

Returns:

  • (String, nil) 


114
115
116
 
# File 'lib/langsmith/context.rb', line 114

def evaluation_root_run_tenant_id
  Thread.current[EVALUATION_ROOT_RUN_TENANT_ID_KEY]
end

.pop ⇒ Object

Pop a run from the context stack



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

def pop
  run_stack.pop
end

.push(run) ⇒ Object

Push a run onto the context stack



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

def push(run)
  run_stack.push(run)
  run
end

.root_run ⇒ Object

Get the root run of the current trace tree



75
76
77
 
# File 'lib/langsmith/context.rb', line 75

def root_run
  run_stack.first
end

.run_stack ⇒ Object

Returns the current run stack for this thread.



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

def run_stack
  Thread.current[CONTEXT_KEY] ||= []
end

.set_evaluation_root_run_id(run_id) ⇒ Object

Stores the root run ID for the current evaluation example. Called by RunTree when creating the first root run inside an evaluation block.

Parameters:

  • run_id (String) —

    the root run's ID



95
96
97
 
# File 'lib/langsmith/context.rb', line 95

def set_evaluation_root_run_id(run_id)
  Thread.current[EVALUATION_ROOT_RUN_ID_KEY] = run_id
end

.set_evaluation_root_run_tenant_id(tenant_id) ⇒ Object

Stores the root run tenant ID for the current evaluation example.

Parameters:

  • tenant_id (String, nil) —

    the root run's tenant ID



108
109
110
 
# File 'lib/langsmith/context.rb', line 108

def set_evaluation_root_run_tenant_id(tenant_id)
  Thread.current[EVALUATION_ROOT_RUN_TENANT_ID_KEY] = tenant_id
end

.with_evaluation(experiment_id:, example_id:) ⇒ Object

Execute a block with evaluation context set. Context is cleared in ensure block even if the block raises.

Parameters:

  • experiment_id (String) —

    the experiment session ID

  • example_id (String) —

    the dataset example ID



123
124
125
126
127
128
129
130
 
# File 'lib/langsmith/context.rb', line 123

def with_evaluation(experiment_id:, example_id:)
  Thread.current[EVALUATION_CONTEXT_KEY] = { experiment_id: experiment_id, example_id: example_id }
  yield
ensure
  Thread.current[EVALUATION_CONTEXT_KEY] = nil
  Thread.current[EVALUATION_ROOT_RUN_ID_KEY] = nil
  Thread.current[EVALUATION_ROOT_RUN_TENANT_ID_KEY] = nil
end

.with_run(run) ⇒ Object

Execute a block with a run pushed onto the stack



49
50
51
52
53
54
 
# File 'lib/langsmith/context.rb', line 49

def with_run(run)
  push(run)
  yield run
ensure
  pop
end