agent99 0.0.2 → 0.0.3

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/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
+```
+

data/docs/control_actions.md

@@ -0,0 +1,179 @@
+# Agent99 Framework
+
+## Control Actions
+
+Agent99 provides a robust control system that allows for dynamic management of agents during runtime. Control actions enable administrative operations and state management without requiring agent restarts or redeployment.
+
+### Built-in Control Actions
+
+The framework includes several built-in control actions:
+
+#### shutdown
+- Gracefully stops the agent
+- Withdraws registration from the registry
+- Cleans up resources and connections
+- Triggers the `fini` method
+- Example usage:
+```ruby
+{
+  header: {
+    type: "control",
+    to_uuid: "target_agent_id",
+    from_uuid: "control_agent_id",
+    event_uuid: "evt_123",
+    timestamp: 1638360000000000
+  },
+  action: "shutdown"
+}
+```
+
+#### pause
+TODO: haven't decided whether messages are left in the messaging network or whether they should be queued within the agent.  TBD
+
+- Temporarily halts message processing
+- Maintains agent registration
+- Continues to accept control messages
+- Queues other messages for later processing
+- Example usage:
+```ruby
+{
+  header: {
+    type: "control",
+    to_uuid: "target_agent_id",
+    from_uuid: "control_agent_id",
+    event_uuid: "evt_456",
+    timestamp: 1638360000000000
+  },
+  action: "pause"
+}
+```
+
+#### resume
+- Reactivates a paused agent
+- Processes any queued messages
+- Restores normal operation
+- Example usage:
+```ruby
+{
+  header: {
+    type: "control",
+    to_uuid: "target_agent_id",
+    from_uuid: "control_agent_id",
+    event_uuid: "evt_789",
+    timestamp: 1638360000000000
+  },
+  action: "resume"
+}
+```
+
+#### update_config
+
+TODO: This is still TBD waiting for the design of the overall configuration class.
+
+- Updates agent configuration at runtime
+- Allows dynamic behavior modification
+- Example usage:
+```ruby
+{
+  header: {
+    type: "control",
+    to_uuid: "target_agent_id",
+    from_uuid: "control_agent_id",
+    event_uuid: "evt_101",
+    timestamp: 1638360000000000
+  },
+  action: "update_config",
+  config: {
+    "log_level": "DEBUG",
+    "timeout": 30
+  }
+}
+```
+
+#### status
+- Requests current agent status
+- Returns operational statistics
+- Example usage:
+```ruby
+{
+  header: {
+    type: "control",
+    to_uuid: "target_agent_id",
+    from_uuid: "control_agent_id",
+    event_uuid: "evt_102",
+    timestamp: 1638360000000000
+  },
+  action: "status"
+}
+```
+
+### Implementing Custom Control Actions
+
+You can implement custom control actions by:
+
+1. Adding a handler method to your agent class:
+```ruby
+def handle_custom_action
+  # Implementation
+  send_control_response(status: "custom action completed")
+end
+```
+
+2. Registering the handler in CONTROL_HANDLERS:
+```ruby
+CONTROL_HANDLERS.merge!({
+  'custom_action' => :handle_custom_action
+})
+```
+
+### Best Practices
+
+1. **Response Handling**
+    - Always send a control response
+    - Include relevant status information
+    - Handle errors gracefully
+
+2. **State Management**
+    - Maintain consistent state transitions
+    - Document state dependencies
+    - Handle edge cases (e.g., pause while paused)
+
+3. **Security Considerations**
+    - Validate control message sources
+    - Implement appropriate authorization
+    - Log all control actions
+
+4. **Error Recovery**
+    - Implement timeout mechanisms
+    - Handle partial failures
+    - Provide status feedback
+
+### Control Flow Example
+
+```ruby
+class MyAgent < Agent99::Base
+  def handle_custom_restart
+    begin
+      cleanup_resources
+      reinitialize_state
+      send_control_response(status: "restart completed")
+    rescue StandardError => e
+      send_control_response(
+        status: "restart failed",
+        error: e.message
+      )
+    end
+  end
+end
+```
+
+### Monitoring Control Actions
+
+All control actions are automatically logged with:
+   * Timestamp
+   * Action type
+   * Source agent
+   * Result status
+   * Error information (if any)
+
+This enables effective monitoring and troubleshooting of agent behavior and system state.

data/docs/custom_agent_implementation.md

@@ -0,0 +1,30 @@
+# Agent99 Framework
+
+## Custom Agent Implementation
+
+### Creating a Custom Agent
+
+To create a custom agent:
+
+1. Subclass `Agent99::Base`.
+2. Define the request and response schemas.
+3. Implement the `receive_request` and `receive_response` methods.
+
+Example:
+
+```ruby
+class MyCustomAgent < Agent99::Base
+  REQUEST_SCHEMA = MyAgentRequest.schema
+
+  def receive_request
+    # Handle incoming request
+    response = { result: "Handled request" }
+    send_response(response)
+  end
+
+  def receive_response
+    # Handle incoming response from another agent
+  end
+end
+```
+

data/docs/diagrams/agent_registry_processes.dot

@@ -0,0 +1,42 @@
+digraph AgentRegistration {
+  rankdir=LR;
+  node [shape=box, style=rounded];
+  edge [fontsize=10];
+
+  MyAgent [label="MyAgent"];
+  RegistryClient [label="RegistryClient"];
+  CentralRegistry [label="Central Registry\n(Sinatra Server)"];
+
+  subgraph cluster_registration {
+    label="Registration Process";
+    color=lightgrey;
+    style=filled;
+
+    MyAgent -> RegistryClient [label="1. initialize"];
+    RegistryClient -> CentralRegistry [label="2. POST /register\n{name, capabilities}"];
+    CentralRegistry -> RegistryClient [label="3. 201 Created\n{uuid}"];
+    RegistryClient -> MyAgent [label="4. Return uuid"];
+  }
+
+  subgraph cluster_discovery {
+    label="Discovery Process";
+    color=lightblue;
+    style=filled;
+
+    MyAgent -> RegistryClient [label="5. discover(capability)"];
+    RegistryClient -> CentralRegistry [label="6. GET /discover?capability=..."];
+    CentralRegistry -> RegistryClient [label="7. 200 OK\n[matching agents]"];
+    RegistryClient -> MyAgent [label="8. Return matching agents"];
+  }
+
+  subgraph cluster_withdrawal {
+    label="Withdrawal Process";
+    color=lightpink;
+    style=filled;
+
+    MyAgent -> RegistryClient [label="9. withdraw(uuid)"];
+    RegistryClient -> CentralRegistry [label="10. DELETE /withdraw/:uuid"];
+    CentralRegistry -> RegistryClient [label="11. 204 No Content"];
+    RegistryClient -> MyAgent [label="12. Confirm withdrawal"];
+  }
+}

data/docs/diagrams/high_level_architecture.dot

@@ -0,0 +1,26 @@
+digraph Agent99Architecture {
+    rankdir=LR;
+    node [shape=box, style=rounded];
+    
+    subgraph cluster_0 {
+        label="Agent99 Framework";
+        style=dashed;
+        
+        Agent1 [label="Agent 1\n(Client)"];
+        Agent2 [label="Agent 2\n(Server)"];
+        Agent3 [label="Agent 3\n(Hybrid)"];
+    }
+    
+    Registry [shape=cylinder, label="Registry\nService"];
+    MessageBroker [shape=diamond, label="Message Broker\n(AMQP/NATS)"];
+    
+    // Registration flows
+    Agent1 -> Registry [label="register/discover", style=dashed];
+    Agent2 -> Registry [label="register/discover", style=dashed];
+    Agent3 -> Registry [label="register/discover", style=dashed];
+    
+    // Message flows
+    Agent1 -> MessageBroker [dir=both, label="publish/subscribe"];
+    Agent2 -> MessageBroker [dir=both, label="publish/subscribe"];
+    Agent3 -> MessageBroker [dir=both, label="publish/subscribe"];
+}

data/docs/diagrams/request_flow.dot

@@ -0,0 +1,42 @@
+digraph RequestFlow {
+    rankdir=TB;
+    node [shape=box, style=rounded];
+    
+    // Message arrival and initial processing
+    start [shape=oval, label="Message Arrives"];
+    dispatch [label="dispatcher()\nMessage Processing Loop"];
+    process [label="process_request(message)"];
+    validate [label="validate_schema()"];
+    
+    // Main processing branch
+    receive [label="receive_request()\nAgent Implementation"];
+    send [label="send_response()\nOptional Response"];
+    
+    // Error handling branch
+    error [label="Error Handler"];
+    error_response [label="Send Error Response"];
+    
+    // Flow connections
+    start -> dispatch;
+    dispatch -> process;
+    process -> validate;
+    
+    // Success path
+    validate -> receive [label="Valid"];
+    receive -> send [style=dashed];
+    
+    // Error path
+    validate -> error [label="Invalid"];
+    error -> error_response;
+    
+    // Styling
+    {
+        node [shape=note, style=filled, fillcolor=lightyellow];
+        note1 [label="Schema validation\nensures message\nintegrity"];
+        note2 [label="Custom processing\nin agent subclass"];
+    }
+    
+    // Connect notes
+    validate -> note1 [style=dotted, arrowhead=none];
+    receive -> note2 [style=dotted, arrowhead=none];
+}

data/docs/error_handling_and_logging.md

@@ -0,0 +1,13 @@
+# Agent99 Framework
+
+## Error Handling and Logging
+
+Agent99 incorporates robust error handling mechanisms, with error messages being captured and logged. The logging system is configured through environment variables to define the logging level and output destination.
+
+Example:
+
+```bash
+export LOG_LEVEL=DEBUG
+```
+
+Logs provide insights into agent activities, including errors encountered during message processing and system events.

data/docs/extending_the_framework.md

@@ -0,0 +1,11 @@
+# Agent99 Framework
+
+## Extending the Framework
+
+To extend Agent99:
+
+1. Implement custom modules and include them in your agents.
+2. Define new message types or schemas as needed.
+3. Use hooks to add functionality or override existing behavior.
+
+If a plugin system is developed in the future, it would allow for additional features without modifying the core framework.

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
+  }
+}
+```
+
+