Class: Xeno::Configuration

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

Overview

Gem-level runtime knobs, set from an initializer:

Xeno.configure do |config|
config.max_steps = 30
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/xeno/configuration.rb', line 82

def initialize
  @max_steps = 20
  @max_turn_attempts = 5
  @turn_stale_after = 5 * 60 # seconds
  @heartbeat_interval = nil
  @max_input_tokens_per_session = nil
  @max_output_tokens_per_session = nil
  @compaction_threshold = 0.9
  @compaction_context_window = nil
  @compaction_tail_turns = 2
  @stopping_check = nil
  @authenticate = nil
  @stream_poll_interval = 0.25
  @stream_catch_up_batch = 500
  @stream_max_duration = nil
  @stream_shutdown_check = nil
end

Instance Attribute Details

#authenticate ⇒ Object

Fail-closed HTTP auth lambda. Receives the request; a falsy return is a 401; a truthy return becomes the request principal.



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

def authenticate
  @authenticate
end

#compaction_context_window ⇒ Object

Fallback context window (tokens) for models the registry doesn't know (assume_model_exists). nil = automatic compaction never triggers for unknown-window models.



45
46
47
 
# File 'lib/xeno/configuration.rb', line 45

def compaction_context_window
  @compaction_context_window
end

#compaction_tail_turns ⇒ Object

How many of the most recent user-message-anchored turns survive a compaction verbatim (the "recent tail"). Everything earlier is summarized and replaced.



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

def compaction_tail_turns
  @compaction_tail_turns
end

#compaction_threshold ⇒ Object

Compaction triggers when the last model call's context usage crosses this fraction of the model's context window. nil/false disables automatic compaction (manual stays available).



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

def compaction_threshold
  @compaction_threshold
end

#heartbeat_interval ⇒ Object 



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

def heartbeat_interval
  @heartbeat_interval || turn_stale_after / 4.0
end

#max_input_tokens_per_session ⇒ Object

Per-session token budgets, enforced BEFORE each model call from the persisted usage columns (the provider's own counts). Checked independently per axis; the call that crosses is allowed to finish — the NEXT call trips. Exceeded → deterministic turn failure with a budget.exceeded event; the session recovers via reset. nil = unlimited. Per-agent override: limits input_tokens:, output_tokens: in agent.rb (false disables an axis).



35
36
37
 
# File 'lib/xeno/configuration.rb', line 35

def max_input_tokens_per_session
  @max_input_tokens_per_session
end

#max_output_tokens_per_session ⇒ Object

Per-session token budgets, enforced BEFORE each model call from the persisted usage columns (the provider's own counts). Checked independently per axis; the call that crosses is allowed to finish — the NEXT call trips. Exceeded → deterministic turn failure with a budget.exceeded event; the session recovers via reset. nil = unlimited. Per-agent override: limits input_tokens:, output_tokens: in agent.rb (false disables an axis).



35
36
37
 
# File 'lib/xeno/configuration.rb', line 35

def max_output_tokens_per_session
  @max_output_tokens_per_session
end

#max_steps ⇒ Object

Per-turn model-call budget (RubyLLM's own loop is unbounded; ours is not).



10
11
12
 
# File 'lib/xeno/configuration.rb', line 10

def max_steps
  @max_steps
end

#max_turn_attempts ⇒ Object

A turn whose claim ledger reaches this many attempts is poison — it fails instead of retrying forever.



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

def max_turn_attempts
  @max_turn_attempts
end

#stopping_check ⇒ Object

Optional lambda answering "is the worker shutting down?" — probed by the runner between steps; when true the turn releases its claim and re-enqueues itself so a deploy-style stop resumes promptly on the next worker instead of waiting out stale-heartbeat reclaim. nil = ask the queue adapter (queue_adapter.stopping? — Solid Queue flips it on worker shutdown; adapters that don't implement it just return false).



58
59
60
 
# File 'lib/xeno/configuration.rb', line 58

def stopping_check
  @stopping_check
end

#stream_catch_up_batch ⇒ Object

How many events one stream poll reads at most. Bounds the catch-up read on long sessions (a reconnect from index 0 pages through history in batches instead of loading every row in one query).



70
71
72
 
# File 'lib/xeno/configuration.rb', line 70

def stream_catch_up_batch
  @stream_catch_up_batch
end

#stream_max_duration ⇒ Object

Optional hard cap on how long one SSE connection is served (seconds). nil = until the session reaches a terminal status.



74
75
76
 
# File 'lib/xeno/configuration.rb', line 74

def stream_max_duration
  @stream_max_duration
end

#stream_poll_interval ⇒ Object

How often the SSE stream polls for new events, in seconds.



65
66
67
 
# File 'lib/xeno/configuration.rb', line 65

def stream_poll_interval
  @stream_poll_interval
end

#stream_shutdown_check ⇒ Object

Optional lambda answering "is the server shutting down?" — when true, open SSE streams close themselves so a graceful stop doesn't wait out the in-flight-request window (Ctrl-C stays near-instant with tabs open). nil = detect Puma's graceful stop automatically.



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

def stream_shutdown_check
  @stream_shutdown_check
end

#turn_stale_after ⇒ Object

A running turn whose heartbeat is older than this is presumed dead and reclaimable. Checkpoint replay makes takeover safe; a too-short window risks overlap with a live-but-slow owner, a too-long one stalls the session after a hard crash.



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

def turn_stale_after
  @turn_stale_after
end