robot_lab 0.0.1

data/lib/robot_lab/robot_result.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Stores the result of a single robot execution
+  #
+  # RobotResult captures the LLM output, tool call results, and metadata
+  # from running an robot. Results are stored in State for conversation
+  # history and can be serialized for persistence.
+  #
+  # @example
+  #   result = RobotResult.new(
+  #     robot_name: "helper",
+  #     output: [TextMessage.new(role: :assistant, content: "Hello!")],
+  #     tool_calls: []
+  #   )
+  #   result.checksum  # => "a1b2c3d4..."
+  #
+  class RobotResult
+    # @!attribute [r] robot_name
+    #   @return [String] the name of the robot that produced this result
+    # @!attribute [r] output
+    #   @return [Array<Message>] the output messages from the robot
+    # @!attribute [r] tool_calls
+    #   @return [Array<ToolResultMessage>] the tool call results
+    # @!attribute [r] created_at
+    #   @return [Time] when the result was created
+    # @!attribute [r] id
+    #   @return [String] unique identifier for this result
+    # @!attribute [r] stop_reason
+    #   @return [String, nil] reason execution stopped
+    attr_reader :robot_name, :output, :tool_calls, :created_at, :id, :stop_reason
+
+    # @!attribute [rw] prompt
+    #   @return [Array<Message>, nil] the prompt messages used (debug)
+    # @!attribute [rw] history
+    #   @return [Array<Message>, nil] the history used (debug)
+    # @!attribute [rw] raw
+    #   @return [Object, nil] the raw LLM response (debug)
+    attr_accessor :prompt, :history, :raw
+
+    # Creates a new RobotResult instance.
+    #
+    # @param robot_name [String] the name of the robot
+    # @param output [Array<Message, Hash>] the output messages
+    # @param tool_calls [Array<ToolResultMessage, Hash>] tool call results
+    # @param created_at [Time, nil] creation timestamp (defaults to now)
+    # @param id [String, nil] unique ID (defaults to UUID)
+    # @param prompt [Array<Message>, nil] prompt messages (debug)
+    # @param history [Array<Message>, nil] history messages (debug)
+    # @param raw [Object, nil] raw LLM response (debug)
+    # @param stop_reason [String, nil] reason for stopping
+    def initialize(
+      robot_name:,
+      output:,
+      tool_calls: [],
+      created_at: nil,
+      id: nil,
+      prompt: nil,
+      history: nil,
+      raw: nil,
+      stop_reason: nil
+    )
+      @robot_name = robot_name
+      @output = normalize_messages(output)
+      @tool_calls = normalize_tool_results(tool_calls)
+      @created_at = created_at || Time.now
+      @id = id || SecureRandom.uuid
+      @prompt = prompt
+      @history = history
+      @raw = raw
+      @stop_reason = stop_reason
+    end
+
+    # Generate a checksum for deduplication
+    #
+    # Uses SHA256 hash of output + tool_calls + timestamp
+    # Useful for detecting duplicate results in persistence
+    #
+    # @return [String] Hex digest of the result content
+    #
+    def checksum
+      content = {
+        output: output.map(&:to_h),
+        tool_calls: tool_calls.map(&:to_h),
+        created_at: created_at.to_i
+      }
+      Digest::SHA256.hexdigest(content.to_json)
+    end
+
+    # Export result for serialization/persistence
+    #
+    # Excludes debug fields (prompt, history, raw) by default
+    #
+    # @return [Hash] Serializable result data
+    #
+    def export
+      {
+        robot_name: robot_name,
+        output: output.map(&:to_h),
+        tool_calls: tool_calls.map(&:to_h),
+        created_at: created_at.iso8601,
+        id: id,
+        checksum: checksum,
+        stop_reason: stop_reason
+      }.compact
+    end
+
+    # Converts the result to a full hash representation.
+    #
+    # Includes debug fields (prompt, history, raw).
+    #
+    # @return [Hash] full result data including debug fields
+    def to_h
+      export.merge(
+        prompt: prompt&.map(&:to_h),
+        history: history&.map(&:to_h),
+        raw: raw
+      ).compact
+    end
+
+    # Converts the result to JSON.
+    #
+    # Uses export format (excludes debug fields).
+    #
+    # @param args [Array] arguments passed to to_json
+    # @return [String] JSON representation
+    def to_json(*args)
+      export.to_json(*args)
+    end
+
+    # Get the last text content from output
+    #
+    # @return [String, nil] The content of the last text message
+    #
+    def last_text_content
+      output.reverse.find(&:text?)&.content
+    end
+
+    # Check if result contains tool calls
+    #
+    # @return [Boolean]
+    #
+    def has_tool_calls?
+      output.any?(&:tool_call?) || tool_calls.any?
+    end
+
+    # Check if execution stopped naturally (not due to tool call)
+    #
+    # @return [Boolean]
+    #
+    def stopped?
+      last_output = output.last
+      last_output&.stopped? || (!has_tool_calls? && last_output&.stop_reason.nil?)
+    end
+
+    # Reconstruct result from hash (e.g., from persistence)
+    #
+    # @param hash [Hash] Serialized result data
+    # @return [RobotResult]
+    #
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+
+      new(
+        robot_name: hash[:robot_name],
+        output: (hash[:output] || []).map { |m| Message.from_hash(m) },
+        tool_calls: (hash[:tool_calls] || []).map { |m| Message.from_hash(m) },
+        created_at: hash[:created_at] ? Time.parse(hash[:created_at].to_s) : nil,
+        id: hash[:id],
+        prompt: hash[:prompt]&.map { |m| Message.from_hash(m) },
+        history: hash[:history]&.map { |m| Message.from_hash(m) },
+        raw: hash[:raw],
+        stop_reason: hash[:stop_reason]
+      )
+    end
+
+    private
+
+    def normalize_messages(messages)
+      Array(messages).map do |msg|
+        case msg
+        when Message
+          msg
+        when Hash
+          Message.from_hash(msg)
+        else
+          raise ArgumentError, "Invalid message: must be Message or Hash"
+        end
+      end
+    end
+
+    def normalize_tool_results(results)
+      Array(results).map do |result|
+        case result
+        when ToolResultMessage
+          result
+        when Hash
+          result[:type] == "tool_result" ? ToolResultMessage.new(**result.slice(:tool, :content, :stop_reason)) : Message.from_hash(result)
+        else
+          raise ArgumentError, "Invalid tool result: must be ToolResultMessage or Hash"
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/robotic_model.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Thread-local storage for capturing tool executions during RubyLLM auto-execution.
+  #
+  # Stores tool execution records in thread-local storage so they can be
+  # retrieved after an LLM inference call completes.
+  #
+  class ToolExecutionCapture
+    # Returns the captured tool executions for the current thread.
+    #
+    # @return [Array<Hash>] array of execution records
+    def self.captured
+      Thread.current[:robot_lab_tool_executions] ||= []
+    end
+
+    # Clears the captured tool executions for the current thread.
+    #
+    # @return [Array] empty array
+    def self.clear!
+      Thread.current[:robot_lab_tool_executions] = []
+    end
+
+    # Records a tool execution.
+    #
+    # @param tool_name [String] name of the executed tool
+    # @param tool_id [String] unique identifier for this execution
+    # @param input [Hash] input parameters passed to the tool
+    # @param output [Object] the tool's return value
+    # @return [Array<Hash>] the updated captured array
+    def self.record(tool_name:, tool_id:, input:, output:)
+      captured << {
+        tool_name: tool_name,
+        tool_id: tool_id,
+        input: input,
+        output: output
+      }
+    end
+  end
+
+  # Wrapper around ruby_llm for LLM inference
+  #
+  # RoboticModel provides a unified interface for LLM calls, handling:
+  # - Message format conversion via adapters
+  # - Tool registration and execution
+  # - Streaming support
+  #
+  # @example Basic usage
+  #   model = RoboticModel.new("claude-sonnet-4", provider: :anthropic)
+  #   messages = [TextMessage.new(role: :user, content: "Hello!")]
+  #   response = model.infer(messages, [])
+  #
+  # @example With tools
+  #   model.infer(messages, [weather_tool], tool_choice: "auto")
+  #
+  class RoboticModel
+    # @!attribute [r] model_id
+    #   @return [String] the LLM model identifier
+    # @!attribute [r] provider
+    #   @return [Symbol] the LLM provider (:anthropic, :openai, :gemini, etc.)
+    # @!attribute [r] adapter
+    #   @return [Adapters::Base] the adapter for message conversion
+    attr_reader :model_id, :provider, :adapter
+
+    # Creates a new RoboticModel instance.
+    #
+    # @param model_id [String] the model identifier
+    # @param provider [Symbol, nil] the provider (auto-detected if not specified)
+    def initialize(model_id, provider: nil)
+      @model_id = model_id
+      @provider = provider || detect_provider(model_id)
+      @adapter = Adapters::Registry.for(@provider)
+    end
+
+    # Perform inference with messages and optional tools
+    #
+    # @param messages [Array<Message>] Conversation messages
+    # @param tools [Array<Tool>] Available tools
+    # @param tool_choice [String, Symbol] Tool selection mode
+    # @param streaming [Proc, nil] Streaming callback
+    # @return [InferenceResponse]
+    #
+    def infer(messages, tools = [], tool_choice: "auto", streaming: nil, &block)
+      chat = create_chat
+
+      # Register tools if any
+      if tools.any?
+        ruby_llm_tools = create_ruby_llm_tools(tools)
+        chat = chat.with_tools(*ruby_llm_tools)
+      end
+
+      # Add system message if present
+      system_content = @adapter.extract_system_message(messages)
+      chat = chat.with_instructions(system_content) if system_content
+
+      # Build conversation (excluding the last user message since ask() will add it)
+      conversation = @adapter.conversation_messages(messages)
+      conversation[0...-1].each do |msg|
+        add_message_to_chat(chat, msg)
+      end
+
+      # Make the request (ask adds the user message)
+      user_content = conversation.last&.content || ""
+
+      # Clear tool execution capture before making the request
+      ToolExecutionCapture.clear!
+
+      response = if block_given? || streaming
+                   chat.ask(user_content, &(block || streaming))
+                 else
+                   chat.ask(user_content)
+                 end
+
+      # Parse response
+      output = @adapter.parse_response(response)
+
+      # Build captured tool results from auto-executed tools
+      captured_tool_results = build_captured_tool_results(tools)
+
+      InferenceResponse.new(
+        output: output,
+        raw: response,
+        model: model_id,
+        provider: provider,
+        captured_tool_results: captured_tool_results
+      )
+    end
+
+    # Quick ask without full message array
+    #
+    # @param prompt [String] User prompt
+    # @param system [String, nil] System prompt
+    # @param tools [Array<Tool>] Available tools
+    # @return [InferenceResponse]
+    #
+    def ask(prompt, system: nil, tools: [], &block)
+      messages = []
+      messages << TextMessage.new(role: "system", content: system) if system
+      messages << TextMessage.new(role: "user", content: prompt)
+
+      infer(messages, tools, &block)
+    end
+
+    private
+
+    def create_chat
+      RubyLLM.chat(model: model_id, provider: provider)
+    end
+
+    def create_ruby_llm_tools(tools)
+      tools.map do |tool|
+        # Create a dynamic RubyLLM::Tool subclass
+        create_tool_class(tool)
+      end
+    end
+
+    def create_tool_class(tool)
+      # Build a RubyLLM::Tool subclass dynamically
+      tool_definition = tool
+      tool_name = tool.name
+
+      klass = Class.new(RubyLLM::Tool) do
+        description tool_definition.description || ""
+
+        # Add parameters from schema
+        schema = tool_definition.to_json_schema
+        if schema[:parameters] && schema[:parameters][:properties]
+          schema[:parameters][:properties].each do |prop_name, prop_def|
+            required = schema[:parameters][:required]&.include?(prop_name.to_s)
+            param prop_name.to_sym,
+                  type: prop_def[:type] || "string",
+                  desc: prop_def[:description],
+                  required: required
+          end
+        end
+
+        define_method(:execute) do |**kwargs|
+          # This is called by ruby_llm when the tool is invoked
+          # Call the handler directly (bypassing Tool#call which requires context)
+          # Handlers should use **_context pattern to accept but ignore context
+          output = tool_definition.handler.call(kwargs, robot: nil, network: nil, step: nil)
+
+          # Record the execution for later retrieval
+          ToolExecutionCapture.record(
+            tool_name: tool_name,
+            tool_id: SecureRandom.uuid,
+            input: kwargs,
+            output: output
+          )
+
+          output
+        end
+      end
+
+      # Set the class name so RubyLLM can identify the tool
+      # RubyLLM converts class names to snake_case for tool identification
+      class_name = tool_name.split("_").map(&:capitalize).join
+      klass.define_singleton_method(:name) { class_name }
+
+      # Also define instance method for name (used by some RubyLLM code paths)
+      klass.define_method(:name) { tool_name }
+
+      # Store reference to our tool for later execution
+      klass.define_singleton_method(:robot_lab_tool) { tool_definition }
+      klass
+    end
+
+    def build_captured_tool_results(tools)
+      ToolExecutionCapture.captured.map do |capture|
+        _tool = tools.find { |t| t.name == capture[:tool_name] }
+        tool_message = ToolMessage.new(
+          id: capture[:tool_id],
+          name: capture[:tool_name],
+          input: capture[:input]
+        )
+        ToolResultMessage.new(
+          tool: tool_message,
+          content: { data: capture[:output] }
+        )
+      end
+    end
+
+    def add_message_to_chat(chat, msg)
+      case msg
+      when TextMessage
+        if msg.user?
+          chat.add_message(role: :user, content: msg.content)
+        elsif msg.assistant?
+          chat.add_message(role: :assistant, content: msg.content)
+        end
+      when ToolResultMessage
+        # Tool results are handled by ruby_llm internally
+      end
+    end
+
+    def detect_provider(model_id)
+      case model_id.to_s.downcase
+      when /^claude/, /^anthropic/
+        :anthropic
+      when /^gpt/, /^o1/, /^o3/, /^chatgpt/
+        :openai
+      when /^gemini/
+        :gemini
+      when /^llama/, /^mistral/, /^mixtral/
+        :ollama
+      else
+        RobotLab.configuration.default_provider
+      end
+    end
+  end
+
+  # Response from LLM inference.
+  #
+  # Contains the parsed output, raw response, and any captured tool results.
+  #
+  class InferenceResponse
+    # @!attribute [r] output
+    #   @return [Array<Message>] parsed output messages
+    # @!attribute [r] raw
+    #   @return [Object] the raw response from RubyLLM
+    # @!attribute [r] model
+    #   @return [String] the model that generated the response
+    # @!attribute [r] provider
+    #   @return [Symbol] the provider that handled the request
+    # @!attribute [r] captured_tool_results
+    #   @return [Array<ToolResultMessage>] tool executions that were auto-executed
+    attr_reader :output, :raw, :model, :provider, :captured_tool_results
+
+    # Creates a new InferenceResponse instance.
+    #
+    # @param output [Array<Message>] parsed output messages
+    # @param raw [Object] raw response from RubyLLM
+    # @param model [String] model identifier
+    # @param provider [Symbol] provider identifier
+    # @param captured_tool_results [Array<ToolResultMessage>] captured results
+    def initialize(output:, raw:, model:, provider:, captured_tool_results: [])
+      @output = output
+      @raw = raw
+      @model = model
+      @provider = provider
+      @captured_tool_results = captured_tool_results
+    end
+
+    # Get the stop reason from the last output message
+    #
+    # @return [String, nil]
+    #
+    def stop_reason
+      output.last&.stop_reason
+    end
+
+    # Check if inference stopped naturally
+    #
+    # @return [Boolean]
+    #
+    def stopped?
+      stop_reason == "stop"
+    end
+
+    # Check if inference wants to call tools
+    #
+    # @return [Boolean]
+    #
+    def wants_tools?
+      stop_reason == "tool" || output.any?(&:tool_call?)
+    end
+
+    # Get all tool calls from the response
+    #
+    # @return [Array<ToolMessage>]
+    #
+    def tool_calls
+      output.select(&:tool_call?).flat_map(&:tools)
+    end
+
+    # Get the text content
+    #
+    # @return [String, nil]
+    #
+    def text_content
+      output.select(&:text?).map(&:content).join
+    end
+  end
+end

data/lib/robot_lab/state_proxy.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Proxy wrapper for state data that tracks mutations
+  #
+  # StateProxy wraps a hash and intercepts read/write operations,
+  # providing a clean interface for state access while enabling
+  # optional change tracking.
+  #
+  # @example
+  #   data = { count: 0, name: "test" }
+  #   proxy = StateProxy.new(data)
+  #   proxy[:count] = 1
+  #   proxy.count       # => 1
+  #   proxy[:name]      # => "test"
+  #   proxy.to_h        # => { count: 1, name: "test" }
+  #
+  class StateProxy
+    # Creates a new StateProxy.
+    #
+    # @param data [Hash] the initial data
+    # @param on_change [Proc, nil] callback invoked when a value changes
+    def initialize(data = {}, on_change: nil)
+      @data = data.transform_keys(&:to_sym)
+      @on_change = on_change
+    end
+
+    # Get value by key
+    #
+    # @param key [Symbol, String]
+    # @return [Object]
+    #
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    # Set value by key
+    #
+    # @param key [Symbol, String]
+    # @param value [Object]
+    #
+    def []=(key, value)
+      key = key.to_sym
+      old_value = @data[key]
+      @data[key] = value
+      @on_change&.call(key, old_value, value) if old_value != value
+      value
+    end
+
+    # Check if key exists
+    #
+    # @param key [Symbol, String]
+    # @return [Boolean]
+    #
+    def key?(key)
+      @data.key?(key.to_sym)
+    end
+    # @!method has_key?(key)
+    #   Alias for {#key?}.
+    alias has_key? key?
+
+    # @!method include?(key)
+    #   Alias for {#key?}.
+    alias include? key?
+
+    # Get all keys
+    #
+    # @return [Array<Symbol>]
+    #
+    def keys
+      @data.keys
+    end
+
+    # Get all values
+    #
+    # @return [Array]
+    #
+    def values
+      @data.values
+    end
+
+    # Iterate over key-value pairs
+    #
+    # @yield [Symbol, Object]
+    #
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Delete a key
+    #
+    # @param key [Symbol, String]
+    # @return [Object] The deleted value
+    #
+    def delete(key)
+      @data.delete(key.to_sym)
+    end
+
+    # Merge in additional data
+    #
+    # @param other [Hash]
+    # @return [self]
+    #
+    def merge!(other)
+      other.each { |k, v| self[k] = v }
+      self
+    end
+
+    # Convert to plain hash
+    #
+    # @return [Hash]
+    #
+    def to_h
+      @data.dup
+    end
+    alias to_hash to_h
+
+    # Deep duplicate
+    #
+    # @return [StateProxy]
+    #
+    def dup
+      StateProxy.new(deep_dup(@data), on_change: @on_change)
+    end
+
+    # Check if empty
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      @data.empty?
+    end
+
+    # Number of keys
+    #
+    # @return [Integer]
+    #
+    def size
+      @data.size
+    end
+    alias length size
+
+    # Respond to method calls as hash access
+    #
+    def respond_to_missing?(method_name, include_private = false)
+      key = method_name.to_s.chomp("=").to_sym
+      @data.key?(key) || super
+    end
+
+    # Allow method-style access to keys
+    #
+    # @example
+    #   proxy.name        # Same as proxy[:name]
+    #   proxy.name = "x"  # Same as proxy[:name] = "x"
+    #
+    def method_missing(method_name, *args, &block)
+      method_str = method_name.to_s
+
+      if method_str.end_with?("=")
+        # Setter
+        key = method_str.chomp("=").to_sym
+        self[key] = args.first
+      elsif @data.key?(method_name.to_sym)
+        # Getter
+        self[method_name]
+      else
+        super
+      end
+    end
+
+    def inspect
+      "#<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