agent99 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e269eac0e8a38fef70f8db9d0487fb3b723d5b928350f396cb8eae852f446897
-  data.tar.gz: e13090c1235e35de5c8665d7a7f6e6f0aee3a9aae999b82b1d925bdc07efcb4c
+  metadata.gz: 1821eef1dcc40dde4e8b93a553728086ab5217020c7635bef4c993a437c88a24
+  data.tar.gz: 8f2b26e50c28c257728cc5dc0b2eb6712b02b1eb3286fd3a1185e5517eef5ed4
 SHA512:
-  metadata.gz: 3546e420df4bb94fa6ec09cbbc4b6e735b6ceebb937f9a6438d69b7fecdeea39fa38108620d9327ca6053218e303ed77284de02886f18dce367f4b6ecb10e588
-  data.tar.gz: 5fb72619e4321a2db1cfcee0d959cdd7206efb21eead25dba81381008c6d893eb39fbb6205857851f34275a01a421c1c193694c874e21a12b1876de0da2e1ce9
+  metadata.gz: cce04381c30134bc1058d69e6c4090ed12551974884b3e71b5871ed483b81a24fd028b9fb142e48ae51ab60236c1a5c404522bd431d4309285c5a3d42102c9bd
+  data.tar.gz: 28e77a074b28f3cc3b8106bb4ba6faaedcbf7ad7215ea03b261aabdaee5560874ed57155af956a035b0e42814cf37c1a9d42e459086edbb72e93c94d1740b9ac

data/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ## Released
 
+### [0.0.4] 2024-12-14
+
+- This is a [breaking change](docs/breaking_change_v0.0.4.md)
+- Replaced the capabilities method with the info method so that lots of stuff can be incorporated into an agent's information packet maintained by the registry.
+
+
+
 ### [0.0.3] - 2024-12-08
 
 - Document advanced features and update examples

data/README.md

@@ -1,7 +1,9 @@
-# Agent99 Framework (AFW)
+# Agent99
 
 **Under Development**  Initial release has no AI components - its just a generic client-server / request-response micro-services system using a peer-to-peer messaging broker and a centralized agent registry.  To keep up with the version changes review [The Changelog](./CHANGELOG.md) file.
 
+v0.0.4 has a [breaking_change.](docs/breaking_change_v0.0.4.md)
+
 Agent99 is a Ruby-based framework for building and managing AI agents in a distributed system. It provides a robust foundation for creating intelligent agents that can communicate, discover each other, and perform various tasks.
 
 ## Hype!
@@ -85,39 +87,36 @@ Here's a basic example of how to create an AI agent:
 ```ruby
 require 'agent99'
 
-class MyAgentRequest < SimpleJsonSchemaBuilder::Base
+class GreeterRequest < SimpleJsonSchemaBuilder::Base
   object do
     object :header, schema: Agent99::HeaderSchema
-
-    # Define your agents parameters ....
-    string :greeting, required: false,  examples: ["Hello"]
-    string :name,     required: true,   examples: ["World"]
+    string :name, required: true, examples: ["World"]
   end
 end
 
-class MyAgent < Agent99::Base
-  REQUEST_SCHEMA  = MyAgentRequest.schema
-
-  def capabilities
-    ['text_processing', 'sentiment_analysis']
-    # TODO: make up mind on keyword or unstructured text
+class GreeterAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     ['greeter', 'hello_world'],
+      request_schema:   GreeterRequest.schema,
+      # Uncomment and define these schemas as needed:
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
   end
 
-  def receive_request
-    # Handle the validated incoming requests
-    response = { result: "Processed request" }
-
-    # Not every request needs a response
+  def process_request(payload)
+    name      = payload.dig(:name)
+    response  = { result: "Hello, #{name}!" }
     send_response(response)
   end
-
-  def receive_response
-    # You sent a request to another agent
-    # now handle the response.
-  end
 end
 
-agent = MyAgent.new
+# Create and run the agent
+agent = GreeterAgent.new
 agent.run
 ```
 
@@ -125,7 +124,14 @@ agent.run
 
 The framework can be configured through environment variables:
 
-- `REGISTRY_BASE_URL`: URL of the agent registry service (default: 'http://localhost:4567')  See the default registry service in the examples folder.
+- `AGENT99_REGISTRY_URL`: URL of the agent registry service (default: 'http://localhost:4567')
+
+Depending on which messaging client you are using, additional environment variables may be used.
+
+TODO: show envars for AMQP via Bunny
+TODO: show envars for NATS via nats0server
+
+See the examples folder for a default registry service implementation.
 
 ## Contributing
 

data/docs/advanced_features.md

@@ -33,10 +33,15 @@ The AgentWatcher will:
 ### Example Implementation
 
 ```ruby
-class MyDynamicAgent < Agent99::Base
-  TYPE = :server
-  
-  def capabilities = ['my_capability']
+class MyDynamicAgent < Agent99::Base  
+  def info
+    {
+      # ...
+      type:         :server,
+      capabilities: ['my_capability'],
+      # ...
+    }
+  end
   
   def receive_request
     # Handle requests

data/docs/agent99_framework/central_registry.md

@@ -0,0 +1,94 @@
+# Central Registry
+
+## Overview
+
+The Central Registry is a crucial component of the Agent99 Framework, serving as a centralized hub for agent registration, discovery, and management. Its primary purpose is to facilitate communication and coordination between various agents within the framework, allowing them to register their capabilities and discover other agents with specific skills.
+
+The registry provides a RESTful API that can be implemented in any programming language or web framework that supports HTTPS endpoints. This document outlines the API specifications for implementing a compatible Central Registry.
+
+## API Endpoints
+
+### 1. Health Check
+
+- **Endpoint**: GET /healthcheck
+- **Purpose**: Provides a simple health check for the registry service.
+- **Response**: JSON object containing the current count of registered agents.
+- **Example Response**:
+  ```json
+  {
+    "agent_count": 5
+  }
+  ```
+
+### 2. Register Agent
+
+- **Endpoint**: POST /register
+- **Purpose**: Allows an agent to register itself with the registry, providing its name and capabilities.
+- **Request Body**: JSON object containing agent information.
+- **Response**: JSON object with a newly generated UUID for the registered agent.
+- **Example Request**:
+  ```json
+  {
+    "name": "TextAnalyzer",
+    "capabilities": ["sentiment analysis", "named entity recognition"]
+  }
+  ```
+- **Example Response**:
+  ```json
+  {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+  ```
+
+### 3. Discover Agents
+
+- **Endpoint**: GET /discover
+- **Purpose**: Allows discovery of agents based on a specific capability.
+- **Query Parameter**: capability (string)
+- **Response**: JSON array of matching agents with their full information.
+- **Example Request**: GET /discover?capability=sentiment+analysis
+- **Example Response**:
+  ```json
+  [
+    {
+      "name": "TextAnalyzer",
+      "capabilities": ["sentiment analysis", "named entity recognition"],
+      "uuid": "550e8400-e29b-41d4-a716-446655440000"
+    }
+  ]
+  ```
+
+### 4. Withdraw Agent
+
+- **Endpoint**: DELETE /withdraw/:uuid
+- **Purpose**: Removes an agent from the registry using its UUID.
+- **Response**: 
+  - 204 No Content if successful
+  - 404 Not Found if the agent UUID is not in the registry
+- **Example Request**: DELETE /withdraw/550e8400-e29b-41d4-a716-446655440000
+
+### 5. List All Agents
+
+- **Endpoint**: GET /
+- **Purpose**: Retrieves a list of all registered agents.
+- **Response**: JSON array containing all registered agents' information.
+
+## Implementation Notes
+
+1. Agent capabilities should be stored and compared in lowercase to ensure case-insensitive matching.
+2. The current implementation uses an in-memory array to store agent information. For production use, consider using a persistent database like SQLite or a more scalable solution.
+3. The discovery process currently uses simple keyword matching. Future enhancements could include semantic matching for more accurate agent discovery.
+
+## Potential Enhancements
+
+1. **Persistent Storage**: Implement a database backend for storing agent information, ensuring data persistence across server restarts.
+2. **Authentication and Authorization**: Add security measures to protect sensitive endpoints and ensure only authorized agents can register or withdraw.
+3. **Semantic Matching**: Enhance the discovery process with natural language processing or vector search capabilities for more intelligent agent matching.
+4. **Agent Health Monitoring**: Implement periodic health checks on registered agents to ensure they are still active and available.
+5. **Versioning**: Add support for agent versioning to manage different versions of agents with similar capabilities.
+6. **Pagination**: Implement pagination for the discovery and list all endpoints to handle large numbers of agents efficiently.
+7. **Metrics and Logging**: Add comprehensive logging and metrics collection for better monitoring and debugging of the registry service.
+8. **API Rate Limiting**: Implement rate limiting to prevent abuse and ensure fair usage of the registry service.
+
+By implementing this API, developers can create a compatible Central Registry for the Agent99 Framework in their preferred language or framework, enabling seamless integration and communication between diverse agents in the ecosystem.
+

data/docs/agent99_framework/message_client.md

@@ -0,0 +1,120 @@
+# Message Client Documentation for Agent99 Framework
+
+## Overview
+
+The Message Client is a crucial component of the Agent99 Framework, providing an interface for agents to communicate with each other through a message broker. This document outlines the required methods and functionalities that should be implemented in any message client to ensure compatibility with the Agent99 Framework.
+
+## Message Format Requirements
+
+All messages sent and received through the Agent99 Framework must adhere to the following format requirements:
+
+1. **JSON Format**: All messages must be in JSON format. This ensures consistency and ease of parsing across different implementations and languages.
+
+2. **Header Element**: Each message must include a `header` element that conforms to the `HeaderSchema` defined for the Agent99 Framework. The `HeaderSchema` is as follows:
+
+```ruby
+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
+```
+
+3. **Message Types**: The `type` field in the header must be one of: `request`, `response`, or `control`.
+
+4. **Validation**: All incoming messages are validated against the appropriate schema based on their type. If validation errors are found, an error response message is returned to the sender.
+
+## Class: MessageClient
+
+### Initialization
+
+```ruby
+def initialize(config: {}, logger: Logger.new($stdout))
+  # Implementation details...
+end
+```
+
+Creates a new instance of the MessageClient.
+
+- `config:` A hash containing configuration options for the message broker connection.
+- `logger:` A logger instance for output (default: stdout logger).
+
+### Public Methods
+
+#### setup
+
+```ruby
+def setup(agent_id:, logger:)
+  # Implementation details...
+end
+```
+
+Sets up the necessary resources for an agent to start communicating.
+
+- `agent_id:` The unique identifier for the agent.
+- `logger:` A logger instance for output.
+- Returns: An object representing the agent's message queue or channel.
+
+#### listen_for_messages
+
+```ruby
+def listen_for_messages(
+  queue,
+  request_handler:,
+  response_handler:,
+  control_handler:
+)
+  # Implementation details...
+end
+```
+
+Starts listening for incoming messages on the specified queue.
+
+- `queue:` The queue or channel object returned by the `setup` method.
+- `request_handler:` A callable object to handle incoming request messages.
+- `response_handler:` A callable object to handle incoming response messages.
+- `control_handler:` A callable object to handle incoming control messages.
+
+#### publish
+
+```ruby
+def publish(message:)
+  # Implementation details...
+end
+```
+
+Publishes a message to the specified queue.
+
+- `message:` A hash containing the message to be published. This must be in JSON format and include a header that conforms to the `HeaderSchema`.
+- Returns: A hash indicating the success or failure of the publish operation, including details if the message structure is invalid.
+
+#### delete_queue
+
+```ruby
+def delete_queue(queue_name:)
+  # Implementation details...
+end
+```
+
+Deletes the specified queue or cleans up resources associated with it.
+
+- `queue_name:` The name of the queue to be deleted.
+
+### Implementation Notes
+
+1. **Message Validation**: Implement thorough validation for all incoming and outgoing messages. Ensure that they are in JSON format and contain a header that conforms to the `HeaderSchema`. If validation fails for incoming messages, send an error response to the sender with details about the validation issues.
+
+2. **Error Handling**: Implement robust error handling for all methods, especially for connection, publishing, and validation errors.
+
+3. **Logging**: Provide detailed logging for all operations, including successful actions, validation results, and errors.
+
+4. **Performance and Scalability**: Optimize the client to handle a large number of JSON-formatted messages efficiently, considering potential performance impacts of validation.
+
+5. **Thread Safety**: Ensure that the client is thread-safe, particularly when handling message validation and publishing.
+
+By adhering to these requirements and implementing the MessageClient with these considerations, developers can ensure that their implementations will be fully compatible with the Agent99 Framework. The strict adherence to JSON formatting and the inclusion of a standardized header in all messages promotes consistency and reliability in inter-agent communication within the framework.
+

data/docs/agent99_framework/registry_client.md

@@ -0,0 +1,119 @@
+# RegistryClient Documentation
+
+## Overview
+
+The RegistryClient class is a crucial component of the Agent99 framework, providing a Ruby interface to interact with the Central Registry service. It encapsulates the HTTP communication logic required to register agents, discover capabilities, and manage agent lifecycle within the Agent99 ecosystem.
+
+## Class: Agent99::RegistryClient
+
+### Initialization
+
+```ruby
+def initialize(base_url: ENV.fetch('REGISTRY_BASE_URL', 'http://localhost:4567'),
+               logger: Logger.new($stdout))
+```
+
+Creates a new instance of the RegistryClient.
+
+- `base_url`: The URL of the Central Registry service (default: http://localhost:4567)
+- `logger`: A logger instance for output (default: stdout logger)
+
+### Public Methods
+
+#### register
+
+```ruby
+def register(name:, capabilities:)
+```
+
+Registers an agent with the Central Registry.
+
+- `name`: The name of the agent
+- `capabilities`: An array of capabilities the agent possesses
+- Returns: The UUID of the registered agent
+
+One of the first improvement that should be considered when registering a new agent is adding its JSON schema for its request and response messages.  This way there should be no question about how to interface with the agent.
+
+#### withdraw
+
+```ruby
+def withdraw(id)
+```
+
+Withdraws an agent from the Central Registry.
+
+- `id`: The UUID of the agent to withdraw
+- Returns: nil
+
+#### discover
+
+```ruby
+def discover(capability:)
+```
+
+Discovers agents with a specific capability.
+
+- `capability`: The capability to search for
+- Returns: An array of agents matching the capability
+
+#### fetch_all_agents
+
+```ruby
+def fetch_all_agents
+```
+
+Retrieves all registered agents from the Central Registry.
+
+- Returns: An array of all registered agents
+
+### Private Methods
+
+The class includes several private methods for handling HTTP requests and responses:
+
+- `create_request`: Creates an HTTP request object
+- `send_request`: Sends an HTTP request and handles exceptions
+- `handle_response`: Processes the HTTP response based on its status code
+
+## Usage Example
+
+```ruby
+client = Agent99::RegistryClient.new
+agent_id = client.register(name: "TextAnalyzer", capabilities: ["sentiment analysis", "named entity recognition"])
+matching_agents = client.discover(capability: "sentiment analysis")
+client.withdraw(agent_id)
+```
+
+## Potential Improvements
+
+1. **Error Handling**: Implement more granular error handling and custom exceptions for different types of failures (e.g., network errors, authentication errors).
+
+2. **Retry Mechanism**: Add a retry mechanism for transient failures, potentially using a library like `retriable`.
+
+3. **Connection Pooling**: Implement connection pooling to improve performance when making multiple requests.
+
+4. **Caching**: Add caching for frequently accessed data, such as the list of all agents or common capability searches.
+
+5. **Asynchronous Operations**: Provide asynchronous versions of methods for non-blocking operations, possibly using Ruby's `async`/`await` syntax or a library like `concurrent-ruby`.
+
+6. **Pagination Support**: Implement pagination for methods that return potentially large datasets, such as `fetch_all_agents`.
+
+7. **Capability Normalization**: Normalize capabilities (e.g., lowercase, remove whitespace) before sending to ensure consistent matching.
+
+8. **Batch Operations**: Add support for batch registration or withdrawal of multiple agents in a single request.
+
+9. **Logging Enhancements**: Improve logging to include more detailed information about requests and responses for better debugging.
+
+10. **Configuration Options**: Allow more configuration options, such as timeout settings, custom headers, or SSL/TLS options.
+
+11. **Capability Validation**: Implement client-side validation of capabilities before sending requests to the server.
+
+12. **Agent Status Updates**: Add methods to update an agent's status or capabilities without full re-registration.
+
+13. **Metrics Collection**: Integrate with a metrics library to collect and report on API usage and performance.
+
+14. **Authentication Support**: Add support for authentication mechanisms if the Central Registry implements them in the future.
+
+15. **API Versioning**: Implement support for API versioning to handle potential future changes in the Central Registry API.
+
+By implementing these improvements, the RegistryClient can become more robust, efficient, and feature-rich, enhancing its utility within the Agent99 framework.
+

data/docs/agent_discovery.md

@@ -12,17 +12,21 @@ The agent discovery process involves the following steps:
 2. **Discovery**: When an agent needs to discover other agents, it queries the registry for agents with specific capabilities.
 3. **Response**: The registry responds with a list of available agents, allowing them to interact based on their capabilities.
 
-### Declaring Capabilities
+### Declaring Capabilities in the Info Method
 
-Each agent must implement the `capabilities` method to declare its capabilities as an array of strings:
+Each agent must implement the `info` method to declare its capabilities as an array of strings:
 
 ```ruby
-def capabilities
-  ['process_image', 'face_detection']
+def info
+  {
+    # ...
+    capabilities:  ['process_image', 'face_detection'],
+    # ...
+  }
 end
 ```
 
-**Note**: The discovery mechanism is based on an exact match (case insensitive) between the requested capability and the entries in the agent's capabilities array. For example, if an agent declares its capabilities as mentioned above, a discovery request for `'FACE_DETECTION'` will successfully match.
+**Note**: The discovery mechanism is based on an exact match (case insensitive) between the requested capability and the entries in the agent's capabilities array in its information packet. For example, if an agent declares its capabilities as mentioned above, a discovery request for `'FACE_DETECTION'` will successfully match.
 
 ### Discovery API
 

data/docs/agent_registry_processes.md

@@ -38,8 +38,14 @@ end
 # Define the new Agent ....
 
 class MyAgent < Agent99::Base
-  REQUEST_SCHEMA    = MyAgentRequest.schema
-  def capabilities  = %w[ greeter hello_world ]
+  def info
+    {
+      # ...
+      request_schema: MyAgentRequest.schema
+      capabilities:   %w[ greeter hello_world ],
+      # ...
+    }
+  end
 end
 
 # You may create multiple instances of the agent if needed

data/docs/api_reference.md

@@ -6,14 +6,24 @@ When creating a new agent by subclassing `Agent99::Base`, you must implement cer
 
 ### Required Methods
 
-#### `capabilities`
-Returns an array of strings describing the agent's capabilities.
+#### `info`
+ The `info` method provides a comprehensive information packet about the agent. It returns a hash containing key details that are crucial for agent registration and discovery within the system.
 ```ruby
-def capabilities
-  ['process_image', 'face_detection']
+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
 ```
 
+Entries for **:name** and **:capabilities** are required.  Other entries are optional.  This entire info packet is stored by the central registry and provided to other agents on a discover "hit" so that the inquiring agents know all the target agent is willing to tell them.
+
 #### `receive_request`
 Handles incoming request messages. Must be implemented if the agent accepts requests.
 ```ruby

data/docs/breaking_change_v0.0.4.md

@@ -0,0 +1,26 @@
+# v0.0.4 is a Breaking Change
+
+## Before
+
+Each agent was required to implement a `capabilities` method that returned an Array of Strings in which the elements of the array were essentially synonyms describing the thing that the agent does.  The roadmap calls for this capabilities structure to become an unstructured String in which semmantic search will be used for discovery rather than exact matches.
+
+## After
+
+The **capabilities** is now just one of several within a Hash collection returned by a new method named `info` representing the agent's information packet.  The entire packet will be returned by the central regristry when the agent is discovered.
+
+The capabilities element of this new `info` hash still has the same requirement of being an Array of Strings with a promiss of becoming more later as the system becomes more sophisticated.
+
+The required elements of the `info` Hash are:
+
+- **name** -- automaticall derived from the class name of the agent.
+- **type** -- one of server, client or hybrid.
+- **capabilities** -- An Array of Strings
+- **request_schema** -- is required when the type is server
+
+The keys to the `info` Hash are Symbols.
+
+### Modivation
+
+The goal is to be able to mix and match multiple agents created by different developers in different languages within the context of the protocols and APIs of the Agent99 Framework.  To that end it seems reasonable that agents would have a need to share more than just their capabilitieis.  For example, their JSON schema for their request, response and control messages might also be something worth sharing.
+
+