robot_lab 0.0.1

data/lib/robot_lab/streaming/context.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Streaming
+    # Context for managing streaming events during execution
+    #
+    # StreamingContext provides methods for publishing events with
+    # automatic sequencing, timestamping, and ID generation.
+    #
+    # @example
+    #   context = Context.new(
+    #     run_id: "run_123",
+    #     message_id: "msg_456",
+    #     scope: "network",
+    #     publish: ->(event) { broadcast(event) }
+    #   )
+    #
+    #   context.publish_event(event: "text.delta", data: { delta: "Hello" })
+    #
+    class Context
+      # @!attribute [r] run_id
+      #   @return [String] the unique run identifier
+      # @!attribute [r] parent_run_id
+      #   @return [String, nil] the parent run identifier for nested contexts
+      # @!attribute [r] message_id
+      #   @return [String] the current message identifier
+      # @!attribute [r] scope
+      #   @return [String] the context scope (network, robot, etc.)
+      attr_reader :run_id, :parent_run_id, :message_id, :scope
+
+      # Creates a new streaming Context.
+      #
+      # @param run_id [String] unique run identifier
+      # @param message_id [String] current message identifier
+      # @param scope [String, Symbol] context scope
+      # @param publish [Proc] callback for publishing events
+      # @param parent_run_id [String, nil] parent run identifier
+      # @param sequence_counter [SequenceCounter, nil] shared sequence counter
+      def initialize(run_id:, message_id:, scope:, publish:, parent_run_id: nil, sequence_counter: nil)
+        @run_id = run_id
+        @parent_run_id = parent_run_id
+        @message_id = message_id
+        @scope = scope.to_s
+        @publish = publish
+        @sequence = sequence_counter || SequenceCounter.new
+      end
+
+      # Publish an event
+      #
+      # @param event [String] Event type
+      # @param data [Hash] Event data
+      #
+      def publish_event(event:, data: {})
+        chunk = build_chunk(event, data)
+
+        begin
+          @publish.call(chunk)
+        rescue StandardError => e
+          RobotLab.configuration.logger.warn("Streaming error: #{e.message}")
+        end
+
+        chunk
+      end
+
+      # Create a child context for nested robot runs
+      #
+      # @param robot_run_id [String]
+      # @return [Context]
+      #
+      def create_child_context(robot_run_id)
+        Context.new(
+          run_id: robot_run_id,
+          parent_run_id: @run_id,
+          message_id: generate_message_id,
+          scope: "robot",
+          publish: @publish,
+          sequence_counter: @sequence  # Share sequence counter
+        )
+      end
+
+      # Create context with shared sequence counter
+      #
+      # @param run_id [String]
+      # @param message_id [String]
+      # @param scope [String]
+      # @return [Context]
+      #
+      def create_context_with_shared_sequence(run_id:, message_id:, scope:)
+        Context.new(
+          run_id: run_id,
+          message_id: message_id,
+          scope: scope,
+          publish: @publish,
+          sequence_counter: @sequence
+        )
+      end
+
+      # Generate a part ID (OpenAI-compatible, max 40 chars)
+      #
+      # @return [String]
+      #
+      def generate_part_id
+        short_msg_id = @message_id[0, 8]
+        timestamp = (Time.now.to_f * 1000).to_i.to_s[-6..]
+        random = SecureRandom.hex(4)
+        "part_#{short_msg_id}_#{timestamp}_#{random}"
+      end
+
+      # Generate a step ID for Inngest compatibility
+      #
+      # @param base_name [String]
+      # @return [String]
+      #
+      def generate_step_id(base_name)
+        "publish-#{@sequence.current}:#{base_name}"
+      end
+
+      # Generate a new message ID
+      #
+      # @return [String]
+      #
+      def generate_message_id
+        SecureRandom.uuid
+      end
+
+      private
+
+      def build_chunk(event, data)
+        seq = @sequence.next
+        {
+          event: event,
+          data: data.merge(
+            run_id: @run_id,
+            message_id: @message_id,
+            scope: @scope
+          ),
+          timestamp: (Time.now.to_f * 1000).to_i,
+          sequence_number: seq,
+          id: "publish-#{seq}:#{event}"
+        }
+      end
+    end
+  end
+end

data/lib/robot_lab/streaming/events.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Streaming
+    # Event type definitions for streaming
+    #
+    # Defines the structure and types of events emitted during
+    # robot and network execution.
+    #
+    module Events
+      # Run lifecycle events
+      RUN_STARTED = "run.started"
+      RUN_COMPLETED = "run.completed"
+      RUN_FAILED = "run.failed"
+      RUN_INTERRUPTED = "run.interrupted"
+
+      # Step events (for durable execution)
+      STEP_STARTED = "step.started"
+      STEP_COMPLETED = "step.completed"
+      STEP_FAILED = "step.failed"
+
+      # Part events (message composition)
+      PART_CREATED = "part.created"
+      PART_COMPLETED = "part.completed"
+      PART_FAILED = "part.failed"
+
+      # Content delta events (token streaming)
+      TEXT_DELTA = "text.delta"
+      TOOL_CALL_ARGUMENTS_DELTA = "tool_call.arguments.delta"
+      TOOL_CALL_OUTPUT_DELTA = "tool_call.output.delta"
+      REASONING_DELTA = "reasoning.delta"
+      DATA_DELTA = "data.delta"
+
+      # Human-in-the-loop events
+      HITL_REQUESTED = "hitl.requested"
+      HITL_RESOLVED = "hitl.resolved"
+
+      # Metadata events
+      USAGE_UPDATED = "usage.updated"
+      METADATA_UPDATED = "metadata.updated"
+
+      # Terminal event
+      STREAM_ENDED = "stream.ended"
+
+      # All event types
+      ALL_EVENTS = [
+        RUN_STARTED, RUN_COMPLETED, RUN_FAILED, RUN_INTERRUPTED,
+        STEP_STARTED, STEP_COMPLETED, STEP_FAILED,
+        PART_CREATED, PART_COMPLETED, PART_FAILED,
+        TEXT_DELTA, TOOL_CALL_ARGUMENTS_DELTA, TOOL_CALL_OUTPUT_DELTA,
+        REASONING_DELTA, DATA_DELTA,
+        HITL_REQUESTED, HITL_RESOLVED,
+        USAGE_UPDATED, METADATA_UPDATED,
+        STREAM_ENDED
+      ].freeze
+
+      # Lifecycle events
+      LIFECYCLE_EVENTS = [
+        RUN_STARTED, RUN_COMPLETED, RUN_FAILED, RUN_INTERRUPTED
+      ].freeze
+
+      # Delta events (content streaming)
+      DELTA_EVENTS = [
+        TEXT_DELTA, TOOL_CALL_ARGUMENTS_DELTA, TOOL_CALL_OUTPUT_DELTA,
+        REASONING_DELTA, DATA_DELTA
+      ].freeze
+
+      class << self
+        # Checks if the event is a lifecycle event.
+        #
+        # @param event [String] the event type
+        # @return [Boolean]
+        def lifecycle?(event)
+          LIFECYCLE_EVENTS.include?(event)
+        end
+
+        # Checks if the event is a delta (content streaming) event.
+        #
+        # @param event [String] the event type
+        # @return [Boolean]
+        def delta?(event)
+          DELTA_EVENTS.include?(event)
+        end
+
+        # Checks if the event is a valid event type.
+        #
+        # @param event [String] the event type
+        # @return [Boolean]
+        def valid?(event)
+          ALL_EVENTS.include?(event)
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/streaming/sequence_counter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Streaming
+    # Monotonic sequence counter for event ordering
+    #
+    # Provides globally unique, strictly increasing sequence numbers
+    # for event ordering across streaming contexts.
+    #
+    # Thread-safe via Mutex.
+    #
+    class SequenceCounter
+      # Creates a new SequenceCounter.
+      #
+      # @param start [Integer] the starting value (default: 0)
+      def initialize(start: 0)
+        @value = start
+        @mutex = Mutex.new
+      end
+
+      # Get the next sequence number
+      #
+      # @return [Integer]
+      #
+      def next
+        @mutex.synchronize do
+          @value += 1
+        end
+      end
+
+      # Get the current value without incrementing
+      #
+      # @return [Integer]
+      #
+      def current
+        @mutex.synchronize { @value }
+      end
+
+      # Reset to a specific value
+      #
+      # @param value [Integer]
+      #
+      def reset(value = 0)
+        @mutex.synchronize { @value = value }
+      end
+    end
+  end
+end

data/lib/robot_lab/task.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Wraps a Robot for use as a pipeline step with per-task configuration
+  #
+  # Task provides a way to pass step-specific context, MCP servers, tools,
+  # and memory to individual robots within a network pipeline. The task's
+  # context is deep-merged with the network's run parameters.
+  #
+  # @example Basic task with context
+  #   task = Task.new(
+  #     name: :billing,
+  #     robot: billing_robot,
+  #     context: { department: "billing", escalation_level: 2 }
+  #   )
+  #
+  # @example Task with MCP and tools
+  #   task = Task.new(
+  #     name: :developer,
+  #     robot: dev_robot,
+  #     context: { project: "api" },
+  #     mcp: [filesystem_server, github_server],
+  #     tools: [CodeSearch, FileReader]
+  #   )
+  #
+  class Task
+    # @!attribute [r] name
+    #   @return [Symbol] the task/step name
+    # @!attribute [r] robot
+    #   @return [Robot] the wrapped robot instance
+    attr_reader :name, :robot
+
+    # Creates a new Task instance.
+    #
+    # @param name [Symbol] the task/step name
+    # @param robot [Robot] the robot instance to wrap
+    # @param context [Hash] task-specific context (deep-merged with run params)
+    # @param mcp [Symbol, Array] MCP server config (:none, :inherit, or array)
+    # @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)
+      @name = name.to_sym
+      @robot = robot
+      @context = context
+      @mcp = mcp
+      @tools = tools
+      @memory = memory
+    end
+
+    # SimpleFlow step interface
+    #
+    # Enhances the result's run_params with task-specific configuration
+    # before delegating to the wrapped robot.
+    #
+    # @param result [SimpleFlow::Result] incoming result from previous step
+    # @return [SimpleFlow::Result] result with robot output
+    #
+    def call(result)
+      # Get current run params and deep merge with task context
+      run_params = deep_merge(
+        result.context[:run_params] || {},
+        @context
+      )
+
+      # Add task-specific robot config
+      run_params[:mcp] = @mcp unless @mcp == :none
+      run_params[:tools] = @tools unless @tools == :none
+      run_params[:memory] = @memory if @memory
+
+      # Create enhanced result with merged params
+      enhanced_result = result.with_context(:run_params, run_params)
+
+      # Delegate to robot
+      @robot.call(enhanced_result)
+    end
+
+    # Converts the task to a hash representation.
+    #
+    # @return [Hash]
+    #
+    def to_h
+      {
+        name: @name,
+        robot: @robot.name,
+        context: @context,
+        mcp: @mcp,
+        tools: @tools,
+        memory: @memory ? true : nil
+      }.compact
+    end
+
+    private
+
+    # Deep merge two hashes
+    #
+    # Values from `override` take precedence. Nested hashes are merged
+    # recursively. Arrays are replaced, not concatenated.
+    #
+    # @param base [Hash] the base hash
+    # @param override [Hash] the overriding hash
+    # @return [Hash] the merged result
+    #
+    def deep_merge(base, override)
+      base = base.transform_keys(&:to_sym)
+      override = override.transform_keys(&:to_sym)
+
+      base.merge(override) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/tool.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Defines a tool/function that robots can use
+  #
+  # Tools are capabilities that robots can invoke during execution.
+  # They have a name, description, parameter schema, and handler.
+  #
+  # @example Simple tool
+  #   tool = Tool.new(
+  #     name: "get_time",
+  #     description: "Get the current time",
+  #     handler: -> (_input, **_opts) { Time.now.to_s }
+  #   )
+  #
+  # @example Tool with parameters (using ruby_llm-schema)
+  #   class WeatherParams < RubyLLM::Schema
+  #     string :location, description: "City name"
+  #     string :unit, enum: %w[celsius fahrenheit], required: false
+  #   end
+  #
+  #   tool = Tool.new(
+  #     name: "get_weather",
+  #     description: "Get weather for a location",
+  #     parameters: WeatherParams,
+  #     handler: ->(input, **opts) {
+  #       # input[:location], input[:unit] are validated
+  #       fetch_weather(input[:location], input[:unit] || "celsius")
+  #     }
+  #   )
+  #
+  class Tool
+    # @!attribute [r] name
+    #   @return [String] the unique identifier for the tool
+    # @!attribute [r] description
+    #   @return [String, nil] a description of what the tool does
+    # @!attribute [r] parameters
+    #   @return [Class, Hash, nil] the parameter schema (RubyLLM::Schema or JSON Schema hash)
+    # @!attribute [r] handler
+    #   @return [Proc, nil] the callable that executes the tool logic
+    # @!attribute [r] mcp
+    #   @return [String, nil] the MCP server name if this is an MCP-provided tool
+    # @!attribute [r] strict
+    #   @return [Boolean, nil] whether strict mode is enabled
+    attr_reader :name, :description, :parameters, :handler, :mcp, :strict
+
+    # Creates a new Tool instance.
+    #
+    # @param name [String] the unique identifier for the tool
+    # @param description [String, nil] a description of what the tool does
+    # @param parameters [Class, Hash, nil] parameter schema (RubyLLM::Schema or JSON Schema)
+    # @param handler [Proc, nil] the callable that executes the tool logic
+    # @param mcp [String, nil] MCP server name if this is an MCP tool
+    # @param strict [Boolean, nil] whether strict mode is enabled
+    # @yield [input, **opts] optional block as handler
+    #
+    # @example Tool with block handler
+    #   Tool.new(name: "greet", description: "Greet user") do |input, **opts|
+    #     "Hello, #{input[:name]}!"
+    #   end
+    def initialize(name:, description: nil, parameters: nil, handler: nil, mcp: nil, strict: nil, &block)
+      @name = name.to_s
+      @description = description
+      @parameters = parameters
+      @handler = handler || block
+      @mcp = mcp
+      @strict = strict
+    end
+
+    # Execute the tool with input and context
+    #
+    # Supports two calling conventions:
+    # - Direct: tool.call(input, robot: robot, network: network)
+    # - ruby_llm: tool.call(args) - called without keyword args
+    #
+    # @param input [Hash] The input parameters (validated against schema)
+    # @param robot [Robot, nil] The robot invoking this tool
+    # @param network [NetworkRun, nil] The network context if running in a network
+    # @param step [Object, nil] Durable execution step context
+    # @return [Object] The tool's output
+    #
+    def call(input, robot: nil, network: nil, step: nil)
+      raise Error, "Tool '#{name}' has no handler defined" unless handler
+
+      validated_input = validate_input(input)
+      handler.call(validated_input, robot: robot, network: network, step: step)
+    rescue Error
+      raise
+    rescue StandardError => e
+      { error: Errors.serialize(e) }
+    end
+
+    # Convert to JSON Schema for LLM function calling
+    #
+    # @return [Hash] JSON Schema representation
+    #
+    def to_json_schema
+      schema = if parameters.respond_to?(:to_json_schema)
+                 # ruby_llm-schema class
+                 parameters.new.to_json_schema[:schema]
+               elsif parameters.is_a?(Hash)
+                 # Raw JSON schema
+                 parameters
+               else
+                 # No parameters
+                 { type: "object", properties: {}, required: [] }
+               end
+
+      {
+        name: name,
+        description: description,
+        parameters: schema
+      }.compact
+    end
+
+    # Convert to ruby_llm Tool class for integration
+    #
+    # @return [Class] A RubyLLM::Tool subclass
+    #
+    def to_ruby_llm_tool
+      tool = self
+      Class.new(RubyLLM::Tool) do
+        description tool.description
+
+        # Define parameters from schema
+        if tool.parameters.respond_to?(:to_json_schema)
+          schema = tool.parameters.new.to_json_schema[:schema]
+          schema[:properties]&.each do |prop_name, prop_def|
+            param prop_name.to_sym,
+                  type: prop_def[:type],
+                  desc: prop_def[:description],
+                  required: schema[:required]&.include?(prop_name.to_s)
+          end
+        elsif tool.parameters.is_a?(Hash) && tool.parameters[:properties]
+          tool.parameters[:properties].each do |prop_name, prop_def|
+            param prop_name.to_sym,
+                  type: prop_def[:type] || "string",
+                  desc: prop_def[:description],
+                  required: tool.parameters[:required]&.include?(prop_name.to_s)
+          end
+        end
+
+        define_method(:execute) do |**kwargs|
+          # This will be overridden at runtime with proper context
+          kwargs
+        end
+      end
+    end
+
+    # Converts the tool to a hash representation.
+    #
+    # @return [Hash] a hash containing the tool configuration
+    def to_h
+      {
+        name: name,
+        description: description,
+        parameters: parameters_to_hash,
+        mcp: mcp,
+        strict: strict
+      }.compact
+    end
+
+    # Converts the tool to JSON.
+    #
+    # @param args [Array] arguments passed to to_json
+    # @return [String] JSON representation of the tool
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Check if this is an MCP-provided tool
+    #
+    # @return [Boolean]
+    #
+    def mcp?
+      !mcp.nil?
+    end
+
+    # Return parameters schema for ruby_llm compatibility
+    #
+    # @return [Hash, nil] JSON Schema for tool parameters
+    #
+    def params_schema
+      if parameters.respond_to?(:to_json_schema)
+        parameters.new.to_json_schema[:schema]
+      elsif parameters.is_a?(Hash)
+        parameters
+      end
+    end
+
+    # Provider-specific parameters for ruby_llm compatibility
+    #
+    # @return [Hash] Empty hash (no provider-specific params)
+    #
+    def provider_params
+      {}
+    end
+
+    private
+
+    def validate_input(input)
+      return input unless parameters
+
+      input = input.transform_keys(&:to_sym) if input.is_a?(Hash)
+
+      if parameters.respond_to?(:new) && parameters.ancestors.include?(defined?(RubyLLM::Schema) ? RubyLLM::Schema : Object)
+        # Validate with ruby_llm-schema (if available)
+        # For now, just pass through
+        input
+      else
+        input
+      end
+    end
+
+    def parameters_to_hash
+      if parameters.respond_to?(:to_json_schema)
+        parameters.new.to_json_schema
+      elsif parameters.is_a?(Hash)
+        parameters
+      end
+    end
+  end
+end