robot_lab 0.0.4 → 0.0.6

data/lib/robot_lab/run_config.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Shared configuration object for LLM, tools, callbacks, and infrastructure.
+  #
+  # RunConfig provides a unified way to express operational defaults that flow
+  # through the configuration hierarchy:
+  #
+  #   RobotLab.config -> Network -> Robot -> Template front matter -> Task -> Runtime
+  #
+  # Only explicitly set values are stored. Merge semantics: the more-specific
+  # config's non-nil values win over the less-specific config.
+  #
+  # @example Keyword construction
+  #   config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.7)
+  #
+  # @example Block DSL
+  #   config = RunConfig.new do |c|
+  #     c.model "claude-sonnet-4"
+  #     c.temperature 0.7
+  #   end
+  #
+  # @example Merge (more-specific wins)
+  #   network_config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+  #   robot_config   = RunConfig.new(temperature: 0.9)
+  #   effective       = network_config.merge(robot_config)
+  #   effective.temperature  #=> 0.9
+  #   effective.model        #=> "claude-sonnet-4"
+  #
+  class RunConfig
+    # LLM configuration fields (applied to chat via with_* methods)
+    LLM_FIELDS = %i[
+      model temperature top_p top_k max_tokens
+      presence_penalty frequency_penalty stop
+    ].freeze
+
+    # Tool-related fields
+    TOOL_FIELDS = %i[mcp tools].freeze
+
+    # Callback fields (Procs)
+    CALLBACK_FIELDS = %i[on_tool_call on_tool_result].freeze
+
+    # Infrastructure fields
+    INFRA_FIELDS = %i[bus enable_cache].freeze
+
+    # All recognized fields
+    FIELDS = (LLM_FIELDS + TOOL_FIELDS + CALLBACK_FIELDS + INFRA_FIELDS).freeze
+
+    # Fields that cannot be serialized to JSON (Procs, IO objects, etc.)
+    NON_SERIALIZABLE_FIELDS = (CALLBACK_FIELDS + %i[bus]).freeze
+
+    # Creates a new RunConfig.
+    #
+    # @param kwargs [Hash] field values to set
+    # @yield [self] optional block for DSL-style configuration
+    def initialize(**kwargs)
+      @fields = {}
+
+      kwargs.each do |key, value|
+        set(key, value)
+      end
+
+      yield self if block_given?
+    end
+
+    # Define getter/setter DSL methods for each field.
+    #
+    # With no arguments: returns the current value (getter).
+    # With one argument: sets the value and returns self (chainable setter).
+    FIELDS.each do |field|
+      define_method(field) do |value = :__unset__|
+        if value == :__unset__
+          @fields[field]
+        else
+          set(field, value)
+          self
+        end
+      end
+    end
+
+    # Returns a duplicate of the internal fields hash.
+    #
+    # @return [Hash] only the fields that have been explicitly set
+    def to_h
+      @fields.dup
+    end
+
+
+    # Returns a JSON-safe hash (skips Procs, IO, and other non-serializable values).
+    #
+    # @return [Hash]
+    def to_json_hash
+      @fields.reject { |k, _| NON_SERIALIZABLE_FIELDS.include?(k) }
+    end
+
+
+    # Merges another RunConfig (or Hash) on top of this one.
+    # The other's non-nil values win. Returns a new RunConfig.
+    #
+    # @param other [RunConfig, Hash] the more-specific configuration
+    # @return [RunConfig] a new merged RunConfig
+    def merge(other)
+      other_hash = other.is_a?(RunConfig) ? other.to_h : other
+      merged = @fields.merge(other_hash) { |_k, old_v, new_v| new_v.nil? ? old_v : new_v }
+      self.class.new(**merged)
+    end
+
+
+    # Applies LLM fields to a chat object via its with_* methods.
+    #
+    # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
+    def apply_to(chat)
+      LLM_FIELDS.each do |field|
+        value = @fields[field]
+        next unless value
+
+        method = :"with_#{field}"
+        chat.public_send(method, value) if chat.respond_to?(method)
+      end
+    end
+
+
+    # Build a RunConfig from prompt_manager front matter metadata.
+    #
+    # @param metadata [Object] a PM::Metadata object (responds to field names)
+    # @return [RunConfig]
+    def self.from_front_matter(metadata)
+      fields = {}
+
+      LLM_FIELDS.each do |key|
+        value = metadata.respond_to?(key) ? metadata.send(key) : nil
+        fields[key] = value if value
+      end
+
+      # Extract tool-related fields
+      %i[mcp tools].each do |key|
+        value = metadata.respond_to?(key) ? metadata.send(key) : nil
+        fields[key] = value if value
+      end
+
+      new(**fields)
+    end
+
+
+    # @return [Boolean] true if no fields have been set
+    def empty?
+      @fields.empty?
+    end
+
+
+    # @param field [Symbol] the field name
+    # @return [Boolean] true if the field has been explicitly set
+    def key?(field)
+      @fields.key?(field)
+    end
+
+
+    # @param other [RunConfig] the other RunConfig to compare
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(RunConfig) && to_h == other.to_h
+    end
+
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@fields.inspect}>"
+    end
+
+    private
+
+    # Validates and stores a field value. Nil removes the key.
+    def set(field, value)
+      field = field.to_sym
+      raise ArgumentError, "Unknown RunConfig field: #{field}" unless FIELDS.include?(field)
+
+      if value.nil?
+        @fields.delete(field)
+      else
+        @fields[field] = value
+      end
+    end
+  end
+end

data/lib/robot_lab/state_proxy.rb

@@ -16,6 +16,8 @@ module RobotLab
   #   proxy.to_h        # => { count: 1, name: "test" }
   #
   class StateProxy
+    include Utils
+
     # Creates a new StateProxy.
     #
     # @param data [Hash] the initial data
@@ -172,17 +174,5 @@ module RobotLab
       "#<RobotLab::StateProxy #{@data.inspect}>"
     end
 
-    private
-
-    def deep_dup(obj)
-      case obj
-      when Hash
-        obj.transform_values { |v| deep_dup(v) }
-      when Array
-        obj.map { |v| deep_dup(v) }
-      else
-        obj.dup rescue obj
-      end
-    end
   end
 end

data/lib/robot_lab/task.rb

@@ -39,13 +39,14 @@ module RobotLab
     # @param tools [Symbol, Array] tools config (:none, :inherit, or array)
     # @param memory [Memory, Hash, nil] task-specific memory
     #
-    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil)
+    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil, config: nil)
       @name = name.to_sym
       @robot = robot
       @context = context
       @mcp = mcp
       @tools = tools
       @memory = memory
+      @config = config
     end
 
     # SimpleFlow step interface
@@ -68,6 +69,12 @@ module RobotLab
       run_params[:tools] = @tools unless @tools == :none
       run_params[:memory] = @memory if @memory
 
+      # Merge task's config on top of network's config
+      if @config
+        network_rc = run_params[:network_config]
+        run_params[:network_config] = network_rc ? network_rc.merge(@config) : @config
+      end
+
       # Create enhanced result with merged params
       enhanced_result = result.with_context(:run_params, run_params)
 

data/lib/robot_lab/utils.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Shared utility methods used across multiple classes.
+  #
+  # Include this module to get `dispatch_async` and `deep_dup`
+  # as private instance methods.
+  module Utils
+    private
+
+    # Dispatch a block asynchronously using Async fibers.
+    #
+    # When already inside an Async reactor, creates a child task.
+    # Otherwise, creates a temporary reactor that runs the block
+    # and cleans up automatically.
+    def dispatch_async(&block)
+      Async do
+        block.call
+      rescue => e
+        RobotLab.config.logger.error("dispatch_async error: #{e.class}: #{e.message}")
+      end
+    end
+
+    # Deep-duplicate a nested Hash/Array structure.
+    #
+    # @param obj [Object] the object to duplicate
+    # @return [Object] the deep copy
+    def deep_dup(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| deep_dup(v) }
+      when Array
+        obj.map { |v| deep_dup(v) }
+      else
+        obj.dup rescue obj
+      end
+    end
+  end
+end

data/lib/robot_lab/version.rb

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

data/lib/robot_lab.rb

@@ -51,11 +51,11 @@ end
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/robot_lab/rails")
+loader.ignore("#{__dir__}/robot_lab/robot")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
 loader.inflector.inflect(
   'robot_lab' => 'RobotLab',
-  'robotic_model' => 'RoboticModel',
   'mcp' => 'MCP',
   'openai' => 'OpenAI',
   'sse' => 'SSE',
@@ -63,12 +63,18 @@ loader.inflector.inflect(
   'websocket' => 'WebSocket'
 )
 
-# NOTE: adapters/ is NOT collapsed since files define RobotLab::Adapters::* classes
-
 loader.setup
 
-# Eager load for proper constant resolution
-loader.eager_load
+# These files define multiple classes that Zeitwerk cannot autoload
+# 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/message'
+require_relative 'robot_lab/memory'
+
+# Eager load everything in Rails or when explicitly requested.
+# Otherwise Zeitwerk's lazy autoloading keeps boot fast.
+loader.eager_load if defined?(Rails::Engine) || ENV["ROBOT_LAB_EAGER_LOAD"]
 
 module RobotLab
   # Error classes are defined in lib/robot_lab/error.rb
@@ -94,6 +100,20 @@ module RobotLab
     end
 
 
+    # Yields the Config object for block-style configuration.
+    #
+    # @yield [Config] the config instance
+    # @return [Config] the config instance
+    #
+    # @example
+    #   RobotLab.configure do |c|
+    #     c.default_model = "claude-sonnet-4"
+    #   end
+    def configure
+      yield config
+    end
+
+
     # Reload configuration from all sources.
     #
     # Clears the cached Config instance, forcing it to be
@@ -132,7 +152,7 @@ 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, **options)
+    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, config: nil, **options)
       Robot.new(
         name: name,
         template: template,
@@ -140,6 +160,7 @@ module RobotLab
         context: context,
         enable_cache: enable_cache,
         bus: bus,
+        config: config,
         **options
       )
     end
@@ -172,8 +193,8 @@ module RobotLab
     #     step :entities, entity_bot, depends_on: [:fetch]
     #     step :merge, merger, depends_on: [:sentiment, :entities]
     #   end
-    def create_network(name:, concurrency: :auto, &block)
-      Network.new(name: name, concurrency: concurrency, &block)
+    def create_network(name:, concurrency: :auto, config: nil, &block)
+      Network.new(name: name, concurrency: concurrency, config: config, &block)
     end
 
 

data/mkdocs.yml

@@ -168,7 +168,6 @@ nav:
       - Using Tools: guides/using-tools.md
       - MCP Integration: guides/mcp-integration.md
       - Streaming Responses: guides/streaming.md
-      - Conversation History: guides/history.md
       - Memory System: guides/memory.md
       - Rails Integration: guides/rails-integration.md
   - API Reference:
@@ -186,11 +185,6 @@ nav:
           - TextMessage: api/messages/text-message.md
           - ToolCallMessage: api/messages/tool-call-message.md
           - ToolResultMessage: api/messages/tool-result-message.md
-      - Adapters:
-          - api/adapters/index.md
-          - Anthropic: api/adapters/anthropic.md
-          - OpenAI: api/adapters/openai.md
-          - Gemini: api/adapters/gemini.md
       - MCP:
           - api/mcp/index.md
           - Client: api/mcp/client.md
@@ -200,11 +194,6 @@ nav:
           - api/streaming/index.md
           - Context: api/streaming/context.md
           - Events: api/streaming/events.md
-      - History:
-          - api/history/index.md
-          - Config: api/history/config.md
-          - ThreadManager: api/history/thread-manager.md
-          - ActiveRecordAdapter: api/history/active-record-adapter.md
   - Examples:
       - examples/index.md
       - Basic Chat: examples/basic-chat.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -227,20 +227,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/api/adapters/anthropic.md
-- docs/api/adapters/gemini.md
-- docs/api/adapters/index.md
-- docs/api/adapters/openai.md
 - docs/api/core/index.md
 - docs/api/core/memory.md
 - docs/api/core/network.md
 - docs/api/core/robot.md
 - docs/api/core/state.md
 - docs/api/core/tool.md
-- docs/api/history/active-record-adapter.md
-- docs/api/history/config.md
-- docs/api/history/index.md
-- docs/api/history/thread-manager.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md
@@ -275,7 +267,6 @@ files:
 - docs/getting-started/quick-start.md
 - docs/guides/building-robots.md
 - docs/guides/creating-networks.md
-- docs/guides/history.md
 - docs/guides/index.md
 - docs/guides/mcp-integration.md
 - docs/guides/memory.md
@@ -322,6 +313,15 @@ files:
 - examples/15_memory_network_and_bus/prompts/os_advocate.md
 - examples/15_memory_network_and_bus/prompts/os_chief.md
 - examples/15_memory_network_and_bus/prompts/os_editor.md
+- examples/16_writers_room/display.rb
+- examples/16_writers_room/output/.gitignore
+- examples/16_writers_room/output/opus_001.md
+- examples/16_writers_room/output/opus_001_notes.log
+- examples/16_writers_room/prompts/writer.md
+- examples/16_writers_room/room.rb
+- examples/16_writers_room/tools.rb
+- examples/16_writers_room/writer.rb
+- examples/16_writers_room/writers_room.rb
 - examples/README.md
 - examples/prompts/assistant.md
 - examples/prompts/billing.md
@@ -359,19 +359,10 @@ files:
 - lib/generators/robot_lab/templates/routing_robot.rb.tt
 - lib/generators/robot_lab/templates/thread_model.rb.tt
 - lib/robot_lab.rb
-- lib/robot_lab/adapters/anthropic.rb
-- lib/robot_lab/adapters/base.rb
-- lib/robot_lab/adapters/gemini.rb
-- lib/robot_lab/adapters/openai.rb
-- lib/robot_lab/adapters/registry.rb
 - lib/robot_lab/ask_user.rb
 - lib/robot_lab/config.rb
 - lib/robot_lab/config/defaults.yml
 - lib/robot_lab/error.rb
-- lib/robot_lab/errors.rb
-- lib/robot_lab/history/active_record_adapter.rb
-- lib/robot_lab/history/config.rb
-- lib/robot_lab/history/thread_manager.rb
 - lib/robot_lab/mcp/client.rb
 - lib/robot_lab/mcp/server.rb
 - lib/robot_lab/mcp/transports/base.rb
@@ -386,9 +377,12 @@ files:
 - lib/robot_lab/rails/engine.rb
 - lib/robot_lab/rails/railtie.rb
 - lib/robot_lab/robot.rb
+- lib/robot_lab/robot/bus_messaging.rb
+- lib/robot_lab/robot/mcp_management.rb
+- lib/robot_lab/robot/template_rendering.rb
 - lib/robot_lab/robot_message.rb
 - lib/robot_lab/robot_result.rb
-- lib/robot_lab/robotic_model.rb
+- lib/robot_lab/run_config.rb
 - lib/robot_lab/state_proxy.rb
 - lib/robot_lab/streaming/context.rb
 - lib/robot_lab/streaming/events.rb
@@ -398,6 +392,7 @@ files:
 - lib/robot_lab/tool_config.rb
 - lib/robot_lab/tool_manifest.rb
 - lib/robot_lab/user_message.rb
+- lib/robot_lab/utils.rb
 - lib/robot_lab/version.rb
 - lib/robot_lab/waiter.rb
 - mkdocs.yml

data/docs/api/adapters/anthropic.md

@@ -1,121 +0,0 @@
-# Anthropic Adapter
-
-Adapter for Claude models via Anthropic API.
-
-## Class: `RobotLab::Adapters::Anthropic`
-
-```ruby
-# Automatically used for Claude models
-robot = RobotLab.build do
-  model "claude-sonnet-4"
-end
-```
-
-## Supported Models
-
-| Model | Description |
-|-------|-------------|
-| `claude-sonnet-4` | Latest Sonnet (recommended) |
-| `claude-opus-4` | Most capable model |
-| `claude-3-5-sonnet-latest` | Claude 3.5 Sonnet |
-| `claude-3-5-haiku-latest` | Fast, efficient model |
-
-## Configuration
-
-### API Key
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-api03-..."
-```
-
-### Options
-
-```ruby
-RobotLab.configure do |config|
-  config.adapter_options = {
-    anthropic: {
-      base_url: "https://api.anthropic.com",
-      api_version: "2024-01-01",
-      timeout: 120,
-      max_tokens: 4096
-    }
-  }
-end
-```
-
-## Features
-
-### Streaming
-
-```ruby
-result = robot.run(state: state) do |event|
-  case event
-  when :text_delta
-    print event.text
-  when :tool_call
-    puts "Calling: #{event.name}"
-  end
-end
-```
-
-### Tool Use
-
-Tools are automatically converted to Anthropic's format:
-
-```ruby
-robot = RobotLab.build do
-  model "claude-sonnet-4"
-
-  tool :search do
-    description "Search the database"
-    parameter :query, type: :string, required: true
-    handler { |query:, **_| Database.search(query) }
-  end
-end
-```
-
-### Extended Thinking
-
-For complex reasoning tasks:
-
-```ruby
-robot = RobotLab.build do
-  model "claude-sonnet-4"
-  # Extended thinking is automatically enabled for supported models
-end
-```
-
-## Response Format
-
-```ruby
-{
-  content: [TextMessage, ...],
-  tool_calls: [ToolCallMessage, ...],
-  usage: {
-    input_tokens: 150,
-    output_tokens: 250,
-    cache_creation_input_tokens: 0,
-    cache_read_input_tokens: 0
-  },
-  stop_reason: "end_turn"
-}
-```
-
-## Error Handling
-
-```ruby
-begin
-  result = robot.run(state: state)
-rescue RobotLab::Adapters::RateLimitError => e
-  sleep(e.retry_after)
-  retry
-rescue RobotLab::Adapters::APIError => e
-  logger.error("Anthropic API error: #{e.message}")
-end
-```
-
-## See Also
-
-- [Adapters Overview](index.md)
-- [Streaming Guide](../../guides/streaming.md)
-- [Anthropic API Documentation](https://docs.anthropic.com/)