robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/tool.rb

@@ -94,19 +94,17 @@ module RobotLab
     # @param args [Hash] the tool arguments from the LLM
     # @return [Object] the tool result or an error string
     def call(args)
-      if self.class.ractor_safe? && !self.class.name.nil?
-        RobotLab.ractor_pool.submit(self.class.name, args)
-      else
-        super
+      context = ToolCallHookContext.new(tool: self, tool_args: args, robot: @robot)
+
+      RobotLab::Hooks.run(:tool_call, context, **tool_hook_options) do
+        context.tool_result = use_ractor_pool? ? execute_ractor_tool_call(args) : super
+      rescue RobotLab::ToolError => e
+        handle_tool_error(context, e)
+      rescue StandardError => e
+        handle_standard_error(context, e)
       end
-    rescue RobotLab::ToolError => e
-      raise if self.class.raise_on_error?
-      "Error (#{name}): #{e.message}"
-    rescue StandardError => e
-      raise if self.class.raise_on_error?
 
-      RobotLab.config.logger.warn("Tool '#{name}' error: #{e.class}: #{e.message}")
-      "Error (#{name}): #{e.message}"
+      context.tool_result
     end
 
     # Override name to support explicit names for dynamic/MCP tools.
@@ -204,12 +202,55 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String]
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     private
 
+    def tool_hook_options
+      hook_scope = RobotLab.current_hook_scope
+
+      {
+        registries: tool_hook_registries(hook_scope),
+        per_run_hooks: hook_scope && hook_scope[:per_run_hooks]
+      }
+    end
+
+    def tool_hook_registries(hook_scope)
+      return hook_scope[:registries] if hook_scope
+
+      [RobotLab.hooks, robot_hook_registry]
+    end
+
+    def robot_hook_registry
+      @robot.hooks if @robot.respond_to?(:hooks)
+    end
+
+    def execute_ractor_tool_call(args)
+      RobotLab.ractor_pool.submit(self.class.name, args)
+    end
+
+    def use_ractor_pool?
+      self.class.ractor_safe? && !self.class.name.nil? && RobotLab.extension_loaded?(:ractor)
+    end
+
+    def handle_tool_error(context, error)
+      context.tool_error = error
+      raise if self.class.raise_on_error?
+
+      suffix = RobotLab::Errors.retryable?(error) ? " (retryable)" : ""
+      context.tool_result = "Error (#{name}): #{error.message}#{suffix}"
+    end
+
+    def handle_standard_error(context, error)
+      context.tool_error = error
+      raise if self.class.raise_on_error?
+
+      RobotLab.config.logger.warn("Tool '#{name}' error: #{error.class}: #{error.message}")
+      context.tool_result = "Error (#{name}): #{error.message}"
+    end
+
     def deep_symbolize_keys(obj)
       case obj
       when Hash

data/lib/robot_lab/tool_config.rb

@@ -94,7 +94,7 @@ module RobotLab
       def filter_tools(tools, allowed_names:)
         return [] if allowed_names.empty?
 
-        allowed_set = allowed_names.map(&:to_s).to_set
+        allowed_set = allowed_names.to_set(&:to_s)
         tools.select { |tool| allowed_set.include?(tool_name(tool)) }
       end
 

data/lib/robot_lab/tool_manifest.rb

@@ -142,8 +142,8 @@ module RobotLab
     #
     # @yield [Tool] Each tool in the manifest
     #
-    def each(&block)
-      @tools.values.each(&block)
+    def each(&)
+      @tools.values.each(&)
     end
 
     # Clear all tools
@@ -173,9 +173,7 @@ module RobotLab
     #
     def merge(other)
       case other
-      when ToolManifest
-        other.each { |tool| add(tool) }
-      when Array
+      when ToolManifest, Array
         other.each { |tool| add(tool) }
       when Tool
         add(other)
@@ -194,8 +192,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Create manifest from hash of tool definitions

data/lib/robot_lab/user_message.rb

@@ -84,8 +84,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Create from string or hash

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.1.0"
+  VERSION = "0.2.6"
 end

data/lib/robot_lab/waiter.rb

@@ -36,7 +36,7 @@ module RobotLab
       end
 
       begin
-        ready = IO.select([@read_io], nil, nil, timeout)
+        ready = @read_io.wait_readable(timeout)
 
         @mutex.synchronize do
           @waiter_count -= 1

data/lib/robot_lab.rb

@@ -6,9 +6,6 @@ require 'securerandom'
 require 'digest'
 
 # Core dependencies
-# ActiveSupport delegation is required by ruby_llm (RubyLLM::Agent uses delegate)
-# but not declared in ruby_llm's gemspec. Load it before ruby_llm.
-require 'active_support/core_ext/module/delegation'
 require 'ruby_llm'
 require 'prompt_manager'
 require 'async'
@@ -49,8 +46,6 @@ module RobotLab
 end
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
-loader.ignore("#{__dir__}/generators")
-loader.ignore("#{__dir__}/robot_lab/rails_integration")
 loader.ignore("#{__dir__}/robot_lab/robot")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
@@ -69,9 +64,12 @@ loader.setup
 # individually (e.g. TextMessage lives in message.rb, not text_message.rb).
 # Require them explicitly so their constants are available without eager loading.
 require_relative 'robot_lab/error'
+require_relative 'robot_lab/hook_context'
+require_relative 'robot_lab/hook'
+require_relative 'robot_lab/hook_registry'
+require_relative 'robot_lab/hooks'
 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.
@@ -80,7 +78,68 @@ loader.eager_load if defined?(Rails::Engine) || ENV["ROBOT_LAB_EAGER_LOAD"]
 module RobotLab
   # Error classes are defined in lib/robot_lab/error.rb
 
+  @extensions = {}
+
   class << self
+    # Registers an extension gem so core can detect it without depending on it.
+    #
+    # Extension gems call this at load time to announce themselves. Core uses
+    # extension_loaded? to guard optional behavior instead of defined?/respond_to?.
+    #
+    # @param name [Symbol] identifier for the extension (e.g. :durable, :ractor)
+    # @param mod [Module, Object] the extension's primary module or a sentinel value
+    def register_extension(name, mod)
+      @extensions[name] = mod
+    end
+
+    # Returns true if the named extension gem has been loaded.
+    #
+    # @param name [Symbol] extension identifier
+    def extension_loaded?(name)
+      @extensions.key?(name)
+    end
+
+    # Returns the module registered for the named extension, or nil.
+    #
+    # @param name [Symbol] extension identifier
+    def extension(name)
+      @extensions[name]
+    end
+
+    # Returns the list of registered extension names.
+    #
+    # @return [Array<Symbol>]
+    def loaded_extensions
+      @extensions.keys
+    end
+
+    def hooks
+      @hooks ||= HookRegistry.new
+    end
+
+    def on(handler_class, context: nil)
+      hooks.on(handler_class, context: context)
+    end
+
+    def clear_hooks!
+      @hooks = HookRegistry.new
+    end
+
+    def with_hook_scope(registries, per_run_hooks)
+      previous = Thread.current[:robot_lab_hook_scope]
+      Thread.current[:robot_lab_hook_scope] = {
+        registries: registries,
+        per_run_hooks: per_run_hooks
+      }
+      yield
+    ensure
+      Thread.current[:robot_lab_hook_scope] = previous
+    end
+
+    def current_hook_scope
+      Thread.current[:robot_lab_hook_scope]
+    end
+
     # Returns the Config object (MywayConfig-based).
     #
     # Configuration is automatically loaded from:
@@ -100,7 +159,6 @@ module RobotLab
       @config ||= Config.new.tap(&:after_load)
     end
 
-
     # Yields the Config object for block-style configuration.
     #
     # @yield [Config] the config instance
@@ -114,7 +172,6 @@ module RobotLab
       yield config
     end
 
-
     # Reload configuration from all sources.
     #
     # Clears the cached Config instance, forcing it to be
@@ -126,6 +183,23 @@ module RobotLab
       config
     end
 
+    # Render a named prompt template to a String using the configured template
+    # library (the prompts_dir from config / ROBOT_LAB_TEMPLATE_PATH). Front
+    # matter parameters are supplied as keyword arguments.
+    #
+    # Unlike #build (which renders a template as a robot's *system prompt*), this
+    # returns the plain text, so callers can use it as a task, a message, or a
+    # grading rubric.
+    #
+    # @param name [Symbol, String] template id (filename without extension)
+    # @param context [Hash] values for the template's parameters
+    # @return [String] the rendered prompt text
+    #
+    # @example
+    #   RobotLab.render_template(:objective, topic: "commit messages")
+    def render_template(name, **context)
+      PM.parse(name.to_sym).to_s(**context)
+    end
 
     # Factory method to create a new Robot instance.
     #
@@ -153,7 +227,8 @@ module RobotLab
     #     name: "helper",
     #     system_prompt: "You are a helpful assistant."
     #   )
-    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil, **options)
+    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil,
+              config: nil, **)
       Robot.new(
         name: name,
         template: template,
@@ -163,11 +238,10 @@ module RobotLab
         bus: bus,
         skills: skills,
         config: config,
-        **options
+        **
       )
     end
 
-
     # Factory method to create a new Network of robots.
     #
     # @param name [String] the unique identifier for the network
@@ -195,11 +269,10 @@ module RobotLab
     #     step :entities, entity_bot, depends_on: [:fetch]
     #     step :merge, merger, depends_on: [:sentiment, :entities]
     #   end
-    def create_network(name:, concurrency: :auto, config: nil, &block)
-      Network.new(name: name, concurrency: concurrency, config: config, &block)
+    def create_network(name:, concurrency: :auto, config: nil, &)
+      Network.new(name: name, concurrency: concurrency, config: config, &)
     end
 
-
     # Factory method to create a new Memory object.
     #
     # @param data [Hash] initial runtime data
@@ -216,43 +289,8 @@ module RobotLab
     #
     # @example Memory with caching disabled
     #   memory = RobotLab.create_memory(data: {}, enable_cache: false)
-    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
+    def create_memory(data: {}, enable_cache: true, **)
+      Memory.new(data: data, enable_cache: enable_cache, **)
     end
   end
 end
-
-# Load Rails integration if Rails is defined
-if defined?(Rails::Engine)
-  require 'robot_lab/rails_integration/engine'
-  require 'robot_lab/rails_integration/railtie'
-  require 'robot_lab/rails_integration/turbo_stream_callbacks'
-  require 'robot_lab/rails_integration/job'
-
-  # Convenience alias so job subclasses can inherit from RobotLab::Job
-  RobotLab::Job = RobotLab::RailsIntegration::Job
-end

data/logfile

@@ -0,0 +1,8 @@
+2026-02-25 20:56:30.644 CST [47152] LOG:  starting PostgreSQL 18.2 (Homebrew) on aarch64-apple-darwin25.2.0, compiled by Apple clang version 17.0.0 (clang-1700.6.3.2), 64-bit
+2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv6 address "::1": Address already in use
+2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
+2026-02-25 20:56:30.646 CST [47152] LOG:  could not bind IPv4 address "127.0.0.1": Address already in use
+2026-02-25 20:56:30.646 CST [47152] HINT:  Is another postmaster already running on port 5432? If not, wait a few seconds and retry.
+2026-02-25 20:56:30.646 CST [47152] WARNING:  could not create listen socket for "localhost"
+2026-02-25 20:56:30.646 CST [47152] FATAL:  could not create any TCP/IP sockets
+2026-02-25 20:56:30.646 CST [47152] LOG:  database system is shut down

data/mkdocs.yml

@@ -169,8 +169,9 @@ nav:
       - MCP Integration: guides/mcp-integration.md
       - Streaming Responses: guides/streaming.md
       - Memory System: guides/memory.md
-      - Rails Integration: guides/rails-integration.md
-      - Ractor Parallelism: guides/ractor-parallelism.md
+      - Observability & Safety: guides/observability.md
+      - Hook System: guides/hooks.md
+      - Knowledge Search: guides/knowledge.md
   - API Reference:
       - api/index.md
       - Core Classes:
@@ -201,4 +202,3 @@ nav:
       - Multi-Robot Network: examples/multi-robot-network.md
       - Tool Usage: examples/tool-usage.md
       - MCP Server: examples/mcp-server.md
-      - Rails Application: examples/rails-application.md

data/robot_concurrency.md

@@ -0,0 +1,38 @@
+# Ruby Concurrency Review — RobotLab
+
+Source: https://paolino.me/ruby-concurrency-what-actually-happens/
+
+## What Applies to RobotLab
+
+### 1. You're Already in the Right Model — Lean Into It
+
+RobotLab uses `async (~> 2.0)`, which is exactly the fiber-based scheduler the article describes. LLM calls are pure I/O-bound work (HTTP streaming), so fibers are the correct and lowest-cost primitive. The article validates this architecture choice. No changes needed here — but be deliberate about not mixing blocking thread-style calls into the `Async` reactor unnecessarily.
+
+### 2. The Ractor Caution Is Real (Recent Commit: `feat(ractor-parallelism)`)
+
+The article is clear: Ractors in Ruby 4.0 are still experimental and practically incompatible with gems that use global state. RobotLab's dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`) almost certainly use global state. Worth auditing whether the new Ractor code hits `Ractor::IsolationError` under realistic load. The article's recommendation: **use Processes** for CPU parallelism if Rails-style gems are involved.
+
+### 3. ~~The `Waiter` Class May Be Misfit in Fiber Context~~ — RESOLVED
+
+`lib/robot_lab/waiter.rb` was updated to use `IO.pipe` + `IO.select` instead of `ConditionVariable`. `IO.select` is hooked by the Ruby 3.1+ fiber scheduler protocol, so it correctly yields to the Async scheduler when called from within an Async task, and correctly blocks the calling thread when used outside one. `Async::Condition` was considered but rejected: it only works inside an Async block, whereas `Memory` is intentionally usable from both plain threads and Async fibers.
+
+### 4. Parallel Network Execution — Check the Primitive
+
+`call_parallel()` in `Network` (built on `SimpleFlow::Pipeline`) — if it spawns OS threads rather than async tasks, you get heavier overhead than necessary for I/O-bound robot calls. The article's guidance: for I/O work, fiber-based `Async::Barrier` with concurrent tasks is 10-20x cheaper than threads.
+
+### 5. Resource Semaphores for Parallel Networks
+
+When a Network runs multiple robots concurrently, each making LLM API calls, you can exhaust API rate limits or connection pools with no back-pressure. The article's semaphore pattern applies directly — cap in-flight robot tasks to match your API tier's concurrency limit. This is worth adding to `RunConfig` as a `max_concurrent_robots` infra field.
+
+### 6. Colorless Concurrency — This Is Already Your Story
+
+The article's main point about Ruby fibers being "colorless" (no `async/await` propagation required) is directly reflected in how `robot.run("...")` stays synchronous-looking whether run standalone or in a parallel network. This is an underappreciated design strength worth highlighting in docs/README.
+
+---
+
+## Summary
+
+The async/fiber architecture is correct for LLM I/O work. The two actionable concerns are:
+
+1. **Audit the Ractor code** for isolation errors with gem dependencies (`ruby_llm`, `prompt_manager`, `zeitwerk`).
+2. **Check `Waiter`** (condition variable in `lib/robot_lab/waiter.rb`) — if called inside an `Async` reactor block, replace with `Async::Condition` to avoid stalling the reactor.