robot_lab 0.0.1

data/lib/robot_lab/errors.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Error serialization utilities
+  #
+  # Provides methods to serialize Ruby exceptions into a format
+  # suitable for tool results and logging.
+  #
+  module Errors
+    class << self
+      # Serialize an exception to a hash
+      #
+      # @param error [Exception] The error to serialize
+      # @param include_backtrace [Boolean] Whether to include backtrace
+      # @return [Hash] Serialized error
+      #
+      def serialize(error, include_backtrace: false)
+        result = {
+          type: error.class.name,
+          message: error.message
+        }
+
+        if include_backtrace && error.backtrace
+          result[:backtrace] = error.backtrace.first(10)
+        end
+
+        if error.cause
+          result[:cause] = serialize(error.cause, include_backtrace: include_backtrace)
+        end
+
+        result
+      end
+
+      # Deserialize an error hash back to an exception
+      #
+      # @param hash [Hash] Serialized error
+      # @return [StandardError]
+      #
+      def deserialize(hash)
+        hash = hash.transform_keys(&:to_sym)
+        klass = begin
+          Object.const_get(hash[:type])
+        rescue NameError
+          StandardError
+        end
+        klass.new(hash[:message])
+      end
+
+      # Format error for display
+      #
+      # @param error [Exception] The error
+      # @return [String]
+      #
+      def format(error)
+        "[#{error.class.name}] #{error.message}"
+      end
+
+      # Wrap a block and return error hash on failure
+      #
+      # @yield Block to execute
+      # @return [Hash] { data: result } or { error: serialized_error }
+      #
+      def capture
+        { data: yield }
+      rescue StandardError => e
+        { error: serialize(e) }
+      end
+    end
+  end
+end

data/lib/robot_lab/history/active_record_adapter.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module History
+    # ActiveRecord-based history persistence adapter
+    #
+    # Provides thread and result storage using ActiveRecord models.
+    # Requires Rails or standalone ActiveRecord setup.
+    #
+    # @example
+    #   adapter = ActiveRecordAdapter.new(
+    #     thread_model: RobotLabThread,
+    #     result_model: RobotLabResult
+    #   )
+    #
+    #   config = adapter.to_config
+    #   network = RobotLab.create_network(history: config)
+    #
+    class ActiveRecordAdapter
+      # @!attribute [r] thread_model
+      #   @return [Class] ActiveRecord model class for threads
+      # @!attribute [r] result_model
+      #   @return [Class] ActiveRecord model class for results
+      attr_reader :thread_model, :result_model
+
+      # Initialize adapter with ActiveRecord models
+      #
+      # @param thread_model [Class] ActiveRecord model for threads
+      # @param result_model [Class] ActiveRecord model for results
+      #
+      def initialize(thread_model:, result_model:)
+        @thread_model = thread_model
+        @result_model = result_model
+      end
+
+      # Create a new thread
+      #
+      # @param state [State] Current state
+      # @param input [String, UserMessage] Initial input
+      # @return [Hash] Thread ID and metadata
+      #
+      def create_thread(state:, input:, **)
+        input_content = input.is_a?(UserMessage) ? input.content : input.to_s
+        input_metadata = input.is_a?(UserMessage) ? input.metadata : {}
+
+        thread = @thread_model.create!(
+          session_id: SecureRandom.uuid,
+          initial_input: input_content,
+          input_metadata: input_metadata,
+          state_data: state.data.to_h
+        )
+
+        { session_id: thread.session_id, created_at: thread.created_at }
+      end
+
+      # Retrieve results for a thread
+      #
+      # @param session_id [String] Thread identifier
+      # @return [Array<RobotResult>] History of results
+      #
+      def get(session_id:, **)
+        @result_model
+          .where(session_id: session_id)
+          .order(:sequence_number, :created_at)
+          .map { |record| deserialize_result(record) }
+      end
+
+      # Append user message to thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param message [UserMessage] Message to append
+      #
+      def append_user_message(session_id:, message:, **)
+        @thread_model.where(session_id: session_id).update_all(
+          last_user_message: message.content,
+          last_user_message_at: Time.current
+        )
+      end
+
+      # Append results to thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param new_results [Array<RobotResult>] Results to append
+      #
+      def append_results(session_id:, new_results:, **)
+        base_sequence = @result_model.where(session_id: session_id).maximum(:sequence_number) || 0
+
+        new_results.each_with_index do |result, index|
+          @result_model.create!(
+            session_id: session_id,
+            robot_name: result.robot_name,
+            sequence_number: base_sequence + index + 1,
+            output_data: serialize_messages(result.output),
+            tool_calls_data: serialize_messages(result.tool_calls),
+            stop_reason: result.stop_reason,
+            checksum: result.checksum
+          )
+        end
+
+        # Update thread timestamp
+        @thread_model.where(session_id: session_id).update_all(
+          updated_at: Time.current
+        )
+      end
+
+      # Convert adapter to Config object
+      #
+      # @return [Config] History configuration
+      #
+      def to_config
+        Config.new(
+          create_thread: method(:create_thread),
+          get: method(:get),
+          append_user_message: method(:append_user_message),
+          append_results: method(:append_results)
+        )
+      end
+
+      private
+
+      def serialize_messages(messages)
+        messages.map(&:to_h)
+      end
+
+      def deserialize_result(record)
+        output = deserialize_messages(record.output_data)
+        tool_calls = deserialize_messages(record.tool_calls_data)
+
+        RobotResult.new(
+          robot_name: record.robot_name,
+          output: output,
+          tool_calls: tool_calls,
+          stop_reason: record.stop_reason
+        )
+      end
+
+      def deserialize_messages(data)
+        return [] unless data
+
+        data.map do |msg_hash|
+          Message.from_hash(msg_hash.symbolize_keys)
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/history/config.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module History
+    # Configuration for conversation history persistence
+    #
+    # Defines callbacks for creating threads, retrieving history,
+    # and appending messages/results.
+    #
+    # @example
+    #   config = History::Config.new(
+    #     create_thread: ->(state:, input:, **) {
+    #       { session_id: SecureRandom.uuid }
+    #     },
+    #     get: ->(session_id:, **) {
+    #       database.find_results(session_id)
+    #     },
+    #     append_results: ->(session_id:, new_results:, **) {
+    #       database.insert_results(session_id, new_results)
+    #     }
+    #   )
+    #
+    class Config
+      # @!attribute [rw] create_thread
+      #   @return [Proc, nil] callback to create a new conversation thread
+      # @!attribute [rw] get
+      #   @return [Proc, nil] callback to retrieve history for a thread
+      # @!attribute [rw] append_user_message
+      #   @return [Proc, nil] callback to append user messages
+      # @!attribute [rw] append_results
+      #   @return [Proc, nil] callback to append robot results
+      attr_accessor :create_thread, :get, :append_user_message, :append_results
+
+      # Initialize history configuration
+      #
+      # @param create_thread [Proc] Callback to create a new thread
+      # @param get [Proc] Callback to retrieve history for a thread
+      # @param append_user_message [Proc] Callback to append user messages
+      # @param append_results [Proc] Callback to append robot results
+      #
+      def initialize(create_thread: nil, get: nil, append_user_message: nil, append_results: nil)
+        @create_thread = create_thread
+        @get = get
+        @append_user_message = append_user_message
+        @append_results = append_results
+      end
+
+      # Check if history persistence is configured
+      #
+      # @return [Boolean]
+      #
+      def configured?
+        @create_thread && @get
+      end
+
+      # Create a new conversation thread
+      #
+      # @param state [State] Current state
+      # @param input [String, UserMessage] Initial input
+      # @param kwargs [Hash] Additional arguments
+      # @return [Hash] Must include :session_id
+      #
+      def create_thread!(state:, input:, **kwargs)
+        raise HistoryError, "create_thread callback not configured" unless @create_thread
+
+        result = @create_thread.call(state: state, input: input, **kwargs)
+
+        unless result.is_a?(Hash) && result[:session_id]
+          raise HistoryError, "create_thread must return a hash with :session_id"
+        end
+
+        result
+      end
+
+      # Retrieve history for a thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param kwargs [Hash] Additional arguments
+      # @return [Array<RobotResult>] History of results
+      #
+      def get!(session_id:, **kwargs)
+        raise HistoryError, "get callback not configured" unless @get
+
+        @get.call(session_id: session_id, **kwargs)
+      end
+
+      # Append a user message to the thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param message [UserMessage] Message to append
+      # @param kwargs [Hash] Additional arguments
+      #
+      def append_user_message!(session_id:, message:, **kwargs)
+        return unless @append_user_message
+
+        @append_user_message.call(session_id: session_id, message: message, **kwargs)
+      end
+
+      # Append robot results to the thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param new_results [Array<RobotResult>] Results to append
+      # @param kwargs [Hash] Additional arguments
+      #
+      def append_results!(session_id:, new_results:, **kwargs)
+        return unless @append_results
+
+        @append_results.call(session_id: session_id, new_results: new_results, **kwargs)
+      end
+    end
+
+    # Error raised when history operations fail
+    class HistoryError < RobotLab::Error; end
+  end
+end

data/lib/robot_lab/history/thread_manager.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module History
+    # Manages conversation thread lifecycle
+    #
+    # Handles thread creation, history retrieval, and result persistence
+    # using the configured history adapter.
+    #
+    # @example
+    #   manager = ThreadManager.new(config)
+    #   session_id = manager.create_thread(state: state, input: "Hello")
+    #   history = manager.get_history(session_id)
+    #
+    class ThreadManager
+      # @!attribute [r] config
+      #   @return [Config] the history configuration
+      attr_reader :config
+
+      # Initialize thread manager
+      #
+      # @param config [Config] History configuration
+      #
+      def initialize(config)
+        @config = config
+      end
+
+      # Create a new conversation thread
+      #
+      # @param state [State] Current state
+      # @param input [String, UserMessage] Initial input
+      # @return [String] Thread ID
+      #
+      def create_thread(state:, input:)
+        result = @config.create_thread!(state: state, input: input)
+        result[:session_id]
+      end
+
+      # Get history for a thread
+      #
+      # @param session_id [String] Thread identifier
+      # @return [Array<RobotResult>] History of results
+      #
+      def get_history(session_id)
+        @config.get!(session_id: session_id)
+      end
+
+      # Append user message to thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param message [UserMessage] Message to append
+      #
+      def append_user_message(session_id:, message:)
+        @config.append_user_message!(session_id: session_id, message: message)
+      end
+
+      # Append results to thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param results [Array<RobotResult>] Results to append
+      #
+      def append_results(session_id:, results:)
+        @config.append_results!(session_id: session_id, new_results: results)
+      end
+
+      # Load state from thread history
+      #
+      # @param session_id [String] Thread identifier
+      # @param state [State, Memory] State/Memory to populate
+      # @return [State, Memory] State/Memory with loaded history
+      #
+      def load_state(session_id:, state:)
+        results = get_history(session_id)
+
+        state.session_id = session_id
+        results.each { |r| state.append_result(r) }
+
+        state
+      end
+
+      # Save state results to thread
+      #
+      # @param session_id [String] Thread identifier
+      # @param state [State] State with results to save
+      # @param since_index [Integer] Save results from this index
+      #
+      def save_state(session_id:, state:, since_index: 0)
+        new_results = state.results[since_index..]
+        append_results(session_id: session_id, results: new_results) if new_results.any?
+      end
+    end
+  end
+end

data/lib/robot_lab/mcp/client.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module MCP
+    # MCP client for communicating with Model Context Protocol servers
+    #
+    # Uses actionmcp gem for MCP protocol implementation.
+    # Supports multiple transport types: StdIO, SSE, WebSocket, HTTP.
+    #
+    # @example
+    #   client = Client.new(name: "neon", transport: { type: "ws", url: "ws://..." })
+    #   client.connect
+    #   tools = client.list_tools
+    #   result = client.call_tool("createBranch", { project_id: "abc" })
+    #
+    class Client
+      # @!attribute [r] server
+      #   @return [Server] the MCP server configuration
+      # @!attribute [r] connected
+      #   @return [Boolean] whether currently connected
+      attr_reader :server, :connected
+
+      # Creates a new MCP Client instance.
+      #
+      # @param server_or_config [Server, Hash] the server or configuration hash
+      # @raise [ArgumentError] if config is invalid
+      def initialize(server_or_config)
+        @server = case server_or_config
+                  when Server
+                    server_or_config
+                  when Hash
+                    Server.new(**server_or_config.transform_keys(&:to_sym))
+                  else
+                    raise ArgumentError, "Invalid server config"
+                  end
+        @connected = false
+        @transport = nil
+        @request_id = 0
+      end
+
+      # Connect to the MCP server
+      #
+      # @return [self]
+      #
+      def connect
+        return self if @connected
+
+        @transport = create_transport
+        @transport.connect if @transport.respond_to?(:connect)
+        @connected = true
+
+        self
+      rescue StandardError => e
+        RobotLab.configuration.logger.warn("MCP connection failed for #{@server.name}: #{e.message}")
+        @connected = false
+        self
+      end
+
+      # Disconnect from the server
+      #
+      # @return [self]
+      #
+      def disconnect
+        return self unless @connected
+
+        @transport.close if @transport.respond_to?(:close)
+        @connected = false
+        @transport = nil
+
+        self
+      end
+
+      # List available tools from the server
+      #
+      # @return [Array<Hash>] Tool definitions
+      #
+      def list_tools
+        ensure_connected!
+        response = request(method: "tools/list")
+        response[:tools] || []
+      end
+
+      # Call a tool on the server
+      #
+      # @param name [String] Tool name
+      # @param arguments [Hash] Tool arguments
+      # @return [Object] Tool result
+      #
+      def call_tool(name, arguments = {})
+        ensure_connected!
+        response = request(
+          method: "tools/call",
+          params: { name: name, arguments: arguments }
+        )
+        response[:content] || response
+      end
+
+      # List available resources
+      #
+      # @return [Array<Hash>]
+      #
+      def list_resources
+        ensure_connected!
+        response = request(method: "resources/list")
+        response[:resources] || []
+      end
+
+      # Read a resource
+      #
+      # @param uri [String] Resource URI
+      # @return [Object]
+      #
+      def read_resource(uri)
+        ensure_connected!
+        response = request(method: "resources/read", params: { uri: uri })
+        response[:contents] || response
+      end
+
+      # List available prompts
+      #
+      # @return [Array<Hash>]
+      #
+      def list_prompts
+        ensure_connected!
+        response = request(method: "prompts/list")
+        response[:prompts] || []
+      end
+
+      # Get a prompt
+      #
+      # @param name [String] Prompt name
+      # @param arguments [Hash] Prompt arguments
+      # @return [Hash]
+      #
+      def get_prompt(name, arguments = {})
+        ensure_connected!
+        response = request(method: "prompts/get", params: { name: name, arguments: arguments })
+        response
+      end
+
+      # Checks if the client is connected to the server.
+      #
+      # @return [Boolean]
+      def connected?
+        @connected
+      end
+
+      # Converts the client to a hash representation.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          server: @server.to_h,
+          connected: @connected
+        }
+      end
+
+      private
+
+      def ensure_connected!
+        raise MCPError, "Not connected to MCP server: #{@server.name}" unless @connected
+      end
+
+      def create_transport
+        case @server.transport_type
+        when "stdio"
+          Transports::Stdio.new(@server.transport)
+        when "ws", "websocket"
+          Transports::WebSocket.new(@server.transport)
+        when "sse"
+          Transports::SSE.new(@server.transport)
+        when "streamable-http", "http"
+          Transports::StreamableHTTP.new(@server.transport)
+        else
+          raise MCPError, "Unsupported transport type: #{@server.transport_type}"
+        end
+      end
+
+      def request(method:, params: nil)
+        @request_id += 1
+
+        message = {
+          jsonrpc: "2.0",
+          id: @request_id,
+          method: method
+        }
+        message[:params] = params if params
+
+        response = @transport.send_request(message)
+        parse_response(response)
+      end
+
+      def parse_response(response)
+        return response[:result] if response.is_a?(Hash) && response[:result]
+
+        case response
+        when String
+          parsed = JSON.parse(response, symbolize_names: true)
+          parsed[:result] || parsed
+        when Hash
+          response[:result] || response
+        else
+          response
+        end
+      rescue JSON::ParserError
+        { raw: response }
+      end
+    end
+  end
+end