Class: Phronomy::Configuration

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

Overview

Holds global configuration for the entire framework. Configure via the Phronomy.configure block.

Examples:

Phronomy.configure do |config|
  config.default_model    = "claude-3-5-sonnet-20241022"
  config.recursion_limit  = 50
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/phronomy/configuration.rb', line 191

def initialize
  @recursion_limit = 25
  @tracer = Phronomy::Tracing::NullTracer.new
  @trace_pii = false
  @parallel_tool_execution = false
  @event_loop_stop_grace_seconds = 5
  @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
  @backpressure = :wait
  @backpressure_timeout = nil
  @event_loop_starvation_threshold_seconds = nil
  @event_loop_dispatch_threshold_seconds = nil
  @scheduler_debug = false
  @blocking_detect_threshold_ms = nil
  @max_concurrent_agent_tasks = nil
  @max_concurrent_tool_tasks = nil
  @max_concurrent_workflow_tasks = nil
  @max_concurrent_llm_calls = nil
  @stream_queue_max_size = nil
  @max_concurrent_vector_searches = nil
  @starvation_threshold_ms = 50
  @runtime_backend = :thread
  @strict_runtime_guards = false
end

Instance Attribute Details

#backpressure ⇒ :wait, ...

Default backpressure strategy for BlockingAdapterPool#submit when the queue is full. One of :wait (block until a slot is available), :raise (raise BackpressureError), or :timeout (raise TimeoutError after backpressure_timeout seconds).

Returns:

  • (:wait, :raise, :timeout) 


94
95
96
 
# File 'lib/phronomy/configuration.rb', line 94

def backpressure
  @backpressure
end

#backpressure_timeout ⇒ Numeric?

Seconds to wait before raising TimeoutError when backpressure is :timeout.

Returns:

  • (Numeric, nil) 


99
100
101
 
# File 'lib/phronomy/configuration.rb', line 99

def backpressure_timeout
  @backpressure_timeout
end

#before_completion ⇒ Object

Global before_completion hook callable (Proc / lambda). Called before every LLM request across all agents. Receives a Agent::BeforeCompletionContext; must return a Hash of params to merge, or nil to pass through unchanged.



26
27
28
 
# File 'lib/phronomy/configuration.rb', line 26

def before_completion
  @before_completion
end

#blocking_detect_threshold_ms ⇒ Float?

Wall-clock threshold (milliseconds) after which a task that has not yielded the scheduler emits a warning log. nil disables the check.

Returns:

  • (Float, nil) 


121
122
123
 
# File 'lib/phronomy/configuration.rb', line 121

def blocking_detect_threshold_ms
  @blocking_detect_threshold_ms
end

#default_embedding_model ⇒ Object

Default embedding model name



17
18
19
 
# File 'lib/phronomy/configuration.rb', line 17

def default_embedding_model
  @default_embedding_model
end

#default_model ⇒ Object

Default LLM model name (nil delegates to RubyLLM default)



14
15
16
 
# File 'lib/phronomy/configuration.rb', line 14

def default_model
  @default_model
end

#event_loop_dispatch_threshold_seconds ⇒ Numeric?

Warn when processing a single event on the EventLoop thread takes longer than this many seconds (long-running task / blocking-on-loop detection). Set to nil to disable the warning.

Returns:

  • (Numeric, nil) 


111
112
113
 
# File 'lib/phronomy/configuration.rb', line 111

def event_loop_dispatch_threshold_seconds
  @event_loop_dispatch_threshold_seconds
end

#event_loop_starvation_threshold_seconds ⇒ Numeric?

Warn when an event spends longer than this many seconds waiting in the EventLoop queue before being dispatched (starvation detection). Set to nil to disable the warning.

Returns:

  • (Numeric, nil) 


105
106
107
 
# File 'lib/phronomy/configuration.rb', line 105

def event_loop_starvation_threshold_seconds
  @event_loop_starvation_threshold_seconds
end

#event_loop_stop_grace_seconds ⇒ Object

Grace period (in seconds) before the EventLoop background thread is force-killed after a cooperative stop request. Applies both to the overall thread join and to the drain-and-cancel phase when stop(drain: true) is used. Default: 5 seconds.

See Also:



61
62
63
 
# File 'lib/phronomy/configuration.rb', line 61

def event_loop_stop_grace_seconds
  @event_loop_stop_grace_seconds
end

#llm_adapter ⇒ Object

LLM adapter used by Agent::Base to perform LLM calls. Must be an instance of a class that inherits from LLMAdapter::Base. Defaults to LLMAdapter::RubyLLM which delegates to chat.ask via BlockingAdapterPool. Set to a custom adapter to swap in an alternative LLM client without changing any agent code.

Examples:

Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }


87
88
89
 
# File 'lib/phronomy/configuration.rb', line 87

def llm_adapter
  @llm_adapter
end

#logger ⇒ Object

Optional logger for framework diagnostic messages (e.g. unreachable-state warnings). Must respond to #warn(message). When nil (default), messages are written to $stderr via Kernel#warn.

Examples:

Phronomy.configure { |c| c.logger = Rails.logger }


54
55
56
 
# File 'lib/phronomy/configuration.rb', line 54

def logger
  @logger
end

#max_concurrent_agent_tasks ⇒ Integer?

Maximum number of concurrent agent tasks (invoke_async calls in-flight). nil = unlimited (default). When at capacity, behaviour is controlled by backpressure (:wait, :raise/:reject, :timeout).

Returns:

  • (Integer, nil) 


127
128
129
 
# File 'lib/phronomy/configuration.rb', line 127

def max_concurrent_agent_tasks
  @max_concurrent_agent_tasks
end

#max_concurrent_llm_calls ⇒ Integer?

Maximum number of concurrent LLM calls in-flight. nil = unlimited (default).

Returns:

  • (Integer, nil) 


142
143
144
 
# File 'lib/phronomy/configuration.rb', line 142

def max_concurrent_llm_calls
  @max_concurrent_llm_calls
end

#max_concurrent_tool_tasks ⇒ Integer?

Maximum number of concurrent tool tasks (parallel tool calls in-flight). nil = unlimited (default).

Returns:

  • (Integer, nil) 


132
133
134
 
# File 'lib/phronomy/configuration.rb', line 132

def max_concurrent_tool_tasks
  @max_concurrent_tool_tasks
end

#max_concurrent_vector_searches ⇒ Integer?

Maximum number of concurrent vector-store searches in-flight. nil = unlimited (default).

Returns:

  • (Integer, nil) 


153
154
155
 
# File 'lib/phronomy/configuration.rb', line 153

def max_concurrent_vector_searches
  @max_concurrent_vector_searches
end

#max_concurrent_workflow_tasks ⇒ Integer?

Maximum number of concurrent workflow tasks. nil = unlimited (default).

Returns:

  • (Integer, nil) 


137
138
139
 
# File 'lib/phronomy/configuration.rb', line 137

def max_concurrent_workflow_tasks
  @max_concurrent_workflow_tasks
end

#parallel_tool_execution ⇒ Boolean

When true, agent LLM calls use MultiAgent::ParallelToolChat for concurrent tool dispatch within a single agent turn. Defaults to false.

Previously, this was automatically enabled when event_loop was true. As of Phase 3, parallel_tool_execution is a separate setting that must be explicitly enabled.

Examples:

Phronomy.configure { |c| c.parallel_tool_execution = true }

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/phronomy/configuration.rb', line 41

def parallel_tool_execution
  @parallel_tool_execution
end

#recursion_limit ⇒ Object

Recursion limit for graph execution (default: 25)



29
30
31
 
# File 'lib/phronomy/configuration.rb', line 29

def recursion_limit
  @recursion_limit
end

#runtime_backend ⇒ :thread, ...

Scheduler backend to use for new Runtime instances.

Value Scheduler Typical use
:thread Runtime::ThreadScheduler Default — production-ready; one OS thread per task
:immediate Runtime::FakeScheduler Tests — tasks run synchronously, no extra threads
:fiber Runtime::DeterministicScheduler (autorun) EXPERIMENTAL — Fiber-based cooperative scheduler; do not use as production default
:cooperative Runtime::FakeScheduler Deprecated — alias for :immediate; do not use in new code

The default is :thread. The :fiber backend remains experimental and opt-in; it will not become the default until integration test coverage is production grade and virtual-time/timeout semantics are fully resolved (see Issues #350, #347, #348).

When this setting is changed, the change only takes effect on the NEXT call to Runtime.instance that auto-creates a new instance (i.e. after the previous instance has been replaced or reset). To replace the current instance immediately call Phronomy::Runtime.instance = nil first.

Returns:

  • (:thread, :immediate, :fiber) 


183
184
185
 
# File 'lib/phronomy/configuration.rb', line 183

def runtime_backend
  @runtime_backend
end

#scheduler_debug ⇒ Boolean

When true, enables all blocking operation diagnostics (Issue #279). Equivalent to setting all diagnostic thresholds to their defaults.

Returns:

  • (Boolean) 


116
117
118
 
# File 'lib/phronomy/configuration.rb', line 116

def scheduler_debug
  @scheduler_debug
end

#starvation_threshold_ms ⇒ Numeric

Scheduler starvation threshold (milliseconds). When a task waits more than this many milliseconds after calling runtime.yield before being resumed, the wait is counted as a starvation event. Used by the fairness regression test and by the tasks_waiting_over_threshold metric on Runtime. Default: 50ms.

Returns:

  • (Numeric) 


162
163
164
 
# File 'lib/phronomy/configuration.rb', line 162

def starvation_threshold_ms
  @starvation_threshold_ms
end

#state_store ⇒ Object

Global state store for workflow persistence. When set, WorkflowRunner routes all state reads and writes through this store. Must be an instance of a class that inherits from Phronomy::StateStore::Base. Defaults to nil (no persistence — state lives only for the duration of invoke).

Examples:

Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }


69
70
71
 
# File 'lib/phronomy/configuration.rb', line 69

def state_store
  @state_store
end

#stream_queue_max_size ⇒ Integer?

Upper bound on the number of streaming token chunks that may be buffered in the AsyncQueue used by Agent#stream before the LLM producer is throttled. When nil (default), the queue is unbounded.

Returns:

  • (Integer, nil) 


148
149
150
 
# File 'lib/phronomy/configuration.rb', line 148

def stream_queue_max_size
  @stream_queue_max_size
end

#strict_runtime_guards ⇒ Boolean

When true, calling Agent#invoke from inside a scheduler task raises SchedulerReentrancyError. When false (default), a warning is logged instead so that existing callers have time to migrate.

Returns:

  • (Boolean) 


189
190
191
 
# File 'lib/phronomy/configuration.rb', line 189

def strict_runtime_guards
  @strict_runtime_guards
end

#tool_result_max_size ⇒ Object

Maximum byte length of a tool result returned to the LLM. When a tool returns a String longer than this limit, the string is truncated and a warning is logged. Set to nil (default) to disable truncation.

Examples:

Phronomy.configure { |c| c.tool_result_max_size = 8192 }


76
77
78
 
# File 'lib/phronomy/configuration.rb', line 76

def tool_result_max_size
  @tool_result_max_size
end

#trace_pii ⇒ Object

When true, user input and LLM output are recorded in trace spans. Defaults to false; set to true only in environments where PII capture is acceptable. Set to false in privacy-sensitive environments to prevent PII from reaching the tracing backend (OTel, Langfuse, etc.).



47
48
49
 
# File 'lib/phronomy/configuration.rb', line 47

def trace_pii
  @trace_pii
end

#tracer ⇒ Object

Tracer instance



20
21
22
 
# File 'lib/phronomy/configuration.rb', line 20

def tracer
  @tracer
end