agent99 0.0.1

data/lib/agent99/agent_lifecycle.rb

@@ -0,0 +1,87 @@
+# lib/agent99/agent_lifecycle.rb
+
+module Agent99::AgentLifecycle
+
+  # Initializes a new AI agent with the given configuration.
+  #
+  # @param registry_client [Agent99::RegistryClient] The client for agent registration
+  # @param message_client [Agent99::AmqpMessageClient] The client for message handling
+  # @param logger [Logger] The logger instance for the agent
+  #
+  def initialize(registry_client: Agent99::RegistryClient.new,
+                 message_client: Agent99::AmqpMessageClient.new,
+                 logger: Logger.new($stdout))
+    @payload = nil
+    @name = self.class.name
+    @capabilities = capabilities
+    @id = nil
+    @registry_client = registry_client
+    @message_client = message_client
+    @logger = logger
+
+    @registry_client.logger = logger
+    register
+
+    @queue = message_client.setup(agent_id: id, logger:)
+
+    init if respond_to?(:init)
+  
+    setup_signal_handlers
+  end
+
+  # Registers the agent with the registry service.
+  #
+  # @raise [StandardError] If registration fails
+  #
+  def register
+    @id = registry_client.register(name:, capabilities:)
+    logger.info "Registered Agent #{name} with ID: #{id}"
+  rescue StandardError => e
+    handle_error("Error during registration", e)
+  end
+
+  # Withdraws the agent from the registry service.
+  #
+  def withdraw
+    registry_client.withdraw(@id) if @id
+    @id = nil
+  end
+
+
+  ################################################
+  private
+
+  # Checks if the agent is currently paused.
+  #
+  # @return [Boolean] True if the agent is paused, false otherwise
+  #
+  def paused?
+    @paused
+  end
+
+  # Sets up signal handlers for graceful shutdown.
+  #
+  def setup_signal_handlers
+    at_exit { fini }
+
+    %w[INT TERM QUIT].each do |signal|
+      Signal.trap(signal) do
+        STDERR.puts "\nReceived #{signal} signal. Initiating graceful shutdown..."
+        exit
+      end
+    end
+  end
+
+
+  # Performs cleanup operations when the agent is shutting down.
+  #
+  def fini
+    if id
+      queue_name = id
+      withdraw
+      @message_client&.delete_queue(queue_name)
+    else
+      logger.warn('fini called with a nil id')
+    end
+  end
+end

data/lib/agent99/amqp_message_client.rb

@@ -0,0 +1,117 @@
+# lib/agent99/amqp_message_client.rb
+
+require 'bunny'
+require 'json'
+require 'json_schema'
+require 'logger'
+
+class Agent99::AmqpMessageClient
+  QUEUE_TTL = 60_000 # 60 seconds TTL
+  @instance = nil
+
+  class << self
+    def instance
+      @instance ||= new
+    end
+  end
+
+  attr_accessor :logger, :channel, :exchange
+
+  def initialize(logger: Logger.new($stdout))
+    @connection = create_amqp_connection
+    @channel  = @connection.create_channel
+    @exchange = @channel.default_exchange
+    @logger   = logger
+  end
+
+  def setup(agent_id:, logger:)
+    queue = create_queue(agent_id)
+    
+    # Returning the queue to be used in the Base class
+    queue
+  end
+
+  def create_queue(agent_id)
+    queue_name = "#{agent_id}"
+    @channel.queue(queue_name, expires: QUEUE_TTL)
+  end
+
+  def listen_for_messages(
+      queue,
+      request_handler:,
+      response_handler:,
+      control_handler:
+    )
+    queue.subscribe(block: true) do |delivery_info, properties, body|
+      message = JSON.parse(body, symbolize_names: true)
+      logger.debug "Received message: #{message.inspect}"
+
+      type = message.dig(:header, :type)
+
+      case type
+      when "request"
+        request_handler.call(message)
+      when "response"
+        response_handler.call(message)
+      when "control"
+        control_handler.call(message)
+      else
+        raise NotImplementedError, "Unsupported message type: #{type}"
+      end
+    end
+  end
+
+
+  def publish(message)
+    queue_name = message.dig(:header, :to_uuid)
+
+    begin
+      json_payload = JSON.generate(message)
+
+      exchange.publish(json_payload, routing_key: queue_name)
+
+      logger.info "Message published successfully to queue: #{queue_name}"
+      
+      # Return a success status
+      { success: true, message: "Message published successfully" }
+    
+    rescue JSON::GeneratorError => e
+      logger.error "Failed to convert payload to JSON: #{e.message}"
+      { success: false, error: "JSON conversion error: #{e.message}" }
+    
+    rescue Bunny::ConnectionClosedError, Bunny::ChannelAlreadyClosed => e
+      logger.error "Failed to publish message: #{e.message}"
+      { success: false, error: "Publishing error: #{e.message}" }
+    
+    rescue StandardError => e
+      logger.error "Unexpected error while publishing message: #{e.message}"
+      { success: false, error: "Unexpected error: #{e.message}" }
+    end
+  end
+
+
+  def delete_queue(queue_name)
+    return logger.warn("Attempted to delete queue with nil name") if queue_name.nil?
+
+    begin
+      queue = @channel.queue(queue_name, passive: true)
+      queue.delete
+      logger.info "Queue #{queue_name} was deleted"
+    rescue Bunny::NotFound
+      logger.warn "Queue #{queue_name} not found"
+    rescue StandardError => e
+      logger.error "Error deleting queue #{queue_name}: #{e.message}"
+    end
+  end
+
+
+  ################################################
+  private
+  
+  def create_amqp_connection
+    Bunny.new.tap(&:start)
+  rescue Bunny::TCPConnectionFailed, StandardError => e
+    logger.error "Failed to connect to AMQP: #{e.message}"
+    raise "AMQP Connection Error: #{e.message}. Please check your AMQP server and try again."
+  end
+end

data/lib/agent99/base.rb

@@ -0,0 +1,61 @@
+# lib/agent99/base.rb
+
+require 'logger'
+require 'json'
+require 'json_schema'
+
+require_relative 'timestamp'
+require_relative 'registry_client'
+require_relative 'amqp_message_client'
+require_relative 'nats_message_client'
+
+require_relative 'header_management'
+require_relative 'agent_discovery'
+require_relative 'control_actions'
+require_relative 'agent_lifecycle'
+require_relative 'message_processing'
+
+# The Agent99::Base class serves as the foundation for creating AI agents in a distributed system.
+# It provides core functionality for agent registration, message handling, and communication.
+#
+# This class:
+# - Manages agent registration and withdrawal
+# - Handles incoming messages (requests, responses, and control messages)
+# - Provides a framework for defining agent capabilities
+# - Implements error handling and logging
+# - Supports configuration updates and status reporting
+#
+# Subclasses should override specific methods like `receive_request`, `receive_response`,
+# and `capabilities` to define custom behavior for different types of agents.
+#
+class Agent99::Base
+  include Agent99::HeaderManagement
+  include Agent99::AgentDiscovery
+  include Agent99::ControlActions
+  include Agent99::AgentLifecycle
+  include Agent99::MessageProcessing
+
+  MESSAGE_TYPES = %w[request response control]
+  
+  CONTROL_HANDLERS = {
+    'shutdown' => :handle_shutdown,
+    'pause' => :handle_pause,
+    'resume' => :handle_resume,
+    'update_config' => :handle_update_config,
+    'status' => :handle_status_request
+  }
+
+  attr_reader :id, :capabilities, :name, :payload, :header, :logger, :queue
+  attr_accessor :registry_client, :message_client
+
+
+  ###################################################
+  private
+
+  def handle_error(message, error)
+    logger.error "#{message}: #{error.message}"
+    logger.debug error.backtrace.join("\n")
+  end
+end
+
+

data/lib/agent99/control_actions.rb

@@ -0,0 +1,56 @@
+# lib/agent99/control_actions.rb
+
+
+module Agent99::ControlActions
+
+
+  ################################################
+  private
+  
+  # Handles the shutdown control message.
+  #
+  def handle_shutdown
+    logger.info "Received shutdown command. Initiating graceful shutdown..."
+    send_control_response("Shutting down")
+    fini
+    exit(0)
+  end
+
+  # Handles the pause control message.
+  #
+  def handle_pause
+    @paused = true
+    logger.info "Agent paused"
+    send_control_response("Paused")
+  end
+
+  # Handles the resume control message.
+  #
+  def handle_resume
+    @paused = false
+    logger.info "Agent resumed"
+    send_control_response("Resumed")
+  end
+
+  # Handles the update_config control message.
+  #
+  def handle_update_config
+    new_config = payload[:config]
+    @config = new_config
+    logger.info "Configuration updated: #{@config}"
+    send_control_response("Configuration updated")
+  end
+
+  # Handles the status request control message.
+  #
+  def handle_status_request
+    status = {
+      id: @id,
+      name: @name,
+      paused: @paused,
+      config: @config,
+      uptime: (Time.now - @start_time).to_i
+    }
+    send_control_response("Status", status)
+  end
+end

data/lib/agent99/header_management.rb

@@ -0,0 +1,24 @@
+# lib/agent99/header_management.rb
+
+module Agent99::HeaderManagement
+
+
+  ################################################
+  private
+  
+  def header      = @payload[:header]
+  def to_uuid     = header[:to_uuid]
+  def from_uuid   = header[:from_uuid]
+  def event_uuid  = header[:event_uuid]
+  def timestamp   = header[:timestamp]
+  def type        = header[:type]
+
+  def return_address
+    header.merge(
+      to_uuid:    from_uuid,
+      from_uuid:  to_uuid,
+      timestamp:  Agent99::Timestamp.new.to_i,
+      type:       'response'
+    )
+  end
+end

data/lib/agent99/header_schema.rb

@@ -0,0 +1,15 @@
+# experiments/agents/header_schema.rb
+
+require 'simple_json_schema_builder'
+
+require_relative 'timestamp'
+
+class Agent99::HeaderSchema < SimpleJsonSchemaBuilder::Base
+  object do
+    string  :from_uuid,   required: true, examples: [SecureRandom.uuid]
+    string  :to_uuid,     required: true, examples: [SecureRandom.uuid]
+    string  :event_uuid,  required: true, examples: [SecureRandom.uuid]
+    string  :type,        required: true, examples: %w[request response control]
+    integer :timestamp,   required: true, examples: [Agent99::Timestamp.new.to_i]
+  end
+end

data/lib/agent99/message_processing.rb

@@ -0,0 +1,155 @@
+# lib/agent99/message_processing.rb
+
+module Agent99::MessageProcessing
+
+
+  # Starts the agent's main loop for processing messages.
+  #
+  def run
+    dispatcher
+  end
+
+  ################################################
+  private
+
+  # Main message dispatching loop.
+  #
+  def dispatcher
+    @start_time = Time.now
+    @paused = false
+    @config = {}
+
+    message_client.listen_for_messages(
+      queue,
+      request_handler: ->(message) { process_request(message) unless paused? },
+      response_handler: ->(message) { process_response(message) unless paused? },
+      control_handler: ->(message) { process_control(message) }
+    )
+  end
+
+
+  # Processes incoming request messages.
+  #
+  # @param message [Hash] The incoming message
+  #
+  def process_request(message)
+    @payload = message
+    @header = payload[:header]
+    return unless validate_schema.empty?
+    receive_request
+  end
+
+  # Processes incoming response messages.
+  #
+  # @param message [Hash] The incoming message
+  #
+  def process_response(message)
+    @payload = message
+    receive_response
+  end
+
+  # Processes incoming control messages.
+  #
+  # @param message [Hash] The incoming message
+  #
+  def process_control(message)
+    @payload = message
+    receive_control
+  end
+
+
+
+  # Handles incoming request messages (to be overridden by subclasses).
+  #
+  def receive_request
+    logger.info "Received request: #{payload}"
+  end
+
+
+  # Handles incoming response messages (to be overridden by subclasses).
+  #
+  def receive_response
+    logger.info "Received response: #{payload}"
+  end
+
+
+  # Processes incoming control messages.
+  #
+  # @raise [StandardError] If there's an error processing the control message
+  #
+  def receive_control
+    action = payload[:action]
+    handler = CONTROL_HANDLERS[action]
+    
+    if handler
+      send(handler)
+    else
+      logger.warn "Unknown control action: #{action}"
+    end
+  
+  rescue StandardError => e
+    logger.error "Error processing control message: #{e.message}"
+    send_control_response("Error", { error: e.message })
+  end
+
+
+  # Sends a response message.
+  #
+  # @param response [Hash] The response to send
+  #
+  def send_response(response)
+    response[:header] = return_address
+    @message_client.publish(response)
+  end
+
+
+  # Sends a control response message.
+  #
+  # @param message [String] The response message
+  # @param data [Hash, nil] Additional data to include in the response
+  #
+  def send_control_response(message, data = nil)
+    response = {
+      header: return_address.merge(type: 'control'),
+      message: message,
+      data: data
+    }
+    @message_client.publish(response)
+  end
+
+  # Validates the incoming message against the defined schema.
+  #
+  # @return [Array] An array of validation errors, empty if validation succeeds
+  #
+  def validate_schema
+    schema = JsonSchema.parse!(self.class::REQUEST_SCHEMA)
+    schema.expand_references!
+    validator = JsonSchema::Validator.new(schema)
+    
+    validator.validate(@payload)
+    []
+  
+  rescue JsonSchema::ValidationError => e
+    handle_error("Validation error", e)
+    send_response(type: 'error', errors: e.messages)
+    e.messages
+  end
+
+  # Retrieves a field from the payload or returns a default value.
+  #
+  # @param field [Symbol] The field to retrieve
+  # @return [Object] The value of the field or its default
+  #
+  def get(field)
+    payload[field] || default(field)
+  end
+
+  # Returns the default value for a field from the schema.
+  #
+  # @param field [Symbol] The field to get the default for
+  # @return [Object, nil] The default value or nil if not found
+  #
+  def default(field)
+    self.class::REQUEST_SCHEMA.dig(:properties, field, :examples)&.first
+  end
+end

data/lib/agent99/nats_message_client.rb

@@ -0,0 +1,101 @@
+# lib/agent99/nats_message_client.rb
+
+require 'nats/client'
+require 'json'
+require 'logger'
+
+class Agent99::NatsMessageClient
+  @instance = nil
+
+  class << self
+    def instance
+      @instance ||= new
+    end
+  end
+
+  attr_accessor :logger, :nats
+
+  def initialize(logger: Logger.new($stdout))
+    @nats = create_nats_connection
+    @logger = logger
+  end
+
+  def setup(agent_id:, logger:)
+    @logger = logger
+    # NATS doesn't require explicit queue creation, so we'll just return the agent_id
+    agent_id
+  end
+
+  def listen_for_messages(
+    queue,
+    request_handler:,
+    response_handler:,
+    control_handler:
+  )
+    @nats.subscribe(queue) do |msg|
+      message = JSON.parse(msg.data, symbolize_names: true)
+      logger.debug "Received message: #{message.inspect}"
+
+      type = message.dig(:header, :type)
+
+      case type
+      when "request"
+        request_handler.call(message)
+      when "response"
+        response_handler.call(message)
+      when "control"
+        control_handler.call(message)
+      else
+        raise NotImplementedError, "Unsupported message type: #{type}"
+      end
+    end
+
+    # Keep the connection open
+    loop { sleep 1 }
+  end
+
+  def publish(message)
+    queue_name = message.dig(:header, :to_uuid)
+
+    begin
+      json_payload = JSON.generate(message)
+
+      @nats.publish(queue_name, json_payload)
+
+      logger.info "Message published successfully to queue: #{queue_name}"
+      
+      # Return a success status
+      { success: true, message: "Message published successfully" }
+    
+    rescue JSON::GeneratorError => e
+      logger.error "Failed to convert payload to JSON: #{e.message}"
+      { success: false, error: "JSON conversion error: #{e.message}" }
+    
+    rescue NATS::IO::TimeoutError => e
+      logger.error "Failed to publish message: #{e.message}"
+      { success: false, error: "Publishing error: #{e.message}" }
+    
+    rescue StandardError => e
+      logger.error "Unexpected error while publishing message: #{e.message}"
+      { success: false, error: "Unexpected error: #{e.message}" }
+    end
+  end
+
+  def delete_queue(queue_name)
+    # NATS doesn't have the concept of deleting queues.
+    # Subjects are automatically cleaned up when there are no more subscribers.
+    logger.info "NATS doesn't require explicit queue deletion. Subject #{queue_name} will be automatically cleaned up."
+  end
+
+
+  ################################################
+  private
+  
+  def create_nats_connection
+    NATS.connect
+  rescue NATS::IO::ConnectError => e
+    logger.error "Failed to connect to NATS: #{e.message}"
+    raise "NATS Connection Error: #{e.message}. Please check your NATS server and try again."
+  end
+end
+

data/lib/agent99/registry_client.rb

@@ -0,0 +1,73 @@
+# experiments/agents/agent99/registry_client.rb
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+class Agent99::RegistryClient
+  attr_accessor :logger
+
+  def initialize(
+      base_url: ENV.fetch('REGISTRY_BASE_URL', 'http://localhost:4567'),
+      logger:   Logger.new($stdout)
+    )
+    @base_url = base_url
+    @logger   = logger
+    @http_client = Net::HTTP.new(URI.parse(base_url).host, URI.parse(base_url).port)
+  end
+
+  def register(name:, capabilities:)
+    request = create_request(:post, "/register", { name: name, capabilities: capabilities })
+    @id = send_request(request)
+  end
+
+  def withdraw(id)
+    return logger.warn("Agent not registered") unless id
+
+    request = create_request(:delete, "/withdraw/#{id}")
+    send_request(request)
+  end
+
+
+  def discover(capability:)
+    encoded_capability = URI.encode_www_form_component(capability)
+    request = create_request(:get, "/discover?capability=#{encoded_capability}")
+    send_request(request)
+  end
+
+  ################################################
+  private
+
+  def create_request(method, path, body = nil)
+    request = Object.const_get("Net::HTTP::#{method.capitalize}").new(path, { "Content-Type" => "application/json" })
+    request.body = body.to_json if body
+    request
+  end
+
+  def send_request(request)
+    response = @http_client.request(request)
+
+    handle_response(response)
+  rescue JSON::ParserError => e
+    logger.error "JSON parsing error: #{e.message}"
+    nil
+  rescue StandardError => e
+    logger.error "Request error: #{e.message}"
+    nil
+  end
+
+  def handle_response(response)
+    case response
+    when Net::HTTPOK
+      JSON.parse(response.body, symbolize_names: true)
+    when Net::HTTPCreated
+      JSON.parse(response.body, symbolize_names: true)[:uuid]
+    when Net::HTTPNoContent
+      logger.info "Action completed successfully."
+      nil
+    else
+      logger.error "Error: #{JSON.parse(response.body, symbolize_names: true)[:error]}"
+      nil
+    end
+  end
+end