Class: RubyLLM::Toolbox::Configuration

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

Overview

Holds global defaults. Every tool takes a snapshot of this at construction time (see Base#initialize) so a single tool instance can be scoped without mutating the global config:

chat.with_tool(ReadFile.new(fs_root: "/srv/project"))

Treat configuration values as read-only inside tools. Do not mutate the arrays in place; assign a new value instead.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 99

def initialize
  @fs_root           = Dir.pwd
  @enable_exec_tools = false
  @allowed_commands  = []
  @command_timeout   = 30
  @max_processes     = 8
  @env_passthrough   = %w[PATH LANG LC_ALL HOME]
  @max_output_tokens = 2_000
  @tokenizer_model   = "gpt-4o"
  @regex_timeout     = 2
  @max_grep_matches  = 200
  @ignored_dirs      = %w[.git .hg .svn node_modules .bundle tmp]
  @search_adapter    = nil
  @tavily_api_key    = ENV["TAVILY_API_KEY"]
  @brave_api_key     = ENV["BRAVE_API_KEY"] || ENV["BRAVE_SEARCH_API_KEY"]
  @searxng_url       = ENV["SEARXNG_URL"]
  @web_allowlist     = []
  @web_denylist      = []
  @docker_image      = "ruby:3.3-slim"
  @python_image      = "python:3.12-slim"
  @rust_image        = "rust:1-slim"
  @sandbox_network   = "none"
  @sandbox_memory    = "256m"
  @sandbox_cpus      = "1.0"
  @sandbox_pids      = 128
  @sandbox_user      = "1000:1000"
  @sandbox_runtime          = :auto
  @sandbox_bwrap_extra      = []
  @sandbox_seatbelt_profile = nil
  @http_timeout      = 10
  @user_agent        = "ruby_llm-toolbox/#{RubyLLM::Toolbox::VERSION}"
  @max_fetch_bytes   = 2_000_000
  @max_redirects     = 5
  @allow_unsafe      = false
  @unsafe_logger     = nil
end

Instance Attribute Details

#allow_unsafe ⇒ Object

— Security override (operator-controlled) ————————- Master switch for per-call unsafe escalation. When false (the default), any tool call that passes unsafe: true is REFUSED — an agent cannot escalate its own privileges. Only a human operator can set this to true, at which point a tool may bypass its guard (path jail, URL guard, command allowlist) for that specific call. Set unsafe_logger to audit every escalation that is actually granted.



96
97
98
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 96

def allow_unsafe
  @allow_unsafe
end

#allowed_commands ⇒ Object

Executables BashTool is permitted to run. Empty means “nothing”.



27
28
29
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 27

def allowed_commands
  @allowed_commands
end

#brave_api_key ⇒ Object

for the :brave adapter (Brave Search API)



63
64
65
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 63

def brave_api_key
  @brave_api_key
end

#command_timeout ⇒ Object

Hard wall-clock limit for any spawned process, in seconds.



30
31
32
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 30

def command_timeout
  @command_timeout
end

#docker_image ⇒ Object

— Sandbox (run_ruby) ———————————————- Docker is the locked code-execution backend. These map to ‘docker run` isolation flags.



71
72
73
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 71

def docker_image
  @docker_image
end

#enable_exec_tools ⇒ Object

— Exec / mutation gate ——————————————– Master switch for the dangerous tool set (bash, write_file, edit_file, run_code, git_commit, mutating http). Off by default: the gem is safe-by-default even though every class is loaded.



24
25
26
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 24

def enable_exec_tools
  @enable_exec_tools
end

#env_passthrough ⇒ Object

Only these environment variables are passed through to spawned processes; everything else is unset.



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

def env_passthrough
  @env_passthrough
end

#fs_root ⇒ Object

— Filesystem ——————————————————- Every filesystem tool is confined to this root (symlinks resolved).



18
19
20
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 18

def fs_root
  @fs_root
end

#http_timeout ⇒ Object

— HTTP (gem tool, web tools) ————————————–



84
85
86
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 84

def http_timeout
  @http_timeout
end

#ignored_dirs ⇒ Object

Directory basenames pruned during recursive walks.



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

def ignored_dirs
  @ignored_dirs
end

#max_fetch_bytes ⇒ Object

cap on a fetched response body



86
87
88
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 86

def max_fetch_bytes
  @max_fetch_bytes
end

#max_grep_matches ⇒ Object

Cap on grep matches returned in a single call.



51
52
53
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 51

def max_grep_matches
  @max_grep_matches
end

#max_output_tokens ⇒ Object

— Output budgeting ————————————————- Tool results are truncated (head + tail, middle elided) to fit this many tokens, counted with ruby_llm-tokenizer.



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

def max_output_tokens
  @max_output_tokens
end

#max_processes ⇒ Object

max concurrent background processes (process_start)



31
32
33
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 31

def max_processes
  @max_processes
end

#max_redirects ⇒ Object

redirect hops web_fetch will follow



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

def max_redirects
  @max_redirects
end

#python_image ⇒ Object

image for run_python



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

def python_image
  @python_image
end

#regex_timeout ⇒ Object

— Search / traversal ———————————————- Per-pattern wall-clock limit for user-supplied regexes (ReDoS guard).



48
49
50
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 48

def regex_timeout
  @regex_timeout
end

#rust_image ⇒ Object

image for run_rust



73
74
75
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 73

def rust_image
  @rust_image
end

#sandbox_bwrap_extra ⇒ Object

extra bwrap args (e.g. [“–tmpfs”, “/home”])



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

def sandbox_bwrap_extra
  @sandbox_bwrap_extra
end

#sandbox_cpus ⇒ Object

–cpus



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

def sandbox_cpus
  @sandbox_cpus
end

#sandbox_memory ⇒ Object

–memory



75
76
77
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 75

def sandbox_memory
  @sandbox_memory
end

#sandbox_network ⇒ Object

–network



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

def sandbox_network
  @sandbox_network
end

#sandbox_pids ⇒ Object

–pids-limit



77
78
79
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 77

def sandbox_pids
  @sandbox_pids
end

#sandbox_runtime ⇒ Object

:auto | :docker | :bubblewrap | :sandbox_exec | :none



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

def sandbox_runtime
  @sandbox_runtime
end

#sandbox_seatbelt_profile ⇒ Object

custom Seatbelt SBPL profile string (overrides default)



81
82
83
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 81

def sandbox_seatbelt_profile
  @sandbox_seatbelt_profile
end

#sandbox_user ⇒ Object

–user (uid:gid)



78
79
80
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 78

def sandbox_user
  @sandbox_user
end

#search_adapter ⇒ Object

— Web (phase 3) —————————————————- Pluggable search backend. Tavily is the chosen default provider, but the adapter is swappable: set search_adapter to an object responding to #search(query, max_results:), or to a symbol (:tavily, :brave, :searxng) to select a built-in adapter. nil falls back to Tavily.



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

def search_adapter
  @search_adapter
end

#searxng_url ⇒ Object

base URL of a self-hosted SearXNG instance



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

def searxng_url
  @searxng_url
end

#tavily_api_key ⇒ Object

Returns the value of attribute tavily_api_key.



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

def tavily_api_key
  @tavily_api_key
end

#tokenizer_model ⇒ Object

Model identifier used to pick a tokenizer. For Claude models, call RubyLLM::Tokenizer.enable_claude_approximation! once at boot.



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

def tokenizer_model
  @tokenizer_model
end

#unsafe_logger ⇒ Object

callable: ->(tool_name, detail) { … }



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

def unsafe_logger
  @unsafe_logger
end

#user_agent ⇒ Object

Returns the value of attribute user_agent.



85
86
87
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 85

def user_agent
  @user_agent
end

#web_allowlist ⇒ Object

Returns the value of attribute web_allowlist.



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

def web_allowlist
  @web_allowlist
end

#web_denylist ⇒ Object

Returns the value of attribute web_denylist.



66
67
68
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 66

def web_denylist
  @web_denylist
end

Instance Method Details

#dup_with(**overrides) ⇒ Object

Returns a copy with the given attributes overridden. Used to scope a single tool instance without touching global state.



138
139
140
141
142
143
144
145
 
# File 'lib/ruby_llm/toolbox/configuration.rb', line 138

def dup_with(**overrides)
  copy = self.class.new
  instance_variables.each do |ivar|
    copy.instance_variable_set(ivar, instance_variable_get(ivar))
  end
  overrides.each { |key, value| copy.public_send("#{key}=", value) }
  copy
end