Class: Phronomy::InvocationContext

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/invocation_context.rb

Overview

Carries all per-invocation context values through the call stack.

InvocationContext is a plain struct-like value carrier that replaces ad-hoc Thread.current[...] propagation. Pass it explicitly wherever context needs to cross a method boundary.

Examples:

Build a context for a new agent invocation

ctx = Phronomy::InvocationContext.new(
  thread_id: "conv-123",
  cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30)
)
agent.invoke("Hello", invocation_context: ctx)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(thread_id: nil, session_id: nil, user_id: nil, cancellation_token: nil, deadline: nil, tracer_span: nil, token_budget: nil, approval_policy: nil, redaction_policy: nil, task_id: nil, parent_task_id: nil) ⇒ InvocationContext

Returns a new instance of InvocationContext.

Parameters:

  • thread_id (String, nil) (defaults to: nil)
  • session_id (String, nil) (defaults to: nil)
  • user_id (String, nil) (defaults to: nil)
  • cancellation_token (CancellationToken, nil) (defaults to: nil)
  • deadline (Deadline, nil) (defaults to: nil)
  • tracer_span (Object, nil) (defaults to: nil)
  • token_budget (Integer, nil) (defaults to: nil)
  • approval_policy (#call, nil) (defaults to: nil)
  • redaction_policy (Object, nil) (defaults to: nil)
  • task_id (String, nil) (defaults to: nil)
  • parent_task_id (String, nil) (defaults to: nil) 


35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/phronomy/invocation_context.rb', line 35

def initialize(
  thread_id: nil,
  session_id: nil,
  user_id: nil,
  cancellation_token: nil,
  deadline: nil,
  tracer_span: nil,
  token_budget: nil,
  approval_policy: nil,
  redaction_policy: nil,
  task_id: nil,
  parent_task_id: nil
)
  @thread_id = thread_id
  @session_id = session_id
  @user_id = user_id
  @cancellation_token = cancellation_token
  @deadline = deadline
  @tracer_span = tracer_span
  @token_budget = token_budget
  @approval_policy = approval_policy
  @redaction_policy = redaction_policy
  @task_id = task_id
  @parent_task_id = parent_task_id
end

Instance Attribute Details

#approval_policy ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def approval_policy
  @approval_policy
end

#cancellation_token ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def cancellation_token
  @cancellation_token
end

#deadline ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def deadline
  @deadline
end

#parent_task_id ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def parent_task_id
  @parent_task_id
end

#redaction_policy ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def redaction_policy
  @redaction_policy
end

#session_id ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def session_id
  @session_id
end

#task_id ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def task_id
  @task_id
end

#thread_id ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def thread_id
  @thread_id
end

#token_budget ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def token_budget
  @token_budget
end

#tracer_span ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def tracer_span
  @tracer_span
end

#user_id ⇒ Object (readonly) 



19
20
21
 
# File 'lib/phronomy/invocation_context.rb', line 19

def user_id
  @user_id
end

Instance Method Details

#effective_cancellation_token ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Convenience: returns the cancellation token or a new never-cancelled token.



81
82
83
 
# File 'lib/phronomy/invocation_context.rb', line 81

def effective_cancellation_token
  @cancellation_token || Phronomy::Concurrency::CancellationToken.new
end

#effective_timeout_token ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the cancellation token to use for an invocation, taking both the explicit cancellation_token and deadline into account.



88
89
90
91
92
93
94
95
 
# File 'lib/phronomy/invocation_context.rb', line 88

def effective_timeout_token
  return @cancellation_token if @cancellation_token
  return nil if @deadline.nil?

  token = Phronomy::Concurrency::CancellationToken.new
  @deadline.attach_to(token)
  token
end

#merge(**overrides) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new InvocationContext with the given attributes merged in.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/phronomy/invocation_context.rb', line 63

def merge(**overrides)
  InvocationContext.new(
    thread_id: overrides.fetch(:thread_id, @thread_id),
    session_id: overrides.fetch(:session_id, @session_id),
    user_id: overrides.fetch(:user_id, @user_id),
    cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
    deadline: overrides.fetch(:deadline, @deadline),
    tracer_span: overrides.fetch(:tracer_span, @tracer_span),
    token_budget: overrides.fetch(:token_budget, @token_budget),
    approval_policy: overrides.fetch(:approval_policy, @approval_policy),
    redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
    task_id: overrides.fetch(:task_id, @task_id),
    parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
  )
end