agent99 0.0.2 → 0.0.4

data/docs/agent_discovery.md

@@ -0,0 +1,66 @@
+# Agent99 Framework
+
+## Agent Discovery
+
+Agents within the Agent99 Framework can efficiently discover one another based on their declared capabilities. This feature fosters dynamic interactions that enhance the collaborative functionality of the agents.
+
+### Overview
+
+The agent discovery process involves the following steps:
+
+1. **Registration**: Agents register their capabilities with a central registry upon startup.
+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 in the Info Method
+
+Each agent must implement the `info` method to declare its capabilities as an array of strings:
+
+```ruby
+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 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
+
+To find other agents, use the `discover_agent` method. Here are some usage examples:
+
+```ruby
+# Find a single agent with a specific capability
+agent = discover_agent(capability: 'face_detection')
+
+# Find multiple agents 
+agents = discover_agent(capability: 'process_image', how_many: 3)
+
+# Find all agents with a specific capability
+all_agents = discover_agent(capability: 'process_image', all: true)
+```
+
+### Important Note on Capabilities
+
+- **Single Capability**: A seeking agent can only request one kind of capability at a time.
+- **Semantics-Based Capabilities**: The development roadmap includes enhancements towards semantic-based capabilities that could allow for more complex interactions between agents in the future.  This would be a change from the current Array of Strings to a single String that is a description of the services the agent provides.  This would be consistent with the way in which LLMs currently find Tools for augmented generation.
+
+### Registry Configuration
+
+The registry client comes with default settings, which you can override as needed:
+
+- **URL**: Default is `http://localhost:4567` (you can override this using the `REGISTRY_BASE_URL` environment variable).
+- **Interface**: Supports a standard HTTP REST interface.
+- **Reconnection**: Automatic reconnection handling is provided to ensure reliable communication.
+
+### Best Practices
+
+1. **Check Discovery Success**: Always verify if agent discovery succeeded before attempting to establish communication with the discovered agent.
+2. **Use Specific Capability Names**: This ensures that the correct agents are matched during the discovery process, avoiding ambiguity.
+3. **Implement Multiple Capabilities**: Consider declaring multiple capabilities per agent to enhance its versatility and improve interaction possibilities.
+
+With these guidelines, you can effectively implement and utilize the agent discovery feature within the Agent99 Framework, ensuring robust and dynamic interactions among agents based on their declared capabilities.
+

data/docs/agent_lifecycle.md

@@ -0,0 +1,137 @@
+# Agent99 Framework
+
+## Agent Lifecycle
+
+The lifecycle of an agent within Agent99 consists of several key stages that are managed through dedicated lifecycle methods. Understanding these stages and their corresponding methods is crucial for proper agent implementation.
+
+### Lifecycle Stages
+
+1. **Creation**: An agent is instantiated through the `Agent99::Base` class.
+2. **Initialization**: The agent sets up resources and establishes connections.
+3. **Running**: The agent processes messages and performs its designated tasks.
+4. **Shutdown**: The agent performs cleanup and gracefully terminates.
+
+### Core Lifecycle Methods
+
+#### The `init` Method
+
+The `init` method is called automatically after the agent has been registered but before it starts processing messages. Its primary purpose is to perform any additional setup required for the agent following the default initialization provided by the `Agent99::Base` class. This may include:
+
+- Setting up initial state
+- Establishing connections to other agents or resources
+- Discovering dependencies or agents to communicate with
+- Sending initial messages to specific agents
+
+Here’s an example implementation:
+
+```ruby
+def init  
+  @state      = initialize_state
+  @resources  = setup_resources
+end
+```
+
+#### Custom Initialization
+
+Agents can choose to either use the default behavior provided by the `Agent99::Base` class or implement their own `initialize` method to customize the `logger`, `message_client`, and `registry_client` attributes. For instance:
+
+1. **Using Defaults**: If you do not define an `initialize` method in your agent class, it will inherit the defaults:
+
+```ruby
+class MyAgent < Agent99::Base
+  # Inherits default logger, message_client, and registry_client
+end
+```
+
+2. **Customizing Initialization**: If you need custom initialization, you can ignore the `init` method and override the `initialize` method:
+
+```ruby
+class MyCustomAgent < Agent99::Base
+  def initialize(
+      registry_client:  CustomRegistryClient.new,
+      message_client:   CustomMessageClient.new,
+      logger:           Logger.new('custom_agent.log')
+    )
+    super  # Registers the Agent and setups its message queue
+
+    # Additional state or resource initialization required
+    # by the new agent
+  end
+end
+```
+
+In this case, the custom agent not need the `init` method to perform any additional setup.
+
+#### The `fini` Method
+
+The `fini` method is setup to be invoked when the `exit` method is called within `initialize` method by the `on_exit { fini }` hook.
+
+The `fini` method ensures proper cleanup during agent shutdown:
+
+The default `fini` method does:
+- Withdrawing from the registry
+- Closing message queue connections
+
+If your agent requires additional cleanup or state presistence you should implement a custom `fini` method to do things like:
+- Cleaning up resources
+- Saving state (if required)
+- Releasing system resources
+
+Example implementation:
+
+```ruby
+def fini
+  save_state if @state
+  cleanup_resources
+  deregister_from_registry
+  
+  super  # Always call super last for proper framework cleanup
+end
+```
+
+### Best Practices
+
+1. **Proper Method Ordering**:
+   - Always call `super` first in `initialize`.
+   - Always call `super` last in `fini`.
+   - This order ensures proper framework initialization and cleanup.
+
+2. **Resource Management**:
+   - Initialize all resources in `init` or `initialize`.
+   - Clean up all resources in `fini`.
+   - Handle cleanup idempotently.
+
+3. **Error Handling**:
+   - Implement robust error handling in all methods.
+   - Ensure `fini` can handle partial initialization states.
+   - Log all significant lifecycle events.
+
+4. **State Management**:
+   - Initialize state clearly.
+   - Save or cleanup state properly in `fini`.
+   - Consider persistence needs.
+
+### Important Considerations
+
+- Agents can be implemented as stand-alone processes.
+- When an agent is implemented within the context of a larger application process, the agent should be "run" within its own thread.
+    ```ruby
+    begin
+      my_agent = MyAgent.new
+      Thread.new { my_agent.run }
+    end
+    ```
+- Agents handle only one request message at a time.
+- The `fini` method is called automatically during graceful shutdowns.
+
+### Framework Integration
+
+The Agent99 framework automatically manages the lifecycle of agents:
+
+1. Calls `init` (if present) after agent creation.
+2. Monitors agent health during operation.
+3. Calls `fini` during shutdown (`on_exit {fini}`).
+4. Handles cleanup if initialization fails.
+
+This automated lifecycle management ensures reliable agent operation within the framework.
+

data/docs/agent_registry_processes.md

@@ -0,0 +1,108 @@
+# Agent99 Framework
+
+## Agent Registry Processes
+
+In the Agent99 framework, an instance of the `Agent99::RegistryClient` class is responsible for registering agent capabilities with a centralized registry.  `examples/registry.rb` is a Sinatra web-app example of what a centralized regristry service should be. 
+
+The registration process is transparent to a new instance of an `Agent99::Base` class.
+
+First thing: start the registry.rb Sinatra app and the peer-to-peer messaging network.  The default is the `AmqpMessageClient` class.
+
+If you do not have the RabbitMQ server installed on your Macthen then grab it using `brew install rabbitmq-server` and while you are installing software do `brew install boxes` as well since the `chief_agent.rb` example uses that little CLI tool to highlight some text in the terminal.
+
+```bash
+git clone ssh://git@github.com/MadBomber/agent99
+brew install rabbitmq-server boxes
+gem install agent99
+
+cd agent99/examples
+./start_rabbitmq_and_registry.sh
+```
+
+Now go into `irb` in a different terminal window and try this code ...
+
+```ruby
+require 'agent99'
+
+# Define the Schema for the Agent's request payload
+
+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
+
+# Define the new Agent ....
+
+class MyAgent < Agent99::Base
+  def info
+    {
+      # ...
+      request_schema: MyAgentRequest.schema
+      capabilities:   %w[ greeter hello_world ],
+      # ...
+    }
+  end
+end
+
+# You may create multiple instances of the agent if needed
+
+my_agent = MyAgent.new
+
+I, [2024-12-07T14:42:08.140286 #36471]  INFO -- : Registered Agent MyAgent with ID: 9e735449-582f-46e2-8f11-371e584d0f08
+I, [2024-12-07T14:42:08.141978 #36471]  INFO -- : Created queue for agent_id: 9e735449-582f-46e2-8f11-371e584d0f08
+  #=>
+#<MyAgent:0x000000011d4d2e48
+...
+
+# The agent as an ID and an address in the peer-to-peer network
+
+my_agent.id
+  #=> "9e735449-582f-46e2-8f11-371e584d0f08"
+```
+
+The image below shows how the `Agent99::Base` class uses dependency injection in its constructor method to bring in an instance of the `RegristryClient` class to provide an interface to the centralized regristery service.
+
+![Agent Register, Discover and Withdraw Processes](diagrams/agent_registry_processes.png)
+
+The above image also show the other services provided via the RegistryClient class.
+
+The example centralized regristry service provides three processes:
+
+1. Registration Process:
+     - MyAgent initializes the RegistryClient
+     - RegistryClient sends a POST request to the Central Registry
+     - Central Registry responds with a UUID
+     - RegistryClient returns the UUID to MyAgent
+2. Discovery Process:
+     - MyAgent requests discovery of agents with a specific capability
+     - RegistryClient sends a GET request to the Central Registry
+     - Central Registry responds with matching agents
+     - RegistryClient returns the matching agents to MyAgent
+3. Withdrawal Process:
+     - MyAgent requests withdrawal using its UUID
+     - RegistryClient sends a DELETE request to the Central Registry
+     - Central Registry responds with a 204 No Content
+     - RegistryClient confirms the withdrawal to MyAgent
+
+Like the register process, the withdraw process is also transparent.  Its executed on any exit via the public method `fini` in the base class' `on_exit {...}` handler.  Calling `exit` for any reason within your agent class will withdraw it from the central registry and remove its message queue from peer-to-peer messaging network.
+
+The discover process is primary business logic for your agent class.  You must call the `@registry_client.discover(capability: "whatever")` method directly within the agents process.
+
+For example suppose your agent needs to work with other agents that provide the "pne", "twp" and "three" services.  That is 3 outside agents.  You can do this in the `init` method for you agent.
+
+```ruby
+class MyAgent < Agent99::Base
+  def init
+    @agnet_1 = discover_agent(capability: 'one')
+    @agnet_2 = discover_agent(capability: 'two')
+    @agnet_3 = discover_agent(capability: 'three')
+  end
+end
+```
+
+`discover_agent` is the `Agent99::Base` method that links to the registry client's instance to do the discovery via the central registry.  Other parameters to `discover_agent` allow's you agent to specify `how_many` agents having the specify capability you want returned.  The default is 1.  If you want all the agents capable of providing the requested service use the `all: true` parameter with the `discover_agent` method.
+

data/docs/api_reference.md

@@ -0,0 +1,146 @@
+# Agent99 Framework API Reference
+
+## Agent Implementation Requirements
+
+When creating a new agent by subclassing `Agent99::Base`, you must implement certain methods and may optionally override others.
+
+### Required Methods
+
+#### `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 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
+def receive_request
+  # Process the request message in @payload
+  # Access message data via @payload[:data]
+  # Send response using send_response(response_data)
+end
+```
+
+### Optional Methods
+
+#### `init`
+Called after registration but before message processing begins. Use for additional setup.
+```ruby
+def init
+  @state = initialize_state
+  @resources = setup_resources
+end
+```
+
+#### `fini`
+Called during shutdown. Override to add custom cleanup.
+```ruby
+def fini
+  cleanup_resources
+  save_state if @state
+  super  # Always call super last
+end
+```
+
+#### `receive_response`
+Handles incoming response messages. Override if the agent processes responses.
+```ruby
+def receive_response
+  # Process the response message in @payload
+end
+```
+
+## Message Client Interface
+
+To implement a custom message client, create a class that implements these methods:
+
+### Required Methods
+
+#### `initialize(logger: Logger.new($stdout))`
+Sets up the messaging connection.
+
+#### `setup(agent_id:, logger:)`
+Initializes message queues/topics for the agent.
+- Returns: queue/topic identifier
+
+#### `listen_for_messages(queue, request_handler:, response_handler:, control_handler:)`
+Starts listening for messages.
+- `queue`: Queue/topic to listen on
+- `request_handler`: Lambda for handling requests
+- `response_handler`: Lambda for handling responses
+- `control_handler`: Lambda for handling control messages
+
+#### `publish(message)`
+Publishes a message.
+- `message`: Hash containing the message with :header and payload
+- Returns: Hash with :success and optional :error
+
+#### `delete_queue(queue_name)`
+Cleans up agent's message queue/topic.
+
+## Registry Client Interface
+
+To implement a custom registry client, create a class that implements these methods:
+
+### Required Methods
+
+#### `initialize(base_url: ENV.fetch('REGISTRY_BASE_URL', 'http://localhost:4567'), logger: Logger.new($stdout))`
+Sets up the registry connection.
+
+#### `register(name:, capabilities:)`
+Registers an agent with the registry.
+- Returns: UUID string for the agent
+
+#### `withdraw(id)`
+Removes an agent from the registry.
+
+## Base Class Public Methods
+
+The `Agent99::Base` class provides these public methods:
+
+#### `run`
+Starts the agent's message processing loop.
+
+#### `discover_agent(capability:, how_many: 1, all: false)`
+Finds other agents by capability.
+- Returns: Array of agent information hashes
+
+#### `send_response(response)`
+Sends a response message.
+- `response`: Hash containing the response data
+
+## Message Types
+
+Messages in Agent99 must include a `:header` with:
+- `:type`: One of "request", "response", or "control"
+- `:to_uuid`: Destination agent's UUID
+- `:from_uuid`: Sending agent's UUID
+- `:event_uuid`: UUID to link request to response
+- `:timestamp`: Integer (`Agent99::Timestamp.new.to_i`)
+
+Example request message structure:
+```ruby
+{
+  header: {
+    type:       'request',
+    to_uuid:    ,
+    from_uuid:  ,
+    event_uuid: ,
+    timestamp:  ,
+  },
+  # agent specific parameters
+}
+```

data/docs/architecture.md

@@ -0,0 +1,77 @@
+# Agent99 Framework Architecture
+
+## High-Level Architecture Overview
+
+Agent99 is a Ruby-based framework designed for building and managing software agents in a distributed system environment. The architecture follows a service-oriented approach with three main components:
+
+1. **Agents**: Independent services that can register, discover, and communicate with each other
+2. **Registry Service**: Central registration and discovery system
+3. **Message Broker**: Communication backbone (supports AMQP or NATS)
+
+### System Components Diagram
+
+![High Level Architecture](diagrams/high_level_architecture.png)
+
+The diagram above (generated from `diagrams/high_level_architecture.dot`) illustrates the key components and their interactions:
+
+- **Agents**: Come in three types:
+   - Client Agents: Only make requests
+   - Server Agents: Only respond to requests
+   - Hybrid Agents: Both make and respond to requests
+
+- **Registry Service**: 
+   - Maintains agent registrations
+   - Handles capability-based discovery
+   - Issues unique UUIDs to agents
+
+- **Message Broker**:
+   - Supports both AMQP and NATS protocols
+   - Handles message routing between agents
+   - Provides reliable message delivery
+
+### Communication Patterns
+
+1. **Registration Flow**:
+      - New agent instantiated
+      - Agent registers with Registry Service
+      - Receives unique UUID for identification
+      - Sets up message queue/topic
+
+2. **Discovery Flow**:
+      - Agent queries Registry for specific capabilities
+      - Registry returns matching agent information
+      - Requesting agent caches discovery results
+
+3. **Messaging Flow**:
+      - Agent creates message with recipient UUID
+      - Message routed through Message Broker
+      - Recipient processes message based on type:
+         - Requests: Handled by receive_request
+         - Responses: Handled by receive_response
+         - Control: Handled by control handlers
+
+### Message Types
+
+The framework supports three primary message types:
+
+1. **Request Messages**: 
+      - Used to request services from other agents
+      - Must include capability requirements
+      - Can contain arbitrary payload data
+
+2. **Response Messages**:
+      - Sent in reply to requests
+      - Include original request reference
+      - Contain result data or error information
+
+3. **Control Messages**:
+      - System-level communication
+      - Handle agent lifecycle events
+      - Support configuration updates
+
+## Implementation Details
+
+For detailed implementation information, see:
+- [API Reference](api_reference.md) for method specifications
+- [Agent Lifecycle](agent_lifecycle.md) for lifecycle management
+- [Agent Discovery](agent_discovery.md) for discovery mechanisms

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.
+
+

data/docs/configuration.md

@@ -0,0 +1,17 @@
+# Agent99 Framework
+
+## Configuration
+
+Agents can be configured using environment variables. Key configuration options include:
+
+- `REGISTRY_BASE_URL`: Specifies the URL of the agent registry service (default: 'http://localhost:4567').
+
+
+### Environment Variables
+
+To set an environment variable, use the following command in your terminal before running your application:
+
+```bash
+export REGISTRY_BASE_URL=http://my-registry-url
+```
+