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.



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

def initialize
  @recursion_limit = 25
  @tracer = Phronomy::Tracing::NullTracer.new
  @trace_pii = false
  @event_loop = 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_rag_fetches = 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) 


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

def backpressure
  @backpressure
end

#backpressure_timeout ⇒ Numeric?

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

Returns:

  • (Numeric, nil) 


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

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) 


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

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 ⇒ Object

When true, workflow execution is driven by EventLoop instead of a synchronous loop in the calling thread. Defaults to false (sync mode).

See Also:



34
35
36
 
# File 'lib/phronomy/configuration.rb', line 34

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


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

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) 


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

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:



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

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 }


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

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 }


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

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) 


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

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) 


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

def max_concurrent_llm_calls
  @max_concurrent_llm_calls
end

#max_concurrent_rag_fetches ⇒ Integer?

Maximum number of concurrent RAG knowledge-source fetches in-flight. nil = unlimited (default).

Returns:

  • (Integer, nil) 


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

def max_concurrent_rag_fetches
  @max_concurrent_rag_fetches
end

#max_concurrent_tool_tasks ⇒ Integer?

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

Returns:

  • (Integer, nil) 


125
126
127
 
# File 'lib/phronomy/configuration.rb', line 125

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) 


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

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) 


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

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


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

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) 


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

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) 


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

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 }


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

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) 


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

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) 


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

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 }


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

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



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

def trace_pii
  @trace_pii
end

#tracer ⇒ Object

Tracer instance



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

def tracer
  @tracer
end