agent99 0.0.1 → 0.0.3

data/docs/message_processing.md

@@ -0,0 +1,165 @@
+# Agent99 Framework
+
+## Message Processing
+
+The Agent99 framework implements a robust message processing system that handles three main types of
+messages: Request, Response, and Control messages. Each message type follows specific processing flows
+and validation rules.
+
+### Message Types
+
+1. **Request Messages**
+    - Sent by clients to request services or actions
+    - Must include a valid schema definition
+    - Processed through the `receive_request` handler
+    - Automatically validated against REQUEST_SCHEMA
+    - Can trigger responses back to the sender
+
+2. **Response Messages**
+    - Sent in reply to requests
+    - Contain results or error information
+    - Processed through the `receive_response` handler
+    - Include original request reference
+    - May trigger additional processing flows
+
+3. **Control Messages**
+    - Manage agent lifecycle and behavior
+    - Include actions like shutdown, pause, resume
+    - Processed through dedicated control handlers
+    - Support configuration updates
+    - Enable status monitoring
+
+### Message Processing Flow
+
+#### Request Processing
+1. Message arrives and is validated against schema
+2. If validation passes:
+    - `receive_request` is called
+    - Custom processing occurs
+    - Optional response is sent
+3. If validation fails:
+    - Error response is automatically sent
+    - Error is logged
+    - Request is not processed further
+
+![Request Message Processing Flow](diagrams/request_flow.png)
+
+#### Response Processing
+1. Response message is received
+2. `receive_response` handler is called
+3. Response data is processed
+4. Any follow-up actions are triggered
+
+#### Control Processing
+1. Control message is received
+2. Action is identified
+3. Appropriate handler is called:
+    - `handle_shutdown`
+    - `handle_pause`
+    - `handle_resume`
+    - `handle_update_config`
+    - `handle_status_request`
+4. Control response is sent if needed
+
+### Error Handling
+
+The framework provides comprehensive error handling:
+
+1. **Validation Errors**
+    - Schema validation failures
+    - Missing required fields
+    - Invalid data types
+
+2. **Processing Errors**
+    - Handler exceptions
+    - Resource unavailability
+    - Timeout conditions
+
+3. **System Errors**
+    - Connection issues
+    - Resource constraints
+    - Framework-level problems
+
+### Best Practices
+
+1. **Message Validation**
+    - Always define REQUEST_SCHEMA for request-handling agents
+    - Include comprehensive examples in schema
+    - Validate message structure
+
+2. **Error Handling**
+    - Implement robust error handling in handlers
+    - Return meaningful error messages
+    - Log all significant events
+
+3. **Response Management**
+    - Send responses promptly
+    - Include relevant context
+    - Handle partial success cases
+
+4. **Control Messages**
+    - Respond to all control messages
+    - Implement graceful shutdown
+    - Maintain agent state properly
+
+### Implementation Example
+
+```ruby
+class MyAgent < Agent99::Base
+  REQUEST_SCHEMA = {
+    type: "object",
+    properties: {
+      header: HEADER_SCHEMA,
+      data: {
+        type: "object",
+        required: ["action"],
+        properties: {
+          action: { type: "string" }
+        }
+      }
+    }
+  }
+
+  def receive_request
+    action = payload.dig(:data, :action)
+    result = process_action(action)
+    send_response(result)
+  rescue StandardError => e
+    send_response(error: e.message)
+  end
+
+  private
+
+  def process_action(action)
+    # Custom processing logic
+    { status: "success", result: action }
+  end
+end
+```
+
+### Message Structure
+
+All messages must include a header with:
+* `type`: Message type (request/response/control)
+* `to_uuid`: Destination agent ID
+* `from_uuid`: Sender agent ID
+* `event_uuid`: Unique event identifier
+* `timestamp`: Message creation time
+
+Example message structure:
+```ruby
+{
+  header: {
+    type: "request",
+    to_uuid: "agent_123",
+    from_uuid: "agent_456",
+    event_uuid: "evt_789",
+    timestamp: 1638360000000000
+  },
+  data: {
+    # Message-specific payload
+  }
+}
+```
+
+

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

@@ -1,41 +1,36 @@
-# Agent99 Framework Examples
-
-- TODO
-    - Review and edit
-    - Add instructions for brew install rabbitmq nats-server boxes
-    - review example agents to see code can be tightened
+# Agent99 Framework Examples - 86 and the Chief
 
 This folder contains example implementations using the Agent99 framework. The framework provides a foundation for building AI agents that can communicate with each other through a message-based system.
 
 ## Files
 
-### 1. hello_world.rb
+### 1. maxwell_agent86.rb
 
-This file demonstrates a basic AI agent implementation using the Agent99 framework.
+This file demonstrates a basic agent implementation using the Agent99 framework.
 
-- Class: `HelloWorld < Agent99::Base`
+- Class: `MaxwellAgent86 < Agent99::Base`
 - Functionality: Responds to "hello world" requests
 - Key methods:
   - `receive_request`: Handles incoming requests
   - `validate_request`: Validates the request against a schema
   - `process`: Generates the response
 
-### 2. hello_world_client.rb
+### 2. chief_agent.rb
 
-This file shows how to create a client that interacts with the HelloWorld agent.
+This file shows how to create a client that interacts with the MaxwellAgent86 agent.
 
-- Class: `HelloWorldClient < Agent99::Base`
-- Functionality: Sends a request to a HelloWorld agent and processes the response
+- Class: `ChiefAgent < Agent99::Base`
+- Functionality: Sends a request to an agent who can be a greeter and processes the response
 - Key methods:
   - `init`: Initiates the request sending process
   - `send_request`: Builds and sends the request
   - `receive_response`: Handles the response from the HelloWorld agent
 
-### 3. hello_world_request.rb
+### 3. mexwell_request.rb
 
-This file defines the schema for HelloWorld requests using SimpleJsonSchemaBuilder.
+This file defines the schema for MaxwellAgent86 requests using SimpleJsonSchemaBuilder.
 
-- Class: `HelloWorldRequest < SimpleJsonSchemaBuilder::Base`
+- Class: `MaxwellRequest < SimpleJsonSchemaBuilder::Base`
 - Defines the structure of a valid HelloWorld request
 
 ### 4. registry.rb
@@ -50,30 +45,65 @@ 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
 
-1. Start the registry service:
-   ```
-   ruby registry.rb
-   ```
+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.
+
+Start the sample registry first: `./registry.rb`
+
+Then start the service agent: `./maxwell_agent86.rb`
+Maxwell will will register itself, get its UUID and setup a message queue to which it will listen for its service requests.
 
-2. Run the HelloWorld agent:
-   ```
-   ruby hello_world.rb
-   ```
+Finally start the chief agent in charge: `./chief_agent.rb`
+The Chief also registers itself but no other agent can give the Chief missions.  That's his job.  The chief gets his mission UUID, sets up a message queue to listen for the reports from the field after he sends out his request (aka order)
 
-3. Run the HelloWorld client:
-   ```
-   ruby hello_world_client.rb
-   ```
+But first the Chief asks the registry for the UUIDs of all agents who can handle a "greeter" request.  The Chief selects one of those agents and sends the agent a greet request.  The Chief then waits for a response to the request.  When it comes in, the chiefs displays the response and terminates.
 
-## Dependencies
+Run the chief a few times in a roll.  Some times the agent to whom the Chief issues his requests does not always respond the you would expect.
 
-- Ruby 3.3+
-- Gems: json, json_schema, sinatra, bunny, securerandom
+![Agent99 Framework Diagram](diagram.png)
 
-## Notes
 
-- The framework uses modern Ruby 3.3 syntax, especially for hashes and method signatures with named parameters.
-- The examples demonstrate basic usage of the Agent99 framework, including request/response handling, validation, and agent discovery.
-- The registry service uses an in-memory store (AGENT_REGISTRY) for simplicity, but it's recommended to use a more robust solution like SQLite for production use.

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