robot_lab-ractor 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24693d3b0371d41a878e7112c904e01bbf65d46f4cded26fe78b45856c49716c
-  data.tar.gz: e7fdf7b457efb4e5359f9ccf36afd50823f2fe15d11e5c56d6dd2fe93ba9f959
+  metadata.gz: 25de3bcf1d2904408d989619f14f2204b556d5cc7412683793d1e108c986192f
+  data.tar.gz: 412b11c1532be8674b9ec1767471d42909dd20e98cf2ca6661f143dbeccbe68f
 SHA512:
-  metadata.gz: 5ed65c66df3ef0d840ab8f4745cf2a3b2fe82c6216f0458480336ec3274fafde8ce8b2c610526de66f00cdf9473ab52961b6f818166b64752a911a377cb21a34
-  data.tar.gz: 9024af8c7f52c239b8549e04eab3c9f852622264a3f3656aac4d41cfc72ccb41707b07ec7749622aaddb4c8ff95d21af0c7e0aa106bedf25c4a58d7de15e9095
+  metadata.gz: ce3e69d19db119d2f28e0c4b557826271f09169d8f5adaf811787f2ffba9bd637ace4aad2f5e8f525781d5c59c6e995bd851f26bac222a5e695d3ac7a6e08c1d
+  data.tar.gz: b3a6f73c02fd8e006dc71c1cea906adb1d47051c5c584d30b45ba374f9c43a036f0782a3f60a72fde5463cd78503cc7b0292a77ded5858b52d5ef9edbc693530

data/.rubocop.yml

@@ -0,0 +1,173 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 4.0
+  Exclude:
+    - 'examples/**/*'
+    - 'vendor/**/*'
+    - 'dead_code/**/*'
+
+# ── Style: disabled cops ───────────────────────────────────────────────────
+Style/StringLiterals:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+# Ruby 4.0 freezes string literals by default
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/TrivialAccessors:
+  Enabled: false
+
+Style/MultilineTernaryOperator:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false
+
+Style/EmptyClassDefinition:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Enabled: false
+
+# Both % and format/sprintf are acceptable
+Style/FormatString:
+  Enabled: false
+
+# String concatenation and interpolation are both acceptable
+Style/StringConcatenation:
+  Enabled: false
+
+# ── Layout ─────────────────────────────────────────────────────────────────
+Layout/LineLength:
+  Max: 140
+
+Layout/ExtraSpacing:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+# ── Naming ─────────────────────────────────────────────────────────────────
+# Single-char params (c, e, n) are acceptable throughout
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Exclude:
+    - 'test/**/*'
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+# set_results and similar explicit setters are clear and conventional
+Naming/AccessorMethodName:
+  Enabled: false
+
+
+# has_tool_calls? and similar are clear and conventional
+Naming/PredicatePrefix:
+  Enabled: false
+
+# Test helper methods don't need to follow predicate naming rules
+Naming/PredicateMethod:
+  Exclude:
+    - 'test/**/*'
+
+# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
+# Library and framework methods commonly accept args for API/documentation purposes
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+
+Lint/EmptyBlock:
+  Exclude:
+    - 'test/**/*'
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'Rakefile'
+    - 'test/**/*'
+
+# ── Gemspec ────────────────────────────────────────────────────────────────
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: Gemfile
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: false
+
+# ── Metrics ────────────────────────────────────────────────────────────────
+# Framework-level code (routers, parsers, orchestrators) is inherently complex.
+# Flog is the primary complexity gate — these RuboCop thresholds catch only
+# egregious outliers without false-positiving every dispatch method.
+
+Metrics/MethodLength:
+  Max: 35
+  CountAsOne:
+    - heredoc
+    - array
+    - hash
+  Exclude:
+    - 'test/**/*'
+
+Metrics/AbcSize:
+  Max: 40
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ClassLength:
+  Max: 600
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ModuleLength:
+  Max: 200
+  Exclude:
+    - 'test/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+# Long method signatures with keyword args are a Ruby framework idiom
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'Rakefile'
+    - '*.gemspec'
+    - 'test/**/*'

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-19
+
+### Added
+- `RactorWorkerPool` — shared pool of Ractor workers; tools marked `ractor_safe true` are automatically routed through it instead of running inline
+- `RactorNetworkScheduler` — DAG-aware parallel execution of robot networks using Ractors; activated via `parallel_mode: :ractor` on a network
+- `RactorBoundary` — `freeze_deep` utility for making values Ractor-shareable; raises `RactorBoundaryError` for values that cannot cross Ractor boundaries
+- `RactorMemoryProxy` — thread-safe proxy exposing `RobotLab::Memory` to Ractor workers via `Ractor::Wrapper`
+- `RactorJob` — Ractor-shareable frozen job value object used internally by the pool and scheduler
+- `ractor_safe` class-level DSL for `RubyLLM::Tool` / `RobotLab::Tool` subclasses; inherited by subclasses
+- `RobotLab.ractor_pool` / `.shutdown_ractor_pool` — process-level pool lifecycle methods added to the `RobotLab` module
+- Ractor Parallelism guide (`docs/guides/ractor-parallelism.md`) covering both CPU-bound tools and parallel network pipelines
+
+### Changed
+- Version synchronized with robot_lab core 0.2.1
+
 ## [0.1.0] - 2026-05-07
 
 - Initial release

data/Rakefile

@@ -1,8 +1,116 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
 
 task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end
+
+desc 'Check code style with RuboCop'
+task :rubocop do
+  sh 'bundle exec rubocop'
+end
+
+desc 'Auto-correct RuboCop offenses'
+task :rubocop_fix do
+  sh 'bundle exec rubocop -a'
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
+task :quality do
+  results = {}
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Tests + Coverage'
+  puts '=' * 60
+  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: RuboCop'
+  puts '=' * 60
+  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Flog Complexity'
+  puts '=' * 60
+  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Summary'
+  puts '=' * 60
+  results.each do |gate, status|
+    icon = status == :pass ? 'PASS' : 'FAIL'
+    puts "  [#{icon}] #{gate}"
+  end
+  puts '=' * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end

data/lib/robot_lab/ractor/version.rb

@@ -4,6 +4,6 @@ module RobotLab
   # RactorPool (not Ractor) avoids shadowing Ruby's built-in Ractor class
   # for all code within the RobotLab namespace.
   module RactorPool
-    VERSION = "0.1.0"
+    VERSION = '0.2.1'
   end
 end

data/lib/robot_lab/ractor.rb

@@ -5,16 +5,16 @@
 # code inside the RobotLab namespace, breaking Ractor.new / Ractor.make_shareable
 # calls in RactorWorkerPool, RactorNetworkScheduler, etc.
 
-require "etc"
-require "ractor_queue"
-require "ractor/wrapper"
+require 'etc'
+require 'ractor_queue'
+require 'ractor/wrapper'
 
-require_relative "ractor/version"
-require_relative "ractor_job"
-require_relative "ractor_boundary"
-require_relative "ractor_worker_pool"
-require_relative "ractor_memory_proxy"
-require_relative "ractor_network_scheduler"
+require_relative 'ractor/version'
+require_relative 'ractor_job'
+require_relative 'ractor_boundary'
+require_relative 'ractor_worker_pool'
+require_relative 'ractor_memory_proxy'
+require_relative 'ractor_network_scheduler'
 
 # Extend the RobotLab module with Ractor pool lifecycle methods.
 # Once robot_lab removes its own copies and adds robot_lab-ractor as a
@@ -23,8 +23,11 @@ module RobotLab
   class << self
     def ractor_pool
       @ractor_pool ||= begin
-        size = respond_to?(:config) && config.respond_to?(:ractor_pool_size) \
-          ? (config.ractor_pool_size || :auto) : :auto
+        size = if respond_to?(:config) && config.respond_to?(:ractor_pool_size)
+                 config.ractor_pool_size || :auto
+               else
+                 :auto
+               end
         RactorWorkerPool.new(size: size)
       end
     end
@@ -35,3 +38,7 @@ module RobotLab
     end
   end
 end
+
+if defined?(RobotLab) && RobotLab.respond_to?(:register_extension)
+  RobotLab.register_extension(:ractor, :ractor_extension_loaded)
+end

data/lib/robot_lab/ractor_boundary.rb

@@ -35,7 +35,7 @@ module RobotLab
                end
 
       Ractor.make_shareable(result)
-    rescue ::Ractor::IsolationError, ::Ractor::Error => e
+    rescue ::Ractor::Error => e
       raise RactorBoundaryError, "Cannot make value Ractor-shareable: #{e.message}"
     end
   end

data/lib/robot_lab/ractor_memory_proxy.rb

@@ -31,9 +31,7 @@ module RobotLab
 
     # Returns the Ractor-shareable stub for use inside Ractors.
     # @return [Ractor::Wrapper stub]
-    def stub
-      @stub
-    end
+    attr_reader :stub
 
     # Read a value from the proxied Memory.
     # @param key [Symbol]
@@ -61,7 +59,7 @@ module RobotLab
     def shutdown
       @wrapper.async_stop
       @wrapper.join
-    rescue => e
+    rescue StandardError => e
       warn "RactorMemoryProxy shutdown error: #{e.message}"
     end
   end

data/lib/robot_lab/ractor_network_scheduler.rb

@@ -50,21 +50,10 @@ module RobotLab
       remaining = specs_with_deps.dup
 
       until remaining.empty?
-        ready, remaining = remaining.partition do |entry|
-          deps = entry[:depends_on]
-          deps == :none || deps == :optional ||
-            Array(deps).all? { |d| completed.key?(d) }
-        end
-
-        raise RobotLab::Error, "Circular dependency or unresolvable deps in RactorNetworkScheduler" if ready.empty?
+        ready, remaining = partition_ready(remaining, completed)
+        raise RobotLab::Error, 'Circular dependency or unresolvable deps in RactorNetworkScheduler' if ready.empty?
 
-        threads = ready.map do |entry|
-          spec = entry[:spec]
-          msg  = completed.values.last || message
-          Thread.new { [spec.name, execute_spec(spec, msg)] }.tap { |t| t.report_on_exception = false }
-        end
-
-        threads.each do |t|
+        dispatch_ready(ready, completed, message).each do |t|
           name, result = t.value
           completed[name] = result
         end
@@ -79,7 +68,38 @@ module RobotLab
 
       @closed = true
       @size.times { @work_q.push(nil) }
-      @workers.each { |w| w.join rescue nil }
+      @workers.each do |w|
+        w.join
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Called inside Ractor worker blocks — must be a class method.
+    def self.process_job(job)
+      spec    = job.payload[:spec]
+      message = job.payload[:message]
+      job.reply_queue.push(build_and_run_robot(spec, message))
+    rescue StandardError => e
+      job.reply_queue.push(wrap_error(e))
+    end
+
+    def self.build_and_run_robot(spec, message)
+      config = spec.config_hash.empty? ? nil : RobotLab::RunConfig.new(**spec.config_hash.transform_keys(&:to_sym))
+      robot  = RobotLab::Robot.new(
+        name: spec.name,
+        template: spec.template&.to_sym,
+        system_prompt: spec.system_prompt,
+        config: config
+      )
+      robot.run(message).last_text_content.to_s.freeze
+    end
+
+    def self.wrap_error(err)
+      RobotLab::RactorJobError.new(
+        message: err.message.freeze,
+        backtrace: (err.backtrace || []).map(&:freeze).freeze
+      )
     end
 
     private
@@ -90,18 +110,16 @@ module RobotLab
       reply_q        = RactorQueue.new(capacity: 1)
 
       job = RactorJob.new(
-        id:          SecureRandom.uuid.freeze,
-        type:        :robot,
-        payload:     RactorBoundary.freeze_deep({ spec: frozen_spec, message: frozen_message }),
+        id: SecureRandom.uuid.freeze,
+        type: :robot,
+        payload: RactorBoundary.freeze_deep({ spec: frozen_spec, message: frozen_message }),
         reply_queue: reply_q
       )
 
       @work_q.push(job)
       result = reply_q.pop
 
-      if result.is_a?(RactorJobError)
-        raise RobotLab::Error, "Robot '#{spec.name}' failed in Ractor: #{result.message}"
-      end
+      raise RobotLab::Error, "Robot '#{spec.name}' failed in Ractor: #{result.message}" if result.is_a?(RactorJobError)
 
       result
     end
@@ -112,28 +130,24 @@ module RobotLab
           job = q.pop
           break if job.nil?
 
-          begin
-            spec   = job.payload[:spec]
-            message = job.payload[:message]
-
-            robot = RobotLab::Robot.new(
-              name:          spec.name,
-              template:      spec.template ? spec.template.to_sym : nil,
-              system_prompt: spec.system_prompt,
-              config:        spec.config_hash.empty? ? nil : RobotLab::RunConfig.new(**spec.config_hash.transform_keys(&:to_sym))
-            )
-
-            robot_result = robot.run(message)
-            job.reply_queue.push(robot_result.last_text_content.to_s.freeze)
-          rescue => e
-            err = RobotLab::RactorJobError.new(
-              message:   e.message.freeze,
-              backtrace: (e.backtrace || []).map(&:freeze).freeze
-            )
-            job.reply_queue.push(err)
-          end
+          RobotLab::RactorNetworkScheduler.process_job(job)
         end
       end
     end
+
+    def partition_ready(remaining, completed)
+      remaining.partition do |entry|
+        deps = entry[:depends_on]
+        deps == :none || deps == :optional || Array(deps).all? { |d| completed.key?(d) }
+      end
+    end
+
+    def dispatch_ready(ready, completed, message)
+      ready.map do |entry|
+        spec = entry[:spec]
+        msg  = completed.values.last || message
+        Thread.new { [spec.name, execute_spec(spec, msg)] }.tap { |t| t.report_on_exception = false }
+      end
+    end
   end
 end

data/lib/robot_lab/ractor_worker_pool.rb

@@ -39,27 +39,22 @@ module RobotLab
     # @return [Object] the tool's return value
     # @raise [ToolError] if the tool raises inside the Ractor
     def submit(tool_class_name, args)
-      raise ToolError, "Pool is shut down" if @closed
+      raise ToolError, 'Pool is shut down' if @closed
 
       reply_q = RactorQueue.new(capacity: 1)
-      payload = RactorBoundary.freeze_deep({
-        tool_class: tool_class_name.to_s,
-        args:       args
-      })
+      payload = RactorBoundary.freeze_deep({ tool_class: tool_class_name.to_s, args: args })
 
       job = RactorJob.new(
-        id:          SecureRandom.uuid.freeze,
-        type:        :tool,
-        payload:     payload,
+        id: SecureRandom.uuid.freeze,
+        type: :tool,
+        payload: payload,
         reply_queue: reply_q
       )
 
       @work_q.push(job)
       result = reply_q.pop
 
-      if result.is_a?(RactorJobError)
-        raise ToolError, "Tool '#{tool_class_name}' failed in Ractor: #{result.message}"
-      end
+      raise ToolError, "Tool '#{tool_class_name}' failed in Ractor: #{result.message}" if result.is_a?(RactorJobError)
 
       result
     end
@@ -71,7 +66,28 @@ module RobotLab
 
       @closed = true
       @size.times { @work_q.push(nil) }
-      @workers.each { |w| w.join rescue nil }
+      @workers.each do |w|
+        w.join
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Called inside Ractor worker blocks — must be a class method.
+    def self.process_job(job)
+      tool_class    = Object.const_get(job.payload[:tool_class])
+      result        = tool_class.new.execute(**job.payload[:args].transform_keys(&:to_sym))
+      frozen_result = ::Ractor.make_shareable(result.frozen? ? result : result.dup.freeze)
+      job.reply_queue.push(frozen_result)
+    rescue StandardError => e
+      job.reply_queue.push(wrap_error(e))
+    end
+
+    def self.wrap_error(err)
+      RobotLab::RactorJobError.new(
+        message: err.message.freeze,
+        backtrace: (err.backtrace || []).map(&:freeze).freeze
+      )
     end
 
     private
@@ -82,19 +98,7 @@ module RobotLab
           job = q.pop
           break if job.nil?
 
-          begin
-            tool_class    = Object.const_get(job.payload[:tool_class])
-            tool          = tool_class.new
-            result        = tool.execute(**job.payload[:args].transform_keys(&:to_sym))
-            frozen_result = ::Ractor.make_shareable(result.frozen? ? result : result.dup.freeze)
-            job.reply_queue.push(frozen_result)
-          rescue => e
-            err = RobotLab::RactorJobError.new(
-              message:   e.message.freeze,
-              backtrace: (e.backtrace || []).map(&:freeze).freeze
-            )
-            job.reply_queue.push(err)
-          end
+          RobotLab::RactorWorkerPool.process_job(job)
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-ractor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: robot_lab
+  name: ractor_queue
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -24,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: ractor_queue
+  name: ractor-wrapper
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -38,19 +38,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: ractor-wrapper
+  name: robot_lab
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.2.0
 description: Provides RobotLab::RactorWorkerPool — a pool of Ruby Ractor workers for
   executing CPU-bound, Ractor-safe tools in parallel. Includes RactorBoundary (deep-freeze
   utility for crossing Ractor boundaries), RactorJob/RactorJobError/RobotSpec (frozen
@@ -64,6 +64,7 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md