agent99 0.0.1 → 0.0.3

data/docs/api_reference.md

@@ -0,0 +1,136 @@
+# 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
+
+#### `capabilities`
+Returns an array of strings describing the agent's capabilities.
+```ruby
+def capabilities
+  ['process_image', 'face_detection']
+end
+```
+
+#### `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/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.