agent99 0.0.2 → 0.0.4

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/maxwell_agent86.rb

@@ -10,12 +10,21 @@ require_relative '../lib/agent99'
 require_relative 'maxwell_request'
 
 class MaxwellAgent86 < Agent99::Base
-  REQUEST_SCHEMA  = MaxwellRequest.schema
-  TYPE            = :server
-
-  # RESPONSE_SCHEMA = Agent99::RESPONSE.schema
-  # ERROR_SCHEMA    = Agent99::ERROR.schema
-
+  # this information is made available when the agent
+  # registers with the central registry service.  It is
+  # made available during the discovery process.
+  #
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     %w[ greeter hello_world hello-world hello],
+      request_schema:   MaxwellRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end
 
   #######################################
   private
@@ -90,26 +99,6 @@ class MaxwellAgent86 < Agent99::Base
   def receive_response(response)
     loger.warn("Unexpected response type message: response.inspect")
   end
-
-
-  # 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.
-  #
-  # For now, lets just go with the Array of Strings.
-  #
-  def capabilities
-    %w[ greeter hello_world hello-world hello]   
-  end
 end
 
 # Example usage

data/examples/registry.rb

@@ -8,8 +8,11 @@ require 'sinatra'
 require 'json'
 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.
 #
@@ -24,14 +27,22 @@ end
 # Endpoint to register an agent
 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_REGISTRY << agent_info.merge({uuid: agent_uuid})
+  request_data  = JSON.parse(request.body.read, symbolize_names: true)
+  debug_me{[
+    :request_data
+  ]}
+  agent_name    = request_data[:name]
+  agent_uuid    = SecureRandom.uuid
+  
+  debug_me{[
+    :agent_name,
+    :agent_uuid
+  ]}
+
+  # Ensure capabilities are lowercase
+  request_data[:capabilities].map!{|c| c.downcase}
+  
+  AGENT_REGISTRY << request_data.merge({uuid: agent_uuid})
 
   status 201
   content_type :json
@@ -42,10 +53,10 @@ 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)
+    agent[:capabilities]&.include?(capability)
   end
 
   content_type :json
@@ -77,4 +88,4 @@ end
 # Start the Sinatra server
 if __FILE__ == $PROGRAM_NAME
   Sinatra::Application.run!
-end
+end

data/lib/agent99/agent_discovery.rb

@@ -32,4 +32,8 @@ module Agent99::AgentDiscovery
 
     all ? result : result.sample(how_many)
   end
+
+  def add_agent(agent_info)
+    @agents[agent_info[:uuid]] = agent_info
+  end
 end

data/lib/agent99/agent_lifecycle.rb

@@ -11,16 +11,19 @@ module Agent99::AgentLifecycle
   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
+    @agents           = {}
+    @payload          = nil
+    @name             = self.class.name
+    @capabilities     = capabilities
+    @id               = nil
+    @registry_client  = registry_client
+    @message_client   = message_client
+    @logger           = logger
+
+    validate_info_keys
 
     @registry_client.logger = logger
-    register
+    register(info)
 
     @queue = message_client.setup(agent_id: id, logger:)
 
@@ -29,12 +32,33 @@ module Agent99::AgentLifecycle
     setup_signal_handlers
   end
 
+
+  def validate_info_keys
+    required_keys = [:name, :capabilities]
+    if respond_to? :info
+      missing_keys = required_keys - info.keys
+      unless missing_keys.empty?
+        logger.error <<~MESSAGE
+          This agent's info method is missing 
+          #{1 == missing_keys.size ? 'a required key' : 'some required keys'}: 
+          #{missing_keys}
+        MESSAGE
+        .split("\n").join
+        exit(1)
+      end
+    else
+      logger.error "An agent must implement the info method"
+      exit(1)
+    end
+  end
+
+
   # Registers the agent with the registry service.
   #
   # @raise [StandardError] If registration fails
   #
-  def register
-    @id = registry_client.register(name:, capabilities:)
+  def register(agent_info)
+    @id = registry_client.register(info: agent_info)
     logger.info "Registered Agent #{name} with ID: #{id}"
   rescue StandardError => e
     handle_error("Error during registration", e)

data/lib/agent99/base.rb

@@ -37,7 +37,11 @@ class Agent99::Base
 
   MESSAGE_TYPES = %w[request response control]
 
-  attr_reader :id, :capabilities, :name, :payload, :header, :logger, :queue
+  attr_reader :id, :capabilities, :name
+  attr_reader :payload, :header, :queue
+  attr_reader :logger
+  attr_reader :agents
+  
   attr_accessor :registry_client, :message_client
 
 

data/lib/agent99/header_schema.rb

@@ -13,3 +13,8 @@ class Agent99::HeaderSchema < SimpleJsonSchemaBuilder::Base
     integer :timestamp,   required: true, examples: [Agent99::Timestamp.new.to_i]
   end
 end
+
+__END__
+
+    string :type, required: true, enum: %w[request response control]
+

data/lib/agent99/message_processing.rb

@@ -128,7 +128,9 @@ module Agent99::MessageProcessing
   # @return [Array] An array of validation errors, empty if validation succeeds
   #
   def validate_schema
-    schema = JsonSchema.parse!(self.class::REQUEST_SCHEMA)
+    return unless info[:request_schema]
+    
+    schema = JsonSchema.parse!(info[:request_schema])
     schema.expand_references!
     validator = JsonSchema::Validator.new(schema)
     

data/lib/agent99/registry_client.rb

@@ -8,17 +8,18 @@ class Agent99::RegistryClient
   attr_accessor :logger
 
   def initialize(
-      base_url: ENV.fetch('REGISTRY_BASE_URL', 'http://localhost:4567'),
+      base_url: ENV.fetch('AGENT99_REGISTRY_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)
+    @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)
+  def register(info:)
+    payload = info
+    request = create_request(:post, "/register", payload)
+    @id     = send_request(request)
   end
 
   def withdraw(id)
@@ -37,16 +38,16 @@ class Agent99::RegistryClient
 
 
   def fetch_all_agents
-    request = create_request(:get, "/")
-    response = send_request(request)
+    request   = create_request(:get, "/")
+    response  = 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       = Object.const_get("Net::HTTP::#{method.capitalize}").new(path, { "Content-Type" => "application/json" })
+    request.body  = body.to_json if body
     request
   end
 

data/lib/agent99/tcp_message_client.rb

@@ -0,0 +1,183 @@
+# lib/agent99/tcp_message_client.rb
+#
+# NOTE: This is an early attempt at a true
+#       peer-to-peer messaging platform.  Its not
+#       not ready for prime time.
+
+require 'socket'
+require 'json'
+require 'logger'
+
+class Agent99::TcpMessageClient
+  attr_accessor :agents
+
+  def initialize(
+      agents: {},
+      logger: Logger.new($stdout)
+    )
+    @agents             = agents
+    @logger             = logger
+    @server_socket      = nil
+    @client_connections = {}
+    @handlers           = {}
+    @running            = false
+  end
+
+  def listen_for_messages(queue, request_handler:, response_handler:, control_handler:)
+    @handlers = {
+      request:  request_handler,
+      response: response_handler,
+      control:  control_handler
+    }
+    
+    start_server(queue[:port])
+  end
+
+  def publish(message)
+    target = message.dig(:header, :to_uuid)
+    return unless target
+
+    agent_info = agents(target)
+    return unless agent_info
+
+    socket = connect_to_agent(agent_info[:ip], agent_info[:port])
+    return unless socket
+
+    begin
+      socket.puts(message.to_json)
+      true
+    
+    rescue StandardError => e
+      @logger.error("Failed to send message: #{e.message}")
+      false
+    
+    ensure
+      socket.close unless socket.closed?
+    end
+  end
+
+  def stop
+    @running = false
+    @server_socket&.close
+    @client_connections.each_value(&:close)
+    @client_connections.clear
+  end
+
+  private
+
+  def start_server(port)
+    @server_socket  = TCPServer.new(port)
+    @running        = true
+
+    Thread.new do
+      while @running
+        begin
+          client = @server_socket.accept
+          handle_client(client)
+        rescue StandardError => e
+          @logger.error("Server error: #{e.message}")
+        end
+      end
+    end
+  end
+
+  def handle_client(client)
+    Thread.new do
+      while @running
+        begin
+          message = client.gets
+          break if message.nil?
+
+          parsed_message = JSON.parse(message, symbolize_names: true)
+          route_message(parsed_message)
+        
+        rescue JSON::ParserError => e
+          @logger.error("Invalid JSON received: #{e.message}")
+        
+        rescue StandardError => e
+          @logger.error("Error handling client: #{e.message}")
+          break
+        end
+      end
+      
+      client.close unless client.closed?
+    end
+  end
+
+  def route_message(message)
+    type    = message.dig(:header, :type)&.to_sym
+    handler = @handlers[type]
+    
+    if handler
+      handler.call(message)
+    else
+      @logger.warn("No handler for message type: #{type}")
+    end
+  end
+
+  def connect_to_agent(ip, port)
+    TCPSocket.new(ip, port)
+  
+  rescue StandardError => e
+    @logger.error("Failed to connect to #{ip}:#{port}: #{e.message}")
+    nil
+  end
+end
+
+
+__END__
+
+Based on the provided code for the `Agent99::TcpMessageClient` class, here's an analysis of your questions:
+
+1. Does this class queue up JSON messages while a previous message is being processed?
+
+No, this class does not explicitly queue up JSON messages while a previous message is being processed. The class processes messages as they are received, without maintaining an internal queue. Each incoming message is handled in its own thread (see the `handle_client` method), which allows for concurrent processing of messages from multiple clients.
+
+2. Does it present a complete JSON message at once or does it only provide part of one?
+
+The class attempts to present complete JSON messages at once. Here's why:
+
+- In the `handle_client` method, messages are read using `client.gets`, which typically reads a full line of input (up to a newline character).
+- The received message is then parsed as JSON using `JSON.parse(message, symbolize_names: true)`.
+- If the parsing is successful, the entire parsed message is passed to the `route_message` method.
+
+However, there are a few potential issues to consider:
+
+- If a JSON message spans multiple lines, `client.gets` might not capture the entire message in one read.
+- There's no explicit handling for partial messages or message boundaries.
+- Large messages might be split across multiple TCP packets, and the current implementation doesn't account for reassembling these.
+
+To ensure complete message handling, you might want to consider implementing a more robust message framing protocol, such as using message length prefixes or delimiter-based framing.
+
+For example, you could modify the `handle_client` method to use a delimiter-based approach:
+
+```ruby
+def handle_client(client)
+  Thread.new do
+    buffer = ""
+    while @running
+      begin
+        chunk = client.readpartial(1024)
+        buffer += chunk
+        while (message_end = buffer.index("\n"))
+          message      = buffer[0...message_end]
+          buffer       = buffer[(message_end + 1)..]
+          parsed_message = JSON.parse(message, symbolize_names: true)
+          route_message(parsed_message)
+        end
+      rescue EOFError
+        break
+      rescue JSON::ParserError => e
+        @logger.error("Invalid JSON received: #{e.message}")
+      rescue StandardError => e
+        @logger.error("Error handling client: #{e.message}")
+        break
+      end
+    end
+    client.close unless client.closed?
+  end
+end
+```
+
+This modification would allow for handling of messages that might be split across multiple reads, ensuring that complete JSON messages are processed.
+

data/lib/agent99/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Agent99
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 
   def self.version  = VERSION
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agent99
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-07 00:00:00.000000000 Z
+date: 2024-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: amazing_print
   requirement: !ruby/object:Gem::Requirement
@@ -138,12 +152,44 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- docs/todo.md
+- docs/README.md
+- docs/advanced_features.md
+- docs/agent99_framework/central_registry.md
+- docs/agent99_framework/message_client.md
+- docs/agent99_framework/registry_client.md
+- docs/agent_discovery.md
+- docs/agent_lifecycle.md
+- docs/agent_registry_processes.md
+- docs/api_reference.md
+- docs/architecture.md
+- docs/breaking_change_v0.0.4.md
+- docs/configuration.md
+- docs/control_actions.md
+- docs/custom_agent_implementation.md
+- docs/diagrams/agent_registry_processes.dot
+- docs/diagrams/agent_registry_processes.png
+- docs/diagrams/high_level_architecture.dot
+- docs/diagrams/high_level_architecture.png
+- docs/diagrams/request_flow.dot
+- docs/diagrams/request_flow.png
+- docs/error_handling_and_logging.md
+- docs/extending_the_framework.md
+- docs/message_processing.md
+- docs/messaging_system.md
+- docs/preformance_considerations.md
+- docs/schema_definition.md
+- docs/security.md
+- docs/troubleshooting.md
+- docs/what_is_an_agent.md
 - examples/README.md
+- examples/agent_watcher.rb
+- examples/agents/.keep
 - examples/chief_agent.rb
 - examples/control.rb
 - examples/diagram.dot
 - examples/diagram.png
+- examples/example_agent.rb
+- examples/kaos_spy.rb
 - examples/maxwell_agent86.rb
 - examples/maxwell_request.rb
 - examples/registry.rb
@@ -160,6 +206,7 @@ files:
 - lib/agent99/message_processing.rb
 - lib/agent99/nats_message_client.rb
 - lib/agent99/registry_client.rb
+- lib/agent99/tcp_message_client.rb
 - lib/agent99/timestamp.rb
 - lib/agent99/version.rb
 - sig/ai_agent.rbs

data/docs/todo.md

@@ -1,66 +0,0 @@
-# Documentation
-
-TODO: Lets get some more detailed documentation underway that can be linked to from the main README.md file.
-
-Here are some key areas that should be covered in comprehensive documentation files:
-
-1. Architecture Overview:
-   - Explain the overall structure of the AiAgent framework
-   - Describe the roles of different components (Base, MessageClient, RegistryClient, etc.)
-   - Illustrate how agents communicate and interact within the system
-
-2. Agent Lifecycle:
-   - Detail the process of creating, initializing, running, and shutting down an agent
-   - Explain the registration and withdrawal process with the registry service
-
-3. Message Processing:
-   - Describe the different types of messages (request, response, control)
-   - Explain how messages are routed and processed
-   - Detail the schema validation process for incoming messages
-
-4. Agent Discovery:
-   - Explain how agents can discover other agents based on capabilities
-   - Describe the process of querying the registry for available agents
-
-5. Control Actions:
-   - List and explain all available control actions (shutdown, pause, resume, etc.)
-   - Describe how to implement custom control actions
-
-6. Configuration:
-   - Detail all configuration options available for agents
-   - Explain how to use environment variables for configuration
-
-7. Error Handling and Logging:
-   - Describe the error handling mechanisms in place
-   - Explain how to configure and use the logging system effectively
-
-8. Messaging Systems:
-   - Provide details on both AMQP and NATS messaging systems
-   - Explain how to switch between different messaging backends
-
-9. Custom Agent Implementation:
-   - Provide a step-by-step guide on creating a custom agent
-   - Explain how to define capabilities, handle requests, and send responses
-
-10. Schema Definition:
-    - Explain how to define and use request and response schemas
-    - Provide examples of complex schema definitions
-
-11. Performance Considerations:
-    - Discuss any performance optimizations in the framework
-    - Provide guidelines for writing efficient agents
-
-12. Security:
-    - Explain any security measures in place (if any)
-    - Provide best practices for securing agent communications
-
-13. Extending the Framework:
-    - Describe how to add new features or modify existing functionality
-    - Explain the plugin system (if one exists)
-
-14. Troubleshooting:
-    - Provide a list of common issues and their solutions
-    - Explain how to debug agents effectively
-
-15. API Reference:
-    - Provide a comprehensive API reference for all public methods and classes