robot_lab-to 0.2.7 → 0.3.0

data/examples/common.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+#
+# ===========================================================================
+# common.rb — shared RubyLLM setup/teardown for the robot_lab-to example demos
+# ===========================================================================
+#
+# Every example under examples/ requires this file (examples/.envrc supplies
+# the RLTO_* / LMS_BASE_URL defaults) and calls `setup` before talking to
+# RubyLLM -- once for a single-model example, or once per model role for an
+# example with more than one (e.g. 04_prose's doer + judge).
+#
+#   actual_provider = setup(provider: PROVIDER, model: MODEL)
+#   RobotLab::To.run(objective, provider: actual_provider, model: MODEL, ...)
+#
+# "lms" is the ruby_llm-providers-lms gem's native LM Studio provider.
+# When `provider` is "lms", setup:
+#   1. points the :lms provider at LMS_BASE_URL
+#   2. starts the LM Studio server if it isn't already running
+#   3. loads `model` into LM Studio if it isn't already loaded
+# and returns :lms -- the RubyLLM-recognized provider to pass to RobotLab.
+# Any other provider (a cloud one) passes straight through untouched; setup
+# does nothing else for it (the example configures its own API key as before).
+#
+# teardown stops the LM Studio server, but ONLY if setup started it here -- a
+# server you already had running (the LM Studio app, another example) is left
+# alone. It runs automatically via an at_exit hook; examples never call it.
+# ===========================================================================
+
+require "json"
+require "logger"
+require "open3"
+require "uri"
+
+require "ruby_llm"
+require "ruby_llm/providers/lms"
+
+LMS_BASE_URL = ENV.fetch("LMS_BASE_URL", "http://localhost:1234/v1")
+
+@lms_server_started_by_us = false
+
+def setup(provider: ENV.fetch("RLTO_PROVIDER", "lms"), model: ENV.fetch("RLTO_MODEL", "qwen/qwen3.8-27b"))
+  provider = provider.to_sym
+  return provider unless provider == :lms
+
+  configure_lms!
+  ensure_lms_server_running!
+  ensure_lms_model_loaded!(model)
+  :lms
+end
+
+def teardown
+  return unless @lms_server_started_by_us
+
+  puts "Stopping the LM Studio server (started for this run)…"
+  Open3.capture2e("lms", "server", "stop")
+end
+
+at_exit { teardown }
+
+# --- internals ---------------------------------------------------------------
+
+# Point the :lms provider at the LM Studio endpoint. Local models are assumed
+# to exist, so no registry refresh is needed.
+def configure_lms!
+  RubyLLM.configure do |c|
+    c.lms_api_base    = LMS_BASE_URL
+    c.request_timeout = 600
+  end
+  RubyLLM.logger.level = Logger::ERROR
+end
+
+def lms_server_running?
+  out, status = Open3.capture2("lms", "server", "status", "--json")
+  status.success? && JSON.parse(out)["running"] == true
+rescue StandardError
+  false
+end
+
+def ensure_lms_server_running!
+  return if lms_server_running?
+
+  puts "Starting the LM Studio server…"
+  port = URI.parse(LMS_BASE_URL).port.to_s
+  out, status = Open3.capture2e("lms", "server", "start", "--port", port)
+  abort "Could not start the LM Studio server:\n#{out}" unless status.success? && lms_server_running?
+
+  @lms_server_started_by_us = true
+rescue Errno::ENOENT
+  abort "The `lms` CLI was not found. Install LM Studio (https://lmstudio.ai) and " \
+        "run `lms bootstrap` to put it on your PATH."
+end
+
+def lms_model_loaded?(model)
+  out, status = Open3.capture2("lms", "ps", "--json")
+  return false unless status.success?
+
+  JSON.parse(out).any? { |m| m["modelKey"] == model || m["identifier"] == model }
+rescue StandardError
+  false
+end
+
+def ensure_lms_model_loaded!(model)
+  return if lms_model_loaded?(model)
+
+  puts "Loading #{model} into LM Studio (first run only)…"
+  out, status = Open3.capture2e("lms", "load", model, "-y")
+  abort "Could not load #{model} in LM Studio:\n#{out}" unless status.success?
+rescue Errno::ENOENT
+  abort "The `lms` CLI was not found. Install LM Studio (https://lmstudio.ai) and " \
+        "run `lms bootstrap` to put it on your PATH."
+end

data/lib/robot_lab/to/cli.rb

@@ -46,6 +46,17 @@ module RobotLab
          "Seconds between polls while waiting on a decision (default: 30)", :decision_wait_poll]
       ].freeze
 
+      # Boolean flags with a fixed value when passed (no argument). Flags
+      # needing bespoke behavior (protect-path, require-improvement, help)
+      # stay in #add_flag_options.
+      BOOLEAN_FLAGS = [
+        ["--no-decisions", "Disable the request_decision tool for this run", :decisions_enabled, false],
+        ["--local-guards", "Add built-in file tools + small-model guardrails (for local models)", :local_guards, true],
+        ["--no-stream", "Disable response streaming (required for local Ollama tool calls)", :stream, false],
+        ["--debug", "Enable verbose JSONL logging to stderr", :debug, true],
+        ["--version", "Print version and exit", :version, true]
+      ].freeze
+
       def self.run(argv = ARGV)
         new.run(argv)
       end
@@ -53,32 +64,33 @@ module RobotLab
       def run(argv)
         return run_decisions(argv[1..] || []) if argv.first == "decisions"
 
-        opts   = {}
-        parser = build_parser(opts)
-        args   = parser.parse!(argv.dup)
+        opts, parser, args = parse_options(argv)
 
-        if opts[:version]
-          puts "robot-to #{VERSION}"
-          return
-        end
-
-        if opts[:resume]
-          return RobotLab::To.resume(opts[:resume], **opts.except(:version, :resume))
-        end
+        return puts("robot-to #{VERSION}") if opts[:version]
+        return RobotLab::To.resume(opts[:resume], **opts.except(:version, :resume)) if opts[:resume]
 
         objective = args.first || read_stdin_objective
-        if objective.nil? || objective.strip.empty?
-          # $stderr.puts, not warn: warn is silenced when $VERBOSE is nil.
-          $stderr.puts "Error: objective required (pass as argument or via stdin)"
-          $stderr.puts parser
-          exit 1
-        end
+        abort_missing_objective!(parser) if objective.nil? || objective.strip.empty?
 
         RobotLab::To.run(objective.strip, **opts.except(:version, :resume))
       end
 
       private
 
+      def parse_options(argv)
+        opts   = {}
+        parser = build_parser(opts)
+        args   = parser.parse!(argv.dup)
+        [opts, parser, args]
+      end
+
+      def abort_missing_objective!(parser)
+        # $stderr.puts, not warn: warn is silenced when $VERBOSE is nil.
+        $stderr.puts "Error: objective required (pass as argument or via stdin)"
+        $stderr.puts parser
+        exit 1
+      end
+
       # `robot-to decisions [run_id]` — list pending decisions and their file
       # paths so a human knows what needs resolving before resuming.
       def run_decisions(args)
@@ -96,17 +108,19 @@ module RobotLab
       def print_decisions(run_id, manager)
         pending  = manager.pending
         resolved = manager.resolved_open
-        puts "Run #{run_id}"
-        puts ""
+
         if pending.empty? && resolved.empty?
-          puts "No open decisions."
+          puts "Run #{run_id}\n\nNo open decisions."
           return
         end
+
+        puts "Run #{run_id}\n\n"
         list_group("Pending (awaiting your answer)", pending)
         list_group("Resolved (not yet consumed)", resolved)
-        puts ""
-        puts "Resolve a pending decision by editing its file: set `status: resolved`"
-        puts "and fill `resolution:`, then run `robot-to --resume #{run_id}`."
+        puts <<~MSG
+          Resolve a pending decision by editing its file: set `status: resolved`
+          and fill `resolution:`, then run `robot-to --resume #{run_id}`.
+        MSG
       end
 
       def list_group(title, decisions)
@@ -126,6 +140,7 @@ module RobotLab
            .sort.map { |p| File.basename(p) }.last
       end
 
+      # :reek:FeatureEnvy -- configuring the OptionParser instance being built.
       def build_parser(opts)
         OptionParser.new do |p|
           p.banner = "Usage: robot-to [objective] [options]\n       " \
@@ -136,30 +151,42 @@ module RobotLab
           p.separator ""
           p.separator "Options:"
 
-          VALUE_OPTIONS.each do |flag, type, desc, key|
-            p.on(flag, type, desc) { |v| opts[key] = v }
-          end
-
+          add_value_options(p, opts)
           add_flag_options(p, opts)
         end
       end
 
+      # :reek:NestedIterators -- one .on registration per option, each with its
+      # own value-assignment callback; that's the OptionParser API shape.
+      def add_value_options(parser, opts)
+        VALUE_OPTIONS.each do |flag, type, desc, key|
+          parser.on(flag, type, desc) { |v| opts[key] = v }
+        end
+      end
+
+      # :reek:FeatureEnvy -- registering flags on the OptionParser being built.
       # Boolean and terminal flags (each has bespoke behavior).
       def add_flag_options(parser, opts)
+        add_require_improvement_option(parser, opts)
+        add_protect_path_option(parser, opts)
+        BOOLEAN_FLAGS.each { |flag, desc, key, value| parser.on(flag, desc) { opts[key] = value } }
+        add_help_option(parser)
+      end
+
+      def add_require_improvement_option(parser, opts)
         parser.on("--[no-]require-improvement",
                   "Roll back gate-passing iterations that don't improve (default: on)") do |v|
           opts[:require_improvement] = v
         end
+      end
+
+      def add_protect_path_option(parser, opts)
         parser.on("--protect-path GLOB", "Lock a grader file from robot edits (repeatable)") do |v|
           (opts[:protect_paths] ||= []) << v
         end
-        parser.on("--no-decisions", "Disable the request_decision tool for this run") { opts[:decisions_enabled] = false }
-        parser.on("--local-guards", "Add built-in file tools + small-model guardrails (for local models)") do
-          opts[:local_guards] = true
-        end
-        parser.on("--no-stream", "Disable response streaming (required for local Ollama tool calls)") { opts[:stream] = false }
-        parser.on("--debug", "Enable verbose JSONL logging to stderr") { opts[:debug] = true }
-        parser.on("--version", "Print version and exit") { opts[:version] = true }
+      end
+
+      def add_help_option(parser)
         parser.on("-h", "--help", "Show this help") do
           puts parser
           exit

data/lib/robot_lab/to/commit_manager.rb

@@ -8,6 +8,9 @@ module RobotLab
     #
     # All subprocess calls use explicit argv arrays (no shell interpolation).
     # GIT_TERMINAL_PROMPT=0 prevents credential prompts from hanging the loop.
+    # :reek:RepeatedConditional -- each `status.success?` belongs to a distinct
+    # Open3.capture3 call with its own failure handling; there is no shared
+    # condition to extract.
     class CommitManager
       GIT_ENV = { "GIT_TERMINAL_PROMPT" => "0" }.freeze
 
@@ -72,6 +75,7 @@ module RobotLab
         parse_diff_stat(out)
       end
 
+      # :reek:FeatureEnvy -- inherent to building/reading/appending a Pathname.
       def add_to_local_exclude(entry)
         exclude = Pathname.new(@work_dir).join(".git", "info", "exclude")
         exclude.parent.mkpath

data/lib/robot_lab/to/config.rb

@@ -11,6 +11,15 @@ module RobotLab
     #   2. User config file (~/.config/robot_lab/to.yml)
     #   3. Environment variables (ROBOT_LAB_TO_*)
     #   4. Constructor keyword arguments (CLI overrides)
+    # :reek:TooManyInstanceVariables -- a flat CLI-override bag for ~24
+    # independent settings; each ivar is genuinely one distinct setting.
+    # :reek:InstanceVariableAssumption -- the defaults.yml-backed ivars
+    # (provider, model, max_consecutive_failures, max_submit_nudges,
+    # max_verify_repairs, verify_timeout, run_dir, commit_format, local_guards,
+    # stream, debug, decisions_enabled, decision_mode, decision_wait_poll,
+    # decision_timeout) ARE assigned -- by `super()` (MywayConfig::Base /
+    # Anyway::Config), before any of this class's own code runs. Do NOT
+    # pre-nil them here: that overwrites the real loaded values with nil.
     class Config < MywayConfig::Base
       config_name :robot_lab_to
       env_prefix :robot_lab_to
@@ -34,6 +43,9 @@ module RobotLab
 
       def initialize(**overrides)
         super()
+        # CLI-only, no YAML default (nil means "no limit / not set") -- unlike
+        # the defaults.yml-backed ivars above, super() never touches these.
+        @max_iterations = @max_tokens = @stop_when = @verify_command = nil
         @eval = @eval_measure = @eval_target = nil
         @require_improvement = @stop_on_plateau = nil
         @eval_judge_model = @eval_spec = @eval_floor = nil

data/lib/robot_lab/to/decision_manager.rb

@@ -40,6 +40,11 @@ module RobotLab
       end
 
       # Persist a decision the robot raised. Returns the parsed Decision.
+      # :reek:BooleanParameter -- blocking is stored data (front matter), not a
+      # behavior switch.
+      # :reek:ControlParameter -- the ternary only coerces blocking to true/false.
+      # :reek:LongParameterList { max_params: 6 } -- one field per front-matter
+      # attribute; a hash would just move the same six names elsewhere.
       def record(question:, situation: "", options: [], recommendation: "", blocking: false, iteration: 0)
         id   = generate_id
         path = @dir.join("#{id}.md")
@@ -57,6 +62,7 @@ module RobotLab
       def pending       = all.select(&:pending?)
       # resolved but not yet closed
       def resolved_open = all.select(&:resolved?)
+      # :reek:FeatureEnvy -- filtering by a Decision's own predicates.
       def blocking_pending = all.select { |d| d.pending? && d.blocking? }
       def blocking_pending? = blocking_pending.any?
 
@@ -66,6 +72,7 @@ module RobotLab
       # Mark a resolved decision closed: its resolution has been delivered to a
       # robot and committed, so it should no longer be re-injected. Flips only
       # the status line, preserving whatever the human wrote in the body.
+      # :reek:FeatureEnvy -- reading/rewriting the decision's own file.
       def close(decision)
         raw = File.read(decision.path)
         AtomicFile.write(decision.path, flip_status(raw, "closed"))
@@ -82,8 +89,10 @@ module RobotLab
         raw.sub(/^status:.*$/, "status: #{status}")
       end
 
+      # :reek:LongParameterList { max_params: 7 } -- one field per front-matter
+      # attribute, mirroring #record.
       def render_new(id:, question:, situation:, options:, recommendation:, blocking:, iteration:)
-        options_md = options.empty? ? "(none provided)\n" : options.each_with_index.map { |o, i| "#{i + 1}. #{o}" }.join("\n") + "\n"
+        options_md = options.empty? ? "(none provided)\n" : options.each_with_index.map { |opt, i| "#{i + 1}. #{opt}" }.join("\n") + "\n"
         # Build the front matter with YAML.dump so question/recommendation are
         # escaped correctly (they can contain colons, quotes, etc.).
         front = {
@@ -116,6 +125,7 @@ module RobotLab
 
       # Split a file into (front_matter_hash, body). Returns a Decision or nil
       # when the file is unreadable.
+      # :reek:FeatureEnvy -- building a Decision from its own front matter hash.
       def parse(path)
         text = File.read(path)
         fm, body = split_front_matter(text)
@@ -138,6 +148,7 @@ module RobotLab
         nil
       end
 
+      # :reek:FeatureEnvy -- slicing the raw file text into front matter/body.
       def split_front_matter(text)
         if text.start_with?("---\n") && (close_idx = text.index("\n---", 4))
           raw_fm = text[4...close_idx]

data/lib/robot_lab/to/exit_summary.rb

@@ -11,14 +11,9 @@ module RobotLab
       end
 
       def print
-        stat       = @run.base_commit ? diff_stat : { insertions: 0, deletions: 0, files: 0 }
-        aborted    = !@abort_reason.nil?
-        good_iters = @run.commits
-        fail_iters = @run.iteration - good_iters
-
         puts ""
-        print_header(aborted)
-        print_counters(good_iters, fail_iters, stat)
+        @abort_reason ? print_aborted_header : print_completed_header
+        print_counters
         print_paths
         print_next_steps
         puts ""
@@ -26,17 +21,21 @@ module RobotLab
 
       private
 
-      def print_header(aborted)
-        if aborted
-          puts "robot-to stopped — #{@config.model} — #{@run.elapsed_human}"
-          puts "Reason: #{@abort_reason}"
-        else
-          puts "robot-to complete — #{@config.model} — #{@run.elapsed_human}"
-          puts "Branch: #{@run.branch}"
-        end
+      def print_aborted_header
+        puts "robot-to stopped — #{@config.model} — #{@run.elapsed_human}"
+        puts "Reason: #{@abort_reason}"
+      end
+
+      def print_completed_header
+        puts "robot-to complete — #{@config.model} — #{@run.elapsed_human}"
+        puts "Branch: #{@run.branch}"
       end
 
-      def print_counters(good_iters, fail_iters, stat)
+      def print_counters
+        good_iters = @run.commits
+        fail_iters = @run.iteration - good_iters
+        stat       = diff_stat
+
         puts ""
         puts "Iterations:      #{@run.iteration} total  (#{good_iters} good / #{fail_iters} failed)"
         puts "Tokens:          #{comma(@run.total_tokens)}  (#{comma(@run.input_tokens)} in / #{comma(@run.output_tokens)} out)"
@@ -61,6 +60,8 @@ module RobotLab
       end
 
       def diff_stat
+        return { insertions: 0, deletions: 0, files: 0 } unless @run.base_commit
+
         git = CommitManager.new
         git.diff_stat(@run.base_commit)
       rescue StandardError

data/lib/robot_lab/to/guards/checkpoint.rb

@@ -48,7 +48,12 @@ module RobotLab
 
             tracked << path
             FileUtils.mkdir_p(dir)
-            dest = File.join(dir, safe_name(path))
+            write_backup(path, File.join(dir, safe_name(path)))
+          rescue SystemCallError, IOError
+            nil
+          end
+
+          def write_backup(path, dest)
             if File.exist?(path)
               FileUtils.cp(path, dest)
               dest
@@ -56,8 +61,6 @@ module RobotLab
               File.write("#{dest}.absent", "")
               "#{dest}.absent"
             end
-          rescue SystemCallError, IOError
-            nil
           end
 
           # @return [String] directory for this run's checkpoints (created)

data/lib/robot_lab/to/guards/quality_monitor.rb

@@ -73,8 +73,9 @@ module RobotLab
             return :empty_response if text.to_s.strip.empty? && calls.empty?
 
             calls.each do |c|
-              return :empty_tool_name if c[:name].to_s.empty?
-              return "unknown_tool:#{c[:name]}" if known.any? && !known.include?(c[:name])
+              name = c[:name]
+              return :empty_tool_name if name.to_s.empty?
+              return "unknown_tool:#{name}" if known.any? && !known.include?(name)
             end
 
             return :repeated_tool_call if repeated?(calls, previous)
@@ -83,6 +84,7 @@ module RobotLab
           end
 
           # True when any current call exactly matches any previous call.
+          # :reek:NestedIterators -- an all-pairs comparison needs both loops.
           def repeated?(calls, previous)
             return false if calls.empty? || previous.empty?
 

data/lib/robot_lab/to/guards/run_store.rb

@@ -22,8 +22,10 @@ module RobotLab
 
         # Fetch the value for `key`, initializing to `default` when unset.
         def fetch(key, default = nil)
-          Thread.current[key] = default if Thread.current[key].nil? && !default.nil?
-          Thread.current[key]
+          value = Thread.current[key]
+          return value unless value.nil?
+
+          Thread.current[key] = default
         end
       end
     end

data/lib/robot_lab/to/notes_manager.rb

@@ -13,6 +13,7 @@ module RobotLab
         @path = Pathname.new(path)
       end
 
+      # :reek:FeatureEnvy -- interpolating the run's own fields into the header.
       def setup(run)
         AtomicFile.write(@path, <<~HEADER)
           # robot-to run: #{run.run_id}
@@ -84,6 +85,7 @@ module RobotLab
         MD
       end
 
+      # :reek:FeatureEnvy -- interpolating the error's own class/message.
       def append_error(error, iteration)
         append(<<~MD)
 
@@ -93,6 +95,7 @@ module RobotLab
         MD
       end
 
+      # :reek:FeatureEnvy -- interpolating the decision's own fields.
       def append_decision(decision, iteration)
         append(<<~MD)