agent99 0.0.2 → 0.0.4

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

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.