agent99 0.0.2 → 0.0.3

data/docs/messaging_system.md

@@ -0,0 +1,129 @@
+# Agent99 Framework
+
+## Messaging Systems
+
+Agent99 supports both AMQP and NATS messaging systems, allowing you to choose the most appropriate messaging backend for your needs. The framework provides a consistent interface regardless of which messaging system you use.
+
+### Supported Message Brokers
+
+#### AMQP (RabbitMQ)
+The AMQP implementation uses RabbitMQ as the message broker and provides:
+
+- **Durability**: Messages can persist across broker restarts
+- **Queue TTL**: Queues automatically expire after 60 seconds of inactivity
+- **Automatic Reconnection**: Handles connection drops gracefully
+- **Default Configuration**:
+  ```ruby
+  {
+    host: "127.0.0.1",
+    port: 5672,
+    ssl: false,
+    vhost: "/",
+    user: "guest",
+    pass: "guest",
+    heartbeat: :server,
+    frame_max: 131072,
+    auth_mechanism: "PLAIN"
+  }
+  ```
+
+#### NATS
+The NATS implementation provides:
+
+- **Lightweight**: Simple pub/sub with minimal overhead
+- **Auto-Pruning**: Automatically cleans up unused subjects
+- **High Performance**: Optimized for speed and throughput
+- **Default Configuration**: Uses NATS default connection settings
+
+### Choosing a Message Client
+
+You can select your messaging backend when initializing an agent:
+
+```ruby
+# For AMQP
+agent = MyAgent.new(message_client: Agent99::AmqpMessageClient.new)
+
+# For NATS
+agent = MyAgent.new(message_client: Agent99::NatsMessageClient.new)
+```
+
+Or configure it via environment variables:
+
+TODO: Need to add this to the configuration class which is still TBD
+
+```bash
+# For AMQP
+export MESSAGE_SYSTEM=amqp
+export RABBITMQ_URL=amqp://guest:guest@localhost:5672
+
+# For NATS
+export MESSAGE_SYSTEM=nats
+export NATS_URL=nats://localhost:4222
+```
+
+### Message Handling
+
+Both implementations support these core operations:
+
+1. **Queue Setup**:
+   ```ruby
+   queue = message_client.setup(agent_id: id, logger: logger)
+   ```
+
+2. **Message Publishing**:
+   ```ruby
+   message_client.publish({
+     header: {
+       type:        "request",
+       to_uuid:     recipient_id,
+       from_uuid:   sender_id,
+       event_uuid:  event_id,
+       timestamp:   Agent99::Timestamp.new.to_i
+     },
+     data: payload # or whatever for the agent.
+   })
+   ```
+
+3. **Message Subscription**:
+   ```ruby
+   message_client.listen_for_messages(
+     queue,
+     request_handler:   ->(msg) { handle_request(msg) },
+     response_handler:  ->(msg) { handle_response(msg) },
+     control_handler:   ->(msg) { handle_control(msg) }
+   )
+   ```
+
+### Key Differences
+
+1. **Queue Management**:
+   - AMQP: Explicit queue creation and deletion
+   - NATS: Implicit subject-based routing
+
+2. **Message Persistence**:
+   - AMQP: Supports persistent messages and queues
+   - NATS: Ephemeral messaging by default
+
+3. **Error Handling**:
+   - AMQP: Provides detailed connection and channel errors
+   - NATS: Simplified error handling with auto-reconnect
+
+### Best Practices
+
+1. **Error Handling**: Always wrap message operations in begin/rescue blocks
+2. **Logging**: Use the provided logger for debugging and monitoring
+3. **Configuration**: Use environment variables for deployment flexibility
+4. **Testing**: Test your agents with both messaging systems to ensure compatibility
+
+### Monitoring
+
+Both implementations provide logging for:
+- Message publication success/failure
+- Queue creation and deletion
+- Connection status
+- Error conditions
+
+Use the logger to monitor your messaging system:
+```ruby
+message_client.logger.level = Logger::DEBUG  # For detailed logging
+```

data/docs/preformance_considerations.md

@@ -0,0 +1,9 @@
+# Agent99 Framework
+
+## Performance Considerations
+
+To ensure optimal performance:
+
+- Optimize message processing by minimizing complex logic in request handlers.
+- Use asynchronous processing wherever possible to prevent blocking operations.
+- Profile agent performance during development to identify bottlenecks.

data/docs/schema_definition.md

@@ -0,0 +1,78 @@
+# Agent99 Framework
+
+## Schema Definition
+
+Agent99 uses `SimpleJsonSchemaBuilder` for defining message schemas. This gem was chosen for its Ruby-like DSL that makes schema definitions readable and maintainable, while still producing JSON Schema compatible output.
+
+### Header Schema
+
+All messages in Agent99 must include a header that conforms to this schema:
+
+```ruby
+class Agent99::HeaderSchema < SimpleJsonSchemaBuilder::Base
+  object do
+    string :type,       required: true, 
+                          enum: %w[request response control]
+    string  :to_uuid,   required: true
+    string  :from_uuid, required: true
+    string  :event_uuid,required: true
+    integer :timestamp, required: true
+  end
+end
+```
+
+### Request Schema Example
+
+Define your agent's request schema by inheriting from SimpleJsonSchemaBuilder::Base:
+
+```ruby
+class MyAgentRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+    string :greeting, required: false,  examples: ["Hello"]
+    string :name,     required: true,   examples: ["World"]
+  end
+end
+```
+
+In this example, the agent has two parameters that it uses from the request message: greeting and name; however, greeting is not required.  **The Agent99 framework will use the first item in the examples array as a default for optional parameters.**
+
+### Automatic Schema Validation
+
+Agent99 automatically validates incoming request messages against your agent's REQUEST_SCHEMA:
+
+1. When a request arrives, the framework checks if your agent class defines REQUEST_SCHEMA
+2. If defined, the message is validated before reaching your receive_request method
+3. If validation fails:
+   - An error response is automatically sent back to the requester
+   - Your receive_request method is not called
+   - The validation errors are logged
+
+Example validation error response:
+
+```ruby
+{
+  header: {
+    type:       'error',
+    to_uuid:    original_from_uuid,
+    from_uuid:  agent_id,
+    event_uuid: original_event_uuid,
+    timestamp:  current_timestamp
+  },
+  errors: ['Required property "name" not found in request']
+}
+```
+
+### Why SimpleJsonSchemaBuilder?
+
+SimpleJsonSchemaBuilder was chosen for Agent99 because it:
+
+1. Provides a Ruby-native DSL for schema definition
+2. Generates standard JSON Schema output
+3. Supports schema composition and reuse
+4. Includes built-in validation
+5. Has excellent performance characteristics
+6. Maintains type safety through static analysis
+
+The gem allows us to define schemas that are both human-readable and machine-validatable, while staying within the Ruby ecosystem.
+

data/docs/security.md

@@ -0,0 +1,9 @@
+# Agent99 Framework
+
+## Security
+
+While Agent99 focuses on communication efficiency, it is recommended to implement security measures like:
+
+- Encrypting messages in transit.
+- Using secure protocols for messaging (e.g., AMQPS or NATS with TLS).
+- Implementing access control mechanisms for sensitive operations.

data/docs/troubleshooting.md

@@ -0,0 +1,11 @@
+# Agent99 Framework
+
+## Troubleshooting
+
+Common issues may include:
+
+- Failed registrations: Ensure that your registry URL is correctly configured.
+- Message routing issues: Verify routing keys and message schemata.
+- Unhandled exceptions: Check logs for details.
+
+For effective debugging, use the logging facilities provided and monitor agent activities.

data/examples/README.md

@@ -45,6 +45,49 @@ This file implements a simple registry service for AI agents using Sinatra.
   - DELETE `/withdraw/:uuid`: Withdraws an agent from the registry
   - GET `/`: Lists all registered agents
 
+### 5. control_agent.rb
+
+Example use of control messages.
+
+### 6. kaos_spy.rb
+  - Agent 99 was kinnapped by KAOS and forced to reveal the secrets of Control's centralized registry and communications network.
+  - The KAOS spy raided hacked the registry, stole the records for all of Control's agents in the field and DOX'ed them on social media.
+  - That was not enough for KAOS.  Knowing the secret UUID for each agent, KAOS proceeded to turn off the communication network one queue at a time.
+  - Get Smart -- Get Security
+
+### 7. agent_watcher.rb
+
+This file implements an agent watcher that dynamically loads and runs new agents.
+
+- Class: `AgentWatcher < Agent99::Base`
+- Functionality: Monitors a specified directory for new Ruby files and loads them as agents
+- Key features:
+  - Watches a configurable directory (default: './agents')
+  - Detects new .rb files added to the watched directory
+  - Dynamically loads new files as Ruby agents
+  - Instantiates and runs each new agent in a separate thread
+  - Handles errors during the loading and running process
+  - Terminates all loaded agents when the watcher is stopped
+- Key methods:
+  - `init`: Sets up the file watcher
+  - `setup_watcher`: Configures the directory listener
+  - `handle_new_agent`: Processes newly detected agent files
+
+### 8. example_agent.rb
+
+This file provides a simple example agent that can be dynamically loaded by the AgentWatcher.
+
+- Class: `ExampleAgent < Agent99::Base`
+- Functionality: Demonstrates a basic agent that can be dynamically loaded
+- Key features:
+  - Defines capabilities as a rubber stamp and yes-man
+  - Responds to all requests with a success status
+- Key methods:
+  - `capabilities`: Defines the agent's capabilities
+  - `receive_request`: Handles incoming requests and sends a response
+
+Note: To use the example_agent.rb, first run the AgentWatcher, then copy example_agent.rb into the 'agents' directory. The AgentWatcher will automatically detect, load, and run the new agent.
+
 ## Usage
 
 From the examples directory you will need to start three different processes.  You will want to keep them all in the forgound so it would be best to start them in different terminal windows.

data/examples/agent_watcher.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# examples/agent_watcher.rb
+#
+# This file defines an AgentWatcher class that monitors a specified directory
+# for new Ruby files and dynamically loads and runs them as agents.
+
+# When running, the AgentWatcher does the following:
+# 1. Watches the directory specified by AGENT_WATCH_PATH (default: './agents')
+# 2. Detects when new .rb files are added to the watched directory
+# 3. Attempts to load each new file as a Ruby agent
+# 4. If successful, instantiates the agent and runs it in a separate thread
+#
+# When example_agent.rb is copied into the agents directory:
+# 1. The AgentWatcher detects the new file
+# 2. It attempts to load the file and extract the agent class
+# 3. If the class is a subclass of Agent99::Base, it instantiates the agent
+# 4. The new agent is then run in a separate thread
+# 5. Any errors during this process are logged for debugging
+#
+# When AgentWatcher is terminated, it first terminates all of the
+# agents that it has previously loaded and then terminates itself.
+
+
+require 'listen'
+
+require_relative '../lib/agent99'
+
+class AgentWatcher < Agent99::Base
+  TYPE = :client
+
+  def capabilities = %w[ launch_agents watcher launcher ]
+
+  def init
+    @watch_path = ENV.fetch('AGENT_WATCH_PATH', './agents')
+    setup_watcher
+  end
+
+  private
+
+  def setup_watcher
+    @listener = Listen.to(@watch_path) do |modified, added, removed|
+      added.each do |file|
+        handle_new_agent(file)
+      end
+    end
+    
+    # Start listening in a separate thread
+    @listener.start
+  end
+
+  def handle_new_agent(file)
+    return unless File.extname(file) == '.rb'
+    
+    begin
+      # Load the new agent file
+      require file
+      
+      # Extract the class name from the file name
+      class_name = File.basename(file, '.rb')
+                      .split('_')
+                      .map(&:capitalize)
+                      .join
+      
+      # Get the class object
+      agent_class = Object.const_get(class_name)
+      
+      # Verify it's an Agent99::Base subclass
+      return unless agent_class < Agent99::Base
+      
+      # Create and run the new agent in a thread
+      Thread.new do
+        begin
+          agent = agent_class.new
+          agent.run
+        rescue StandardError => e
+          logger.error "Error running agent #{class_name}: #{e.message}"
+          logger.debug e.backtrace.join("\n")
+        end
+      end
+      
+      logger.info "Successfully launched agent: #{class_name}"
+    
+    rescue LoadError => e
+      logger.error "Failed to load agent file #{file}: #{e.message}"
+    
+    rescue NameError => e
+      logger.error "Failed to instantiate agent class from #{file}: #{e.message}"
+    
+    rescue StandardError => e
+      logger.error "Unexpected error handling #{file}: #{e.message}"
+      logger.debug e.backtrace.join("\n")
+    end
+  end
+
+  def fini
+    @listener&.stop
+    super
+  end
+end
+
+watcher = AgentWatcher.new
+watcher.run

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/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.
 #
@@ -25,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
@@ -42,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/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/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Agent99
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 
   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.3
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-07 00:00:00.000000000 Z
+date: 2024-12-09 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,39 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- docs/todo.md
+- docs/README.md
+- docs/advanced_features.md
+- docs/agent_discovery.md
+- docs/agent_lifecycle.md
+- docs/agent_registry_processes.md
+- docs/api_reference.md
+- docs/architecture.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
 - 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

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