agent99 0.0.1 → 0.0.3

data/examples/chief_agent.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# examples/chief_agent.rb
+#
+# This program is a type :client agent.
+#
+# This program calls a CLI program named boxes to highlight
+# the response received to the request that it sent.
+#
+# brew install boxes
+#
+# Run this program several times to see if Maxwell Agent86
+# messes up his mission which he is prone to do half the time.
+
+require_relative '../lib/agent99'
+
+class ChiefAgent < Agent99::Base
+  TYPE = :client
+
+  # init is called at the end of the initialization process.
+  # It may be only something that a :client type agent would do.
+  #
+  # For this client it sends out a request as its first order of
+  # business and expects to receive a response.
+  #
+  def init
+    action  = 'greeter'
+    agent   = discover_agent(
+                capability: action, 
+                how_many:   1
+              ).first[:uuid]
+
+    send_request(agent:)
+
+  rescue Exception => e
+    logger.warn "No Agents are available as #{action}"
+    exit(1)
+  end
+
+
+  ##################################################
+  private
+
+  def send_request(agent:)
+    request = build_request(
+                to_uuid:  agent,
+                greeting: 'Hey',
+                name:     'MadBomber'
+              )
+
+    result = @message_client.publish(request)
+    logger.info "Sent request: #{request.inspect}; status? #{result.inspect}"
+  end
+
+
+  def build_request(
+                to_uuid:,
+                greeting: 'Hello',
+                name:     'World'
+              )
+
+    {
+      header: {
+        type:       'request',
+        from_uuid:  @id,
+        to_uuid:    ,
+        event_uuid: SecureRandom.uuid,
+        timestamp:  Agent99::Timestamp.new.to_i
+      },
+      greeting:,
+      name:
+    }
+  end
+
+
+  def receive_response
+    logger.info "Received response: #{payload.inspect}"
+    result = payload[:result]
+
+    puts
+    puts `echo "#{result}" | boxes -d info`
+    puts
+
+    exit(0)
+  end
+
+
+  def capabilities
+    ['Chief of Control']
+  end
+end
+
+
+# Example usage
+client = ChiefAgent.new
+client.run
+

data/examples/control.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# control.rb
+
+require_relative '../lib/agent99'
+
+class Control < Agent99::Base
+  TYPE = :hybrid
+
+  attr_accessor :statuses
+
+  def init
+    @agents = @registry_client.fetch_all_agents
+    @statuses = {}
+  end
+
+
+  def capabilities
+    ['control', 'headquarters', 'secret underground base']
+  end
+
+
+  def send_control_message(message:, payload: {})
+    @agents.each do |agent|
+      response = @message_client.publish(
+        header: {
+          to_uuid: agent[:uuid],
+          from_uuid: @id,
+          event_uuid: SecureRandom.uuid,
+          type: 'control',
+          timestamp: Agent99::Timestamp.new.to_i
+        },
+        action: message,
+        payload: payload
+      )
+      puts "Sent #{message} to #{agent[:name]}: #{response[:success] ? 'Success' : 'Failed'}"
+    end
+  end
+
+
+  def pause_all
+    send_control_message(message: 'pause')
+  end
+
+
+  def resume_all
+    send_control_message(message: 'resume')
+  end
+
+
+  def stop_all
+    send_control_message(message: 'stop')
+  end
+
+  def get_all_status
+    @statuses.clear  # Reset statuses before new request
+    
+    @agents.each do |agent|
+      @message_client.publish(
+        header: {
+          to_uuid:    agent[:uuid],
+          from_uuid:  @id,
+          event_uuid: SecureRandom.uuid,
+          type:       'control',
+          timestamp:  Agent99::Timestamp.new.to_i
+        },
+        action: 'status'
+      )
+    end
+
+    # Wait for responses (with timeout)
+    sleep 2  # Give agents time to respond
+    @statuses
+  end
+
+  def receive_response
+    if payload[:action] == 'response' && payload[:data][:type] == 'status'
+      agent_name = payload[:header][:from_uuid]
+      @statuses[agent_name] = payload[:data]
+      logger.info "Received status from #{agent_name}: #{payload[:data]}"
+    elsif payload[:action] == 'status' && payload[:header][:from_uuid] == @id
+      # Handle our own status request
+      handle_status_request
+    end
+  end
+
+
+end
+
+
+if __FILE__ == $PROGRAM_NAME
+  control = Control.new
+  
+  # Start the message processing in a separate thread
+  dispatcher_thread = Thread.new do
+    control.run
+  end
+
+  # UI thread
+  begin
+    loop do
+      puts "\n1. Pause all agents"
+      puts "2. Resume all agents"
+      puts "3. Stop all agents"
+      puts "4. Get all agents status"
+      puts "5. Exit"
+      print "\nEnter your choice: "
+      
+      choice = gets.chomp.to_i
+
+      case choice
+      when 1
+        control.pause_all
+      when 2
+        control.resume_all
+      when 3
+        control.stop_all
+      when 4
+        statuses = control.get_all_status
+        sleep 2 # Give time for responses to arrive
+        puts JSON.pretty_generate(control.statuses)
+      when 5
+        puts "Exiting..."
+        Thread.exit
+        break
+      else
+        puts "Invalid choice. Please try again."
+      end
+    end
+  rescue Interrupt
+    puts "\nShutting down..."
+  ensure
+    dispatcher_thread.exit
+    control.fini
+  end
+end
+

data/examples/diagram.dot

@@ -0,0 +1,22 @@
+digraph agent_interaction {
+    rankdir=LR; // Left to right layout
+
+    // Define nodes for each component
+    node [shape=box];
+    ChiefAgent [label="ChiefAgent"];
+    MaxwellAgent86 [label="MaxwellAgent86"];
+    Registry [label="Registry Service"];
+
+    // Define edges for interactions
+    ChiefAgent -> Registry [label="GET /discover (greeter)"];
+    Registry -> ChiefAgent [label="Agent UUIDs"];
+
+    ChiefAgent -> MaxwellAgent86 [label="Send greet request"];
+    MaxwellAgent86 -> ChiefAgent [label="Response (Hello World)"];
+    
+    MaxwellAgent86 -> Registry [label="POST /register"];
+    Registry -> MaxwellAgent86 [label="ACK (registration)"];
+
+    ChiefAgent -> Registry [label="POST /register"];
+    Registry -> ChiefAgent [label="ACK (registration)"];
+}

data/examples/example_agent.rb

@@ -0,0 +1,26 @@
+# examples/example_agent.rb
+#
+# NOTE: This agent is meant to be loaded
+#       by the agent_watcher.rb be file.
+#       To do that first have AgentWatcher running
+#       then `cp example_agent.rb agents`
+#       AgentWatcher will see the new file arrive
+#       in the `agents` folder, will determine that the
+#       new file contains an Agent99 subclass, will
+#       load it, create a new instance of the class and
+#       finally run the new instance within its own
+#       thread as part of the AgentWatcher process.
+#
+
+require_relative '../../lib/agent99'
+
+class ExampleAgent < Agent99::Base
+  TYPE = :server
+  
+  def capabilities = %w[ rubber_stamp yes_man example ]
+  
+  def receive_request
+    logger.info "Example agent received request: #{payload}"
+    send_response(status: 'success')
+  end
+end

data/examples/kaos_spy.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# examples/kaos_spy.rb
+#
+# KAOS stood for "Kreatively Akting Out Simultaneously."
+
+require 'agent99'
+
+# Kaos captured Agent99 and forced her to reveal the
+# secrets of the centralized registry and the communication
+# network used by Control.  Max was not there to save her.
+
+require 'tty-table'
+
+class KaosSpy
+  # TODO: spread some choas!
+
+  attr_reader :registry, :comms, :agents
+
+  def initialize
+    @registry = Agent99::RegistryClient.new
+    @agents   = registry.fetch_all_agents
+    dox_control_agents
+
+    @comms    = Agent99::AmqpMessageClient.new
+    take_out_communications
+  end
+
+  def dox_control_agents
+    if agents.empty?
+      puts "\nKAOS won!  There are no Control agents in the field."
+    else
+      report = [ %w[Name Address Capabilities] ]
+
+      agents.each{|agent|
+        report << [
+                    agent[:name],
+                    agent[:uuid],
+                    agent[:capabilities].join(', ')
+                  ]
+      }
+
+      table = TTY::Table.new(report[0], report[1..])
+      puts table.render(:unicode)
+    end
+  end
+
+  def take_out_communications
+    puts
+    puts "Destroy Control's Comms Network ..."
+    puts
+
+    agents.each do |agent|
+      comms.delete_queue(agent[:uuid])
+      puts "  Agent #{agent[:name]} cannot make or receive calls@"
+    end
+  end
+end
+
+KaosSpy.new
+puts
+puts "That's all it takes - Get Smart; get security!"
+puts
+

data/examples/{hello_world.rb → maxwell_agent86.rb}

@@ -1,22 +1,31 @@
 #!/usr/bin/env ruby
-# examples/hello_world.rb
+# examples/maxwell_agent86.rb
 
-require 'json'
-require 'json_schema'
+# There are three types of agents: Server, Client and Hybrid.
+# A Server receives a requests and _may_ send a response.
+# A Client sends a request and _may_ expect a response.
+# A Hybrid _may_ act like a Server or a Client
 
 require_relative '../lib/agent99'
-require_relative 'hello_world_request'
+require_relative 'maxwell_request'
+
+class MaxwellAgent86 < Agent99::Base
+  REQUEST_SCHEMA  = MaxwellRequest.schema
+  TYPE            = :server
 
-class HelloWorld < Agent99::Base
-  REQUEST_SCHEMA  = HelloWorldRequest.schema
   # RESPONSE_SCHEMA = Agent99::RESPONSE.schema
   # ERROR_SCHEMA    = Agent99::ERROR.schema
 
+
+  #######################################
+  private
+
   # The request is in @payload
   def receive_request
     send_response( validate_request || process )
   end
 
+
   # This method validates the incoming request and returns any errors found
   # or nil if there are no errors.
   # It allows for returning an array of errors.
@@ -44,6 +53,7 @@ class HelloWorld < Agent99::Base
       }
     end
 
+
     # Validate the incoming request body against the schema
     validation_errors = validate_schema
     unless validation_errors.empty?
@@ -57,6 +67,7 @@ class HelloWorld < Agent99::Base
     responses.empty? ? nil : responses
   end
 
+
   # Returns the response value
   # All response message have the same schema in that
   # they have a header (all messages have headers) and
@@ -64,9 +75,13 @@ class HelloWorld < Agent99::Base
   # a JSON string, sure but then we would need a 
   # RESPONSE_SCHEMA constant for the class.
   def process
-    {
-      result: get(:greeting) + ' ' + get(:name)
-    }
+    result  = if 50 <= rand(100)
+                get(:greeting) + ' ' + get(:name)
+              else
+                'Missed it by that >< much.'
+              end
+
+    { result: result }
   end
 
 
@@ -76,16 +91,21 @@ class HelloWorld < Agent99::Base
     loger.warn("Unexpected response type message: response.inspect")
   end
 
-  private
 
-  # NOTE: what I'm thinking about here is similar to the
-  #       prompt tool (aka function) callback facility
-  #       where descriptive text is used to describe
-  #       what the tool does.
+  # Phase One Implementation is to do a search
+  # using the String#include? and the Array#include?
+  # methods.  If you want discrete word-based selection
+  # then use an Array of Strings to define the different
+  # things this agent can do.
+  #
+  # If you want to match on sub-strings then define the
+  # the capabilities as a String.
+  #
+  # Subsequent implementations may use a semantic search
+  # to find the agents to use in which case capabilities may
+  # be constrained to be a String.
   #
-  # TODO: scale this idea back to just keywords
-  #       until the registry program gets more
-  #       stuff added to its discovery process.
+  # For now, lets just go with the Array of Strings.
   #
   def capabilities
     %w[ greeter hello_world hello-world hello]   
@@ -93,5 +113,5 @@ class HelloWorld < Agent99::Base
 end
 
 # Example usage
-agent = HelloWorld.new
+agent = MaxwellAgent86.new
 agent.run # Starts listening for messages

data/examples/{hello_world_request.rb → maxwell_request.rb}

@@ -1,8 +1,8 @@
-# examples/hello_world_request.rb
+# examples/maxwell_request.rb
 
 require_relative '../lib/agent99/header_schema'
 
-class HelloWorldRequest < SimpleJsonSchemaBuilder::Base
+class MaxwellRequest < SimpleJsonSchemaBuilder::Base
   object do
     object :header, schema: Agent99::HeaderSchema
 

data/examples/registry.rb

@@ -6,11 +6,13 @@ include DebugMe
 
 require 'sinatra'
 require 'json'
-require 'bunny'
 require 'securerandom'
 
-# In-memory registry to store agent capabilities
-# Array(Hash)
+# In-memory registry to store agent Array(Hash)
+#
+# Agent capabilities are save as lower case.  The 
+# discovery process also compares content as lower case.
+#
 # TODO: change this data store to a sqlite database
 #       maybe with a vector search capability.
 #
@@ -26,12 +28,11 @@ end
 post '/register' do
   request.body.rewind
   agent_info = JSON.parse(request.body.read, symbolize_names: true)
-
   agent_name = agent_info[:name]
-  capabilities = agent_info[:capabilities]
-
   agent_uuid = SecureRandom.uuid
 
+  agent_info[:capabilities].map!{|c| c.downcase}
+
   AGENT_REGISTRY << agent_info.merge({uuid: agent_uuid})
 
   status 201
@@ -43,7 +44,7 @@ end
 # TODO: This is a simple keyword matcher.  Looking
 # =>    for a semantic match process.
 get '/discover' do
-  capability = params['capability']
+  capability = params['capability'].downcase
 
   matching_agents = AGENT_REGISTRY.select do |agent|
     agent[:capabilities].include?(capability)

data/examples/start_rabbitmq_and_registry.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# examples/start_rabbitmq_and_registry.sh
+#
+# brew install rabbitmq-server
+#
+# Start up the AMQP message broker (RabbitM@) in the background
+
+echo "Starting rabbitmq-server in background ..."
+rabbitmq-server &
+sleep 2
+open http://localhost:15672/#/queues
+
+echo
+echo
+echo "Starting example registry in forground ..."
+echo "http://localhost:4567"
+echo
+ruby registry.rb  # blocks until control-C
+
+# You may have to do control-c twice to stop both
+
+echo "#"
+echo "##"
+echo "###"
+echo "####"
+echo "#####"
+echo "registry is stopped"
+echo "stopping the rabbitmq server ...."
+rabbitmqctl stop

data/lib/agent99/agent_lifecycle.rb

@@ -48,9 +48,21 @@ module Agent99::AgentLifecycle
   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
+
   ################################################
   private
-
+  
   # Checks if the agent is currently paused.
   #
   # @return [Boolean] True if the agent is paused, false otherwise
@@ -71,17 +83,4 @@ module Agent99::AgentLifecycle
       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
+end

data/lib/agent99/amqp_message_client.rb

@@ -6,6 +6,19 @@ require 'json_schema'
 require 'logger'
 
 class Agent99::AmqpMessageClient
+  CONFIG = {
+    host:           "127.0.0.1",
+    port:           5672,
+    ssl:            false,
+    vhost:          "/",
+    user:           "guest",
+    pass:           "guest",
+    heartbeat:      :server, # will use RabbitMQ setting
+    frame_max:      131072,
+    auth_mechanism: "PLAIN"
+  }
+
+
   QUEUE_TTL = 60_000 # 60 seconds TTL
   @instance = nil
 
@@ -17,16 +30,21 @@ class Agent99::AmqpMessageClient
 
   attr_accessor :logger, :channel, :exchange
 
-  def initialize(logger: Logger.new($stdout))
+  def initialize(
+      config: CONFIG,
+      logger: Logger.new($stdout))
+    @config     = config
     @connection = create_amqp_connection
-    @channel  = @connection.create_channel
-    @exchange = @channel.default_exchange
-    @logger   = logger
+    @channel    = @connection.create_channel
+    @exchange   = @channel.default_exchange
+    @logger     = logger
   end
 
   def setup(agent_id:, logger:)
     queue = create_queue(agent_id)
     
+    logger.info "Created queue for agent_id: #{agent_id}"
+
     # Returning the queue to be used in the Base class
     queue
   end
@@ -66,26 +84,39 @@ class Agent99::AmqpMessageClient
     queue_name = message.dig(:header, :to_uuid)
 
     begin
+      # FIXME: message.to_json
       json_payload = JSON.generate(message)
 
       exchange.publish(json_payload, routing_key: queue_name)
 
-      logger.info "Message published successfully to queue: #{queue_name}"
+      logger.info "#{message.dig(:header,:type).to_s.upcase} message published successfully to queue: #{queue_name}"
       
       # Return a success status
-      { success: true, message: "Message published successfully" }
+      { 
+        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}" }
+      { 
+        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}" }
+      { 
+        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}" }
+      { 
+        success:  false, 
+        error:    "Unexpected error: #{e.message}" 
+      }
     end
   end
 
@@ -109,7 +140,7 @@ class Agent99::AmqpMessageClient
   private
   
   def create_amqp_connection
-    Bunny.new.tap(&:start)
+    Bunny.new(@config).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."