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.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/phronomy/configuration.rb', line 198

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_callback_error_policy = :report
  @blocking_io_pool_size = 10
  @blocking_io_queue_size = 100
  @authorization_pool_size = 4
  @authorization_queue_size = 100
  @authorization_timeout = 5
  @starvation_threshold_ms = 50
  @runtime_backend = :thread
  @strict_runtime_guards = false
end

Instance Attribute Details

#authorization_pool_size ⇒ Integer

Worker count for Tool authorization evaluation. The named pool is owned by Runtime#pool(:authorization) and shares PoolRegistry lifecycle.

Returns:

  • (Integer) 


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

def authorization_pool_size
  @authorization_pool_size
end

#authorization_queue_size ⇒ Integer

Maximum queued Tool authorization evaluations.

Returns:

  • (Integer) 


145
146
147
 
# File 'lib/phronomy/configuration.rb', line 145

def authorization_queue_size
  @authorization_queue_size
end

#authorization_timeout ⇒ Numeric

Operation-wide deadline for approval_facts, requires_approval callables, and Agent#tool_approval_policy. Timeout fails closed to Human approval.

Returns:

  • (Numeric) 


150
151
152
 
# File 'lib/phronomy/configuration.rb', line 150

def authorization_timeout
  @authorization_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.



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

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) 


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

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) 


130
131
132
 
# File 'lib/phronomy/configuration.rb', line 130

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) 


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

def blocking_io_queue_size
  @blocking_io_queue_size
end

#default_embedding_model ⇒ Object

Default embedding model name



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

def default_embedding_model
  @default_embedding_model
end

#default_model ⇒ Object

Default LLM model name (nil delegates to RubyLLM default)



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

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) 


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

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) 


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

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


64
65
66
 
# File 'lib/phronomy/configuration.rb', line 64

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 }


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

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 }


57
58
59
 
# File 'lib/phronomy/configuration.rb', line 57

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) 


44
45
46
 
# File 'lib/phronomy/configuration.rb', line 44

def parallel_tool_execution
  @parallel_tool_execution
end

#recursion_limit ⇒ Object

Recursion limit for graph execution (default: 25)



32
33
34
 
# File 'lib/phronomy/configuration.rb', line 32

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) 


180
181
182
 
# File 'lib/phronomy/configuration.rb', line 180

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) 


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

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) 


159
160
161
 
# File 'lib/phronomy/configuration.rb', line 159

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 }


72
73
74
 
# File 'lib/phronomy/configuration.rb', line 72

def state_store
  @state_store
end

#stream_callback_error_policy ⇒ :report, :fail_task

Determines how an unhandled Application exception from a terminal stream callback affects the Task returned by Agent#stream_async or Agent#approve_async.

:report logs the callback failure and preserves the Agent result. :fail_task logs the callback failure and fails the current Task with StreamCallbackError. Neither policy terminates EventLoop.

Default: :report.

Returns:

  • (:report, :fail_task) 


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

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


186
187
188
 
# File 'lib/phronomy/configuration.rb', line 186

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 }


79
80
81
 
# File 'lib/phronomy/configuration.rb', line 79

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



50
51
52
 
# File 'lib/phronomy/configuration.rb', line 50

def trace_pii
  @trace_pii
end

#tracer ⇒ Object

Tracer instance



23
24
25
 
# File 'lib/phronomy/configuration.rb', line 23

def tracer
  @tracer
end