agent99 0.0.3 → 0.0.5

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/api-reference/agent99-base.md

@@ -0,0 +1,463 @@
+# Agent99::Base
+
+The `Agent99::Base` class is the foundation of all agents in the Agent99 framework. It provides core functionality for agent lifecycle, messaging, discovery, and error handling.
+
+## Class Overview
+
+```ruby
+class Agent99::Base
+  include Agent99::HeaderManagement
+  include Agent99::AgentDiscovery  
+  include Agent99::ControlActions
+  include Agent99::AgentLifecycle
+  include Agent99::MessageProcessing
+end
+```
+
+## Instance Methods
+
+### Core Lifecycle
+
+#### `#run`
+
+Starts the agent and begins listening for messages.
+
+```ruby
+def run
+```
+
+**Example:**
+```ruby
+agent = MyAgent.new
+agent.run  # Blocks until shutdown
+```
+
+#### `#shutdown`
+
+Gracefully shuts down the agent.
+
+```ruby
+def shutdown
+```
+
+**Example:**
+```ruby
+agent.shutdown
+```
+
+#### `#info`
+
+Abstract method that must be implemented by subclasses. Returns agent metadata.
+
+```ruby
+def info
+  # Must return hash with:
+  # - :name (String)
+  # - :type (Symbol: :server, :client, or :hybrid)  
+  # - :capabilities (Array of Strings)
+end
+```
+
+**Example:**
+```ruby
+def info
+  {
+    name: self.class.to_s,
+    type: :server,
+    capabilities: ['calculator', 'math']
+  }
+end
+```
+
+### Message Processing
+
+#### `#process_request(payload)`
+
+Abstract method for handling incoming requests. Only called for server and hybrid agents.
+
+```ruby
+def process_request(payload)
+  # Process the payload and call send_response or send_error
+end
+```
+
+**Parameters:**
+- `payload` (Hash) - The request data
+
+**Example:**
+```ruby
+def process_request(payload)
+  name = payload.dig(:name) || "World"
+  send_response(message: "Hello, #{name}!")
+end
+```
+
+#### `#send_response(data)`
+
+Sends a successful response back to the requester.
+
+```ruby
+def send_response(data)
+```
+
+**Parameters:**
+- `data` (Hash) - Response data
+
+**Example:**
+```ruby
+send_response(
+  result: 42,
+  status: "success",
+  timestamp: Time.now.iso8601
+)
+```
+
+#### `#send_error(message, code = nil, details = nil)`
+
+Sends an error response back to the requester.
+
+```ruby
+def send_error(message, code = nil, details = nil)
+```
+
+**Parameters:**
+- `message` (String) - Error message
+- `code` (String, optional) - Error code
+- `details` (Hash, optional) - Additional error details
+
+**Example:**
+```ruby
+send_error(
+  "Invalid input data", 
+  "VALIDATION_ERROR",
+  { field: "email", expected: "valid email address" }
+)
+```
+
+#### `#send_request(agent_name, payload, options = {})`
+
+Sends a request to another agent. Only available for client and hybrid agents.
+
+```ruby
+def send_request(agent_name, payload, options = {})
+```
+
+**Parameters:**
+- `agent_name` (String) - Target agent name
+- `payload` (Hash) - Request data
+- `options` (Hash, optional) - Request options (timeout, etc.)
+
+**Returns:** Response hash or nil if failed
+
+**Example:**
+```ruby
+response = send_request(
+  "CalculatorAgent", 
+  { operation: "add", a: 5, b: 3 },
+  { timeout: 30 }
+)
+```
+
+### Agent Discovery
+
+#### `#discover_agents(capabilities = [])`
+
+Finds agents that match the specified capabilities.
+
+```ruby
+def discover_agents(capabilities = [])
+```
+
+**Parameters:**
+- `capabilities` (Array) - List of required capabilities
+
+**Returns:** Array of agent info hashes
+
+**Example:**
+```ruby
+calculators = discover_agents(['calculator'])
+weather_agents = discover_agents(['weather', 'forecast'])
+```
+
+#### `#register_agent`
+
+Registers this agent with the registry.
+
+```ruby
+def register_agent
+```
+
+**Example:**
+```ruby
+register_agent
+```
+
+#### `#unregister_agent`
+
+Removes this agent from the registry.
+
+```ruby
+def unregister_agent
+```
+
+### Header Management
+
+#### `#header_value(key)`
+
+Gets a header value from the current request.
+
+```ruby
+def header_value(key)
+```
+
+**Parameters:**
+- `key` (String) - Header key
+
+**Returns:** Header value or nil
+
+**Example:**
+```ruby
+user_id = header_value('user_id')
+correlation_id = header_value('correlation_id')
+```
+
+#### `#set_header(key, value)`
+
+Sets a header value for the current response.
+
+```ruby
+def set_header(key, value)
+```
+
+**Parameters:**
+- `key` (String) - Header key  
+- `value` (String) - Header value
+
+**Example:**
+```ruby
+set_header('processing_time', '150ms')
+set_header('cache_status', 'hit')
+```
+
+### Control Actions
+
+#### `#pause`
+
+Pauses the agent (stops processing new requests).
+
+```ruby
+def pause
+```
+
+#### `#resume`
+
+Resumes the agent after being paused.
+
+```ruby
+def resume
+```
+
+#### `#status`
+
+Returns the current agent status.
+
+```ruby
+def status
+```
+
+**Returns:** Symbol (`:running`, `:paused`, `:stopped`)
+
+### Configuration
+
+#### `#logger`
+
+Returns the logger instance for this agent.
+
+```ruby
+def logger
+```
+
+**Example:**
+```ruby
+logger.info "Processing request"
+logger.error "Something went wrong: #{error.message}"
+```
+
+#### `#config`
+
+Returns the configuration hash for this agent.
+
+```ruby
+def config
+```
+
+**Example:**
+```ruby
+timeout = config[:timeout] || 30
+registry_url = config[:registry_url]
+```
+
+## Class Methods
+
+### `Agent99::Base.create(type:, **options)`
+
+Factory method for creating agents.
+
+```ruby
+Agent99::Base.create(type: :server, name: 'TestAgent')
+```
+
+**Parameters:**
+- `type` (Symbol) - Agent type (`:server`, `:client`, `:hybrid`)
+- `options` (Hash) - Configuration options
+
+## Configuration Options
+
+When creating agents, you can pass configuration options:
+
+```ruby
+class MyAgent < Agent99::Base
+  def initialize(options = {})
+    super(options)
+  end
+end
+
+agent = MyAgent.new(
+  registry_url: 'http://localhost:4567',
+  message_client: 'nats',
+  timeout: 30,
+  log_level: :info
+)
+```
+
+### Available Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `registry_url` | String | `http://localhost:4567` | Registry service URL |
+| `message_client` | String | `nats` | Message broker type (`nats`, `amqp`, `tcp`) |
+| `timeout` | Integer | 30 | Default request timeout (seconds) |
+| `log_level` | Symbol | `:info` | Logging level |
+| `retry_attempts` | Integer | 3 | Request retry attempts |
+| `retry_delay` | Integer | 1 | Delay between retries (seconds) |
+
+## Examples
+
+### Simple Server Agent
+
+```ruby
+class GreeterAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :server,
+      capabilities: ['greeting', 'hello']
+    }
+  end
+
+  def process_request(payload)
+    name = payload.dig(:name) || "World"
+    logger.info "Greeting #{name}"
+    
+    send_response(
+      message: "Hello, #{name}!",
+      timestamp: Time.now.iso8601
+    )
+  end
+end
+```
+
+### Client Agent with Error Handling
+
+```ruby
+class ClientAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :client,
+      capabilities: ['client_operations']
+    }
+  end
+
+  def make_greeting_request(name)
+    greeters = discover_agents(['greeting'])
+    
+    if greeters.empty?
+      logger.warn "No greeting agents available"
+      return nil
+    end
+
+    begin
+      response = send_request(
+        greeters.first[:name], 
+        { name: name },
+        { timeout: 10 }
+      )
+      
+      logger.info "Received: #{response[:message]}"
+      response
+    rescue => e
+      logger.error "Request failed: #{e.message}"
+      nil
+    end
+  end
+end
+```
+
+### Hybrid Agent with State
+
+```ruby
+class StatefulAgent < Agent99::Base
+  def initialize(options = {})
+    super(options)
+    @request_count = 0
+    @mutex = Mutex.new
+  end
+
+  def info
+    {
+      name: self.class.to_s,
+      type: :hybrid,
+      capabilities: ['stateful', 'counter']
+    }
+  end
+
+  def process_request(payload)
+    @mutex.synchronize do
+      @request_count += 1
+      
+      if payload[:operation] == 'get_count'
+        send_response(count: @request_count)
+      elsif payload[:operation] == 'reset_count'
+        @request_count = 0
+        send_response(count: 0, status: 'reset')
+      else
+        send_error('Unknown operation', 'INVALID_OPERATION')
+      end
+    end
+  end
+end
+```
+
+## Thread Safety
+
+The `Agent99::Base` class is designed to be thread-safe for concurrent request processing. However:
+
+- **Subclass implementations** should ensure thread safety in their `process_request` methods
+- **Shared state** should be protected with mutexes or other synchronization primitives  
+- **Instance variables** may be accessed concurrently during request processing
+
+## Error Handling
+
+The base class provides automatic error handling for:
+
+- **Network failures** during agent registration and discovery
+- **Message broker disconnections** with automatic retry
+- **Invalid message formats** with appropriate error responses
+- **Unhandled exceptions** in `process_request` (converted to error responses)
+
+## Next Steps
+
+- **[Registry Client](registry-client.md)** - Registry service API
+- **[Message Clients](message-clients.md)** - Message broker clients
+- **[Schemas](schemas.md)** - Schema validation system