robot_lab 0.0.9 → 0.0.12

data/lib/robot_lab/waiter.rb

@@ -1,28 +1,26 @@
 # frozen_string_literal: true
 
 module RobotLab
-  # Thread-safe waiter for blocking get operations on Memory
+  # Thread-safe waiter for blocking get operations on Memory.
   #
-  # Waiter provides a condition variable wrapper that allows one thread
-  # to wait for a value that will be provided by another thread.
+  # Uses an IO.pipe pair instead of ConditionVariable so that
+  # IO.select integrates with the Async fiber scheduler hook.
+  # ConditionVariable#wait can block the event loop in Async
+  # contexts; IO.select yields to the scheduler correctly.
   #
-  # @example Basic usage
-  #   waiter = Waiter.new
-  #
-  #   # In thread A (waiting)
-  #   value = waiter.wait(timeout: 30)
-  #
-  #   # In thread B (signaling)
-  #   waiter.signal("the value")
+  # Multiple threads may wait on the same Waiter instance.
+  # signal() writes one byte per waiting thread so every
+  # blocked IO.select wakes exactly once.
   #
   # @api private
   class Waiter
     # Creates a new Waiter instance.
     def initialize
-      @mutex = Mutex.new
-      @condition = ConditionVariable.new
-      @value = nil
-      @signaled = false
+      @read_io, @write_io = IO.pipe
+      @mutex        = Mutex.new
+      @value        = nil
+      @signaled     = false
+      @waiter_count = 0
     end
 
     # Wait for a value to be signaled.
@@ -34,32 +32,44 @@ module RobotLab
       @mutex.synchronize do
         return @value if @signaled
 
-        if timeout
-          deadline = Time.now + timeout
-          until @signaled
-            remaining = deadline - Time.now
-            return :timeout if remaining <= 0
-            @condition.wait(@mutex, remaining)
-          end
-          @value
-        else
-          @condition.wait(@mutex) until @signaled
+        @waiter_count += 1
+      end
+
+      begin
+        ready = IO.select([@read_io], nil, nil, timeout)
+
+        @mutex.synchronize do
+          @waiter_count -= 1
+          return :timeout unless ready
+
+          @read_io.read_nonblock(1) rescue nil  # drain one wake byte
           @value
         end
+      rescue IOError
+        @mutex.synchronize { @waiter_count -= 1 }
+        :timeout
       end
     end
 
-    # Signal a value to waiting threads.
+    # Signal a value to all waiting threads.
     #
     # @param value [Object] the value to signal
     # @return [void]
     #
     def signal(value)
-      @mutex.synchronize do
-        @value = value
+      count = @mutex.synchronize do
+        @value    = value
         @signaled = true
-        @condition.broadcast
+        @waiter_count
       end
+
+      # Write one byte per waiting thread (min 1 to handle the race
+      # where a thread passed the @signaled check but hasn't entered
+      # IO.select yet — its IO.select will return immediately).
+      bytes = [count, 1].max
+      @write_io.write_nonblock("." * bytes) rescue nil
+    rescue IOError
+      # pipe already closed — signal is a no-op
     end
 
     # Check if this waiter has been signaled.
@@ -69,5 +79,15 @@ module RobotLab
     def signaled?
       @mutex.synchronize { @signaled }
     end
+
+    # Release the pipe file descriptors.
+    # Should be called after wait returns.
+    #
+    # @return [void]
+    #
+    def close
+      @read_io.close  rescue nil
+      @write_io.close rescue nil
+    end
   end
 end

data/lib/robot_lab.rb

@@ -71,6 +71,7 @@ loader.setup
 require_relative 'robot_lab/error'
 require_relative 'robot_lab/message'
 require_relative 'robot_lab/memory'
+require_relative 'robot_lab/ractor_job'
 
 # Eager load everything in Rails or when explicitly requested.
 # Otherwise Zeitwerk's lazy autoloading keeps boot fast.
@@ -218,6 +219,30 @@ module RobotLab
     def create_memory(data: {}, enable_cache: true, **options)
       Memory.new(data: data, enable_cache: enable_cache, **options)
     end
+
+
+    # Returns the shared RactorWorkerPool, lazily initialized.
+    #
+    # Pool size is determined by RobotLab.config.ractor_pool_size or
+    # defaults to Etc.nprocessors (:auto). The pool lives for the lifetime
+    # of the process. Call RobotLab.shutdown_ractor_pool to drain and
+    # close it explicitly.
+    #
+    # @return [RactorWorkerPool]
+    def ractor_pool
+      @ractor_pool ||= begin
+        size = config.respond_to?(:ractor_pool_size) ? (config.ractor_pool_size || :auto) : :auto
+        RactorWorkerPool.new(size: size)
+      end
+    end
+
+    # Shut down the shared Ractor worker pool, draining in-flight jobs.
+    #
+    # @return [void]
+    def shutdown_ractor_pool
+      @ractor_pool&.shutdown
+      @ractor_pool = nil
+    end
   end
 end
 

data/mkdocs.yml

@@ -170,6 +170,7 @@ nav:
       - Streaming Responses: guides/streaming.md
       - Memory System: guides/memory.md
       - Rails Integration: guides/rails-integration.md
+      - Ractor Parallelism: guides/ractor-parallelism.md
   - API Reference:
       - api/index.md
       - Core Classes:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.12
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -163,6 +163,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: ractor_queue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ractor-wrapper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -216,9 +244,11 @@ files:
 - docs/api/core/index.md
 - docs/api/core/memory.md
 - docs/api/core/network.md
+- docs/api/core/result.md
 - docs/api/core/robot.md
 - docs/api/core/state.md
 - docs/api/core/tool.md
+- docs/api/errors.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md
@@ -254,12 +284,17 @@ files:
 - docs/guides/building-robots.md
 - docs/guides/creating-networks.md
 - docs/guides/index.md
+- docs/guides/knowledge.md
 - docs/guides/mcp-integration.md
 - docs/guides/memory.md
+- docs/guides/observability.md
+- docs/guides/ractor-parallelism.md
 - docs/guides/rails-integration.md
 - docs/guides/streaming.md
 - docs/guides/using-tools.md
 - docs/index.md
+- docs/superpowers/plans/2026-04-14-ractor-integration.md
+- docs/superpowers/specs/2026-04-14-ractor-integration-design.md
 - examples/01_simple_robot.rb
 - examples/02_tools.rb
 - examples/03_network.rb
@@ -343,6 +378,24 @@ files:
 - examples/18_rails/config/initializers/robot_lab.rb
 - examples/18_rails/config/routes.rb
 - examples/18_rails/db/migrate/001_create_robot_lab_tables.rb
+- examples/19_token_tracking.rb
+- examples/20_circuit_breaker.rb
+- examples/21_learning_loop.rb
+- examples/22_context_compression.rb
+- examples/23_convergence.rb
+- examples/24_structured_delegation.rb
+- examples/25_history_search.rb
+- examples/25_history_search/conversation.jsonl
+- examples/26_document_store.rb
+- examples/26_document_store/api_versioning_adr.md
+- examples/26_document_store/incident_postmortem.md
+- examples/26_document_store/postgres_runbook.md
+- examples/26_document_store/redis_caching_guide.md
+- examples/26_document_store/sidekiq_guide.md
+- examples/27_incident_response/incident_response.rb
+- examples/28_mcp_discovery.rb
+- examples/29_ractor_tools.rb
+- examples/30_ractor_network.rb
 - examples/README.md
 - examples/prompts/assistant.md
 - examples/prompts/audit_trail.md
@@ -382,7 +435,10 @@ files:
 - examples/prompts/skill_nested_test.md
 - examples/prompts/skill_refs_main_test.md
 - examples/prompts/skill_self_ref_test.md
+- examples/prompts/skill_with_mcp_test.md
 - examples/prompts/skill_with_params_test.md
+- examples/prompts/skill_with_robot_name_test.md
+- examples/prompts/skill_with_tools_test.md
 - examples/prompts/sre_compliance.md
 - examples/prompts/structured_output.md
 - examples/prompts/synthesizer.md
@@ -401,11 +457,18 @@ files:
 - lib/generators/robot_lab/templates/thread_model.rb.tt
 - lib/robot_lab.rb
 - lib/robot_lab/ask_user.rb
+- lib/robot_lab/bus_poller.rb
 - lib/robot_lab/config.rb
 - lib/robot_lab/config/defaults.yml
+- lib/robot_lab/convergence.rb
+- lib/robot_lab/delegation_future.rb
+- lib/robot_lab/document_store.rb
 - lib/robot_lab/error.rb
+- lib/robot_lab/history_compressor.rb
 - lib/robot_lab/mcp/client.rb
+- lib/robot_lab/mcp/connection_poller.rb
 - lib/robot_lab/mcp/server.rb
+- lib/robot_lab/mcp/server_discovery.rb
 - lib/robot_lab/mcp/transports/base.rb
 - lib/robot_lab/mcp/transports/sse.rb
 - lib/robot_lab/mcp/transports/stdio.rb
@@ -415,11 +478,17 @@ files:
 - lib/robot_lab/memory_change.rb
 - lib/robot_lab/message.rb
 - lib/robot_lab/network.rb
+- lib/robot_lab/ractor_boundary.rb
+- lib/robot_lab/ractor_job.rb
+- lib/robot_lab/ractor_memory_proxy.rb
+- lib/robot_lab/ractor_network_scheduler.rb
+- lib/robot_lab/ractor_worker_pool.rb
 - lib/robot_lab/rails_integration/engine.rb
 - lib/robot_lab/rails_integration/railtie.rb
 - lib/robot_lab/rails_integration/turbo_stream_callbacks.rb
 - lib/robot_lab/robot.rb
 - lib/robot_lab/robot/bus_messaging.rb
+- lib/robot_lab/robot/history_search.rb
 - lib/robot_lab/robot/mcp_management.rb
 - lib/robot_lab/robot/template_rendering.rb
 - lib/robot_lab/robot_message.rb
@@ -430,6 +499,7 @@ files:
 - lib/robot_lab/streaming/events.rb
 - lib/robot_lab/streaming/sequence_counter.rb
 - lib/robot_lab/task.rb
+- lib/robot_lab/text_analysis.rb
 - lib/robot_lab/tool.rb
 - lib/robot_lab/tool_config.rb
 - lib/robot_lab/tool_manifest.rb
@@ -464,7 +534,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby framework for building and orchestrating multi-robot LLM workflows
 test_files: []