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.



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/phronomy/configuration.rb', line 165

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
  @event_loop_starvation_threshold_seconds = nil
  @event_loop_dispatch_threshold_seconds = nil
  @scheduler_debug = false
  @blocking_detect_threshold_ms = nil
  @stream_queue_max_size = nil
  @blocking_io_pool_size = 10
  @blocking_io_queue_size = 100
  @starvation_threshold_ms = 50
  @runtime_backend = :thread
  @strict_runtime_guards = false
end

Instance Attribute Details

#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) 


107
108
109
 
# File 'lib/phronomy/configuration.rb', line 107

def blocking_detect_threshold_ms
  @blocking_detect_threshold_ms
end

#blocking_io_pool_size ⇒ Integer

Number of OS worker threads in the default BlockingAdapterPool. All LLM calls, MCP tool calls, and other blocking I/O share this pool. Increase for higher LLM/tool throughput; decrease to limit concurrency (e.g. to stay within a provider's rate limit). Default: 10.

Returns:

  • (Integer) 


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

def blocking_io_pool_size
  @blocking_io_pool_size
end

#blocking_io_queue_size ⇒ Integer

Maximum number of operations that may wait in the BlockingAdapterPool queue before BackpressureError is raised (on_full: :raise) or the caller blocks (on_full: :wait, the default). Default: 100.

Returns:

  • (Integer) 


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

def blocking_io_queue_size
  @blocking_io_queue_size
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) 


97
98
99
 
# File 'lib/phronomy/configuration.rb', line 97

def event_loop_dispatch_threshold_seconds
  @event_loop_dispatch_threshold_seconds
end

#event_loop_starvation_threshold_seconds ⇒ Numeric?

Set to nil to disable the warning.

Returns:

  • (Numeric, nil) 


91
92
93
 
# File 'lib/phronomy/configuration.rb', line 91

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:

  • EventLoop#stop


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

#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) 


157
158
159
 
# File 'lib/phronomy/configuration.rb', line 157

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) 


102
103
104
 
# File 'lib/phronomy/configuration.rb', line 102

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) 


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

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) 


113
114
115
 
# File 'lib/phronomy/configuration.rb', line 113

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) 


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

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