agent99 0.0.3 → 0.0.5

data/docs/agent-development/request-response-handling.md

@@ -0,0 +1,512 @@
+# Request & Response Handling
+
+Understanding how to properly handle requests and responses is fundamental to building robust Agent99 applications. This guide covers patterns, best practices, and advanced techniques.
+
+## Request Processing Lifecycle
+
+![Request Processing Lifecycle](../assets/images/request-processing-lifecycle.svg)
+
+## Basic Request Handling
+
+### Simple Request Processing
+
+```ruby
+class SimpleAgent < Agent99::Base
+  def process_request(payload)
+    # Extract data from payload
+    user_name = payload.dig(:name) || "Anonymous"
+    
+    # Perform business logic
+    greeting = generate_greeting(user_name)
+    
+    # Send response
+    send_response(message: greeting)
+  end
+
+  private
+
+  def generate_greeting(name)
+    "Hello, #{name}! Welcome to Agent99."
+  end
+end
+```
+
+### With Input Validation
+
+```ruby
+class ValidatingAgent < Agent99::Base
+  def process_request(payload)
+    # Validate required fields
+    unless payload.key?(:user_id)
+      return send_error("Missing required field: user_id", "MISSING_FIELD")
+    end
+    
+    unless payload[:user_id].is_a?(String) && !payload[:user_id].empty?
+      return send_error("Invalid user_id: must be non-empty string", "INVALID_FORMAT")
+    end
+    
+    # Process valid request
+    result = lookup_user_data(payload[:user_id])
+    send_response(result)
+  end
+
+  private
+
+  def lookup_user_data(user_id)
+    # Simulate database lookup
+    {
+      user_id: user_id,
+      name: "User #{user_id}",
+      status: "active",
+      last_seen: Time.now.iso8601
+    }
+  end
+end
+```
+
+## Advanced Request Patterns
+
+### Asynchronous Processing
+
+For long-running operations, acknowledge receipt immediately and process asynchronously:
+
+```ruby
+class AsyncProcessingAgent < Agent99::Base
+  def initialize
+    super
+    @job_queue = Queue.new
+    @worker_thread = Thread.new { process_jobs }
+  end
+
+  def process_request(payload)
+    job_id = SecureRandom.uuid
+    
+    # Acknowledge receipt immediately
+    send_response(
+      status: "accepted",
+      job_id: job_id,
+      message: "Request queued for processing"
+    )
+    
+    # Queue for background processing
+    @job_queue << {
+      id: job_id,
+      payload: payload,
+      requester: current_request_id
+    }
+  end
+
+  private
+
+  def process_jobs
+    while job = @job_queue.pop
+      begin
+        result = perform_long_operation(job[:payload])
+        
+        # Send completion notification (if supported)
+        notify_completion(job[:requester], job[:id], result)
+      rescue => e
+        logger.error "Job #{job[:id]} failed: #{e.message}"
+        notify_failure(job[:requester], job[:id], e.message)
+      end
+    end
+  end
+
+  def perform_long_operation(payload)
+    # Simulate long operation
+    sleep(5)
+    { result: "Operation completed", data: payload }
+  end
+end
+```
+
+### Streaming Responses
+
+For data that comes in chunks:
+
+```ruby
+class StreamingAgent < Agent99::Base
+  def process_request(payload)
+    file_path = payload.dig(:file_path)
+    
+    unless File.exist?(file_path)
+      return send_error("File not found: #{file_path}", "FILE_NOT_FOUND")
+    end
+    
+    # Send initial response
+    send_response(
+      status: "streaming",
+      total_size: File.size(file_path),
+      chunk_size: 1024
+    )
+    
+    # Stream file contents
+    File.open(file_path, 'rb') do |file|
+      chunk_number = 0
+      while chunk = file.read(1024)
+        send_chunk(chunk_number, chunk)
+        chunk_number += 1
+      end
+    end
+    
+    # Send completion marker
+    send_completion()
+  end
+
+  private
+
+  def send_chunk(number, data)
+    # Implementation depends on messaging system
+    # This is a conceptual example
+    publish_message({
+      type: "chunk",
+      sequence: number,
+      data: Base64.encode64(data)
+    })
+  end
+
+  def send_completion
+    publish_message({
+      type: "stream_complete"
+    })
+  end
+end
+```
+
+## Response Patterns
+
+### Success Responses
+
+```ruby
+# Simple success
+send_response(result: "Operation successful")
+
+# Rich success response
+send_response(
+  status: "success",
+  data: processed_data,
+  metadata: {
+    processing_time: elapsed_time,
+    version: "1.0.0"
+  }
+)
+
+# Collection response
+send_response(
+  items: search_results,
+  total_count: total_count,
+  page: current_page,
+  has_more: has_more_pages
+)
+```
+
+### Error Responses
+
+```ruby
+# Simple error
+send_error("Something went wrong")
+
+# Structured error
+send_error("Invalid input data", "VALIDATION_ERROR")
+
+# Rich error response
+send_error(
+  "Database connection failed",
+  "DATABASE_ERROR",
+  {
+    retry_after: 30,
+    support_id: "ERR-#{SecureRandom.hex(8)}",
+    details: {
+      attempted_host: db_host,
+      timeout: connection_timeout
+    }
+  }
+)
+```
+
+## Request Context and Headers
+
+### Accessing Request Headers
+
+```ruby
+class HeaderAwareAgent < Agent99::Base
+  def process_request(payload)
+    # Access headers from the current request
+    request_id = header_value('request_id')
+    user_id = header_value('user_id')
+    correlation_id = header_value('correlation_id')
+    
+    logger.info "Processing request #{request_id} for user #{user_id}"
+    
+    # Use headers in processing
+    if authorized_user?(user_id)
+      result = perform_operation(payload)
+      send_response(result)
+    else
+      send_error("Unauthorized access", "UNAUTHORIZED")
+    end
+  end
+
+  private
+
+  def authorized_user?(user_id)
+    # Check authorization logic
+    user_id && user_id.start_with?('user_')
+  end
+end
+```
+
+### Setting Response Headers
+
+```ruby
+def process_request(payload)
+  result = process_data(payload)
+  
+  # Set custom headers in response
+  set_header('processing_node', Socket.gethostname)
+  set_header('cache_status', 'miss')
+  set_header('processing_time', elapsed_time.to_s)
+  
+  send_response(result)
+end
+```
+
+## Error Handling Strategies
+
+### Graceful Degradation
+
+```ruby
+class ResilientAgent < Agent99::Base
+  def process_request(payload)
+    begin
+      # Try primary service
+      result = primary_service.process(payload)
+      send_response(result)
+    rescue PrimaryServiceError => e
+      logger.warn "Primary service failed: #{e.message}"
+      
+      begin
+        # Fallback to secondary service
+        result = secondary_service.process(payload)
+        result[:fallback_used] = true
+        send_response(result)
+      rescue SecondaryServiceError => e2
+        logger.error "Both services failed: #{e2.message}"
+        
+        # Return cached or default result
+        default_result = get_cached_result(payload) || default_response
+        default_result[:degraded_service] = true
+        send_response(default_result)
+      end
+    end
+  end
+
+  private
+
+  def get_cached_result(payload)
+    # Check cache for previous result
+    cache_key = generate_cache_key(payload)
+    cached_data = cache.get(cache_key)
+    
+    if cached_data && fresh_enough?(cached_data)
+      cached_data[:from_cache] = true
+      return cached_data
+    end
+    
+    nil
+  end
+
+  def default_response
+    {
+      status: "service_unavailable",
+      message: "Service temporarily unavailable",
+      retry_after: 60
+    }
+  end
+end
+```
+
+### Circuit Breaker Pattern
+
+```ruby
+class CircuitBreakerAgent < Agent99::Base
+  def initialize
+    super
+    @circuit_breaker = CircuitBreaker.new(
+      failure_threshold: 5,
+      recovery_timeout: 30
+    )
+  end
+
+  def process_request(payload)
+    @circuit_breaker.call do
+      # Potentially failing operation
+      external_service.process(payload)
+    end.then do |result|
+      send_response(result)
+    end.rescue do |error|
+      case error
+      when CircuitBreaker::OpenError
+        send_error("Service temporarily unavailable", "CIRCUIT_OPEN")
+      else
+        send_error("Service error: #{error.message}", "SERVICE_ERROR")
+      end
+    end
+  end
+end
+```
+
+## Request Routing and Delegation
+
+### Multi-operation Agent
+
+```ruby
+class MultiOperationAgent < Agent99::Base
+  def process_request(payload)
+    operation = payload.dig(:operation)
+    
+    case operation
+    when 'create'
+      handle_create(payload)
+    when 'read'
+      handle_read(payload)
+    when 'update'
+      handle_update(payload)
+    when 'delete'
+      handle_delete(payload)
+    else
+      send_error("Unknown operation: #{operation}", "INVALID_OPERATION")
+    end
+  end
+
+  private
+
+  def handle_create(payload)
+    # Creation logic
+    entity = create_entity(payload[:data])
+    send_response(entity: entity, status: "created")
+  end
+
+  def handle_read(payload)
+    # Read logic
+    entity = find_entity(payload[:id])
+    if entity
+      send_response(entity: entity)
+    else
+      send_error("Entity not found", "NOT_FOUND")
+    end
+  end
+
+  def handle_update(payload)
+    # Update logic
+    entity = update_entity(payload[:id], payload[:data])
+    send_response(entity: entity, status: "updated")
+  end
+
+  def handle_delete(payload)
+    # Delete logic
+    delete_entity(payload[:id])
+    send_response(status: "deleted")
+  end
+end
+```
+
+## Testing Request Handling
+
+### Unit Testing
+
+```ruby
+require 'minitest/autorun'
+
+class TestCalculatorAgent < Minitest::Test
+  def setup
+    @agent = CalculatorAgent.new
+  end
+
+  def test_successful_addition
+    payload = { operation: 'add', a: 5, b: 3 }
+    
+    # Mock the send_response method
+    response = nil
+    @agent.stub(:send_response, ->(data) { response = data }) do
+      @agent.process_request(payload)
+    end
+    
+    assert_equal 8, response[:result]
+    assert_equal 'add', response[:operation]
+  end
+
+  def test_division_by_zero
+    payload = { operation: 'divide', a: 10, b: 0 }
+    
+    error_response = nil
+    @agent.stub(:send_error, ->(msg, code) { 
+      error_response = { message: msg, code: code } 
+    }) do
+      @agent.process_request(payload)
+    end
+    
+    assert_equal 'DIVISION_BY_ZERO', error_response[:code]
+  end
+end
+```
+
+## Best Practices
+
+### Do's ✅
+
+- **Always respond**: Every request should get a response
+- **Validate early**: Check inputs before processing
+- **Use schemas**: Define and validate request/response structures
+- **Log appropriately**: Track requests without logging sensitive data
+- **Handle timeouts**: Set reasonable processing time limits
+- **Provide context**: Include helpful error messages and codes
+
+### Don'ts ❌
+
+- **Don't block indefinitely**: Always have timeouts
+- **Don't expose internals**: Keep error messages user-friendly
+- **Don't ignore errors**: Handle and respond to all error conditions
+- **Don't trust input**: Always validate and sanitize
+- **Don't forget correlation**: Maintain request tracing across calls
+
+## Performance Considerations
+
+### Memory Management
+
+```ruby
+def process_request(payload)
+  # Stream large data instead of loading all at once
+  if payload[:data_size] > LARGE_DATA_THRESHOLD
+    process_data_streaming(payload)
+  else
+    process_data_in_memory(payload)
+  end
+end
+```
+
+### Connection Pooling
+
+```ruby
+class DatabaseAgent < Agent99::Base
+  def initialize
+    super
+    @connection_pool = ConnectionPool.new(size: 10) do
+      Database.connect
+    end
+  end
+
+  def process_request(payload)
+    @connection_pool.with do |connection|
+      result = connection.query(payload[:sql])
+      send_response(rows: result.to_a)
+    end
+  end
+end
+```
+
+## Next Steps
+
+- **[Error Handling & Logging](error-handling-and-logging.md)** - Comprehensive error strategies
+- **[Schema Definition](schema-definition.md)** - Advanced schema patterns  
+- **[Advanced Features](../advanced-topics/advanced-features.md)** - Complex patterns and techniques

data/docs/agent99_framework/central_registry.md

@@ -0,0 +1,94 @@
+# Central Registry
+
+## Overview
+
+The Central Registry is a crucial component of the Agent99 Framework, serving as a centralized hub for agent registration, discovery, and management. Its primary purpose is to facilitate communication and coordination between various agents within the framework, allowing them to register their capabilities and discover other agents with specific skills.
+
+The registry provides a RESTful API that can be implemented in any programming language or web framework that supports HTTPS endpoints. This document outlines the API specifications for implementing a compatible Central Registry.
+
+## API Endpoints
+
+### 1. Health Check
+
+- **Endpoint**: GET /healthcheck
+- **Purpose**: Provides a simple health check for the registry service.
+- **Response**: JSON object containing the current count of registered agents.
+- **Example Response**:
+  ```json
+  {
+    "agent_count": 5
+  }
+  ```
+
+### 2. Register Agent
+
+- **Endpoint**: POST /register
+- **Purpose**: Allows an agent to register itself with the registry, providing its name and capabilities.
+- **Request Body**: JSON object containing agent information.
+- **Response**: JSON object with a newly generated UUID for the registered agent.
+- **Example Request**:
+  ```json
+  {
+    "name": "TextAnalyzer",
+    "capabilities": ["sentiment analysis", "named entity recognition"]
+  }
+  ```
+- **Example Response**:
+  ```json
+  {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+  ```
+
+### 3. Discover Agents
+
+- **Endpoint**: GET /discover
+- **Purpose**: Allows discovery of agents based on a specific capability.
+- **Query Parameter**: capability (string)
+- **Response**: JSON array of matching agents with their full information.
+- **Example Request**: GET /discover?capability=sentiment+analysis
+- **Example Response**:
+  ```json
+  [
+    {
+      "name": "TextAnalyzer",
+      "capabilities": ["sentiment analysis", "named entity recognition"],
+      "uuid": "550e8400-e29b-41d4-a716-446655440000"
+    }
+  ]
+  ```
+
+### 4. Withdraw Agent
+
+- **Endpoint**: DELETE /withdraw/:uuid
+- **Purpose**: Removes an agent from the registry using its UUID.
+- **Response**: 
+  - 204 No Content if successful
+  - 404 Not Found if the agent UUID is not in the registry
+- **Example Request**: DELETE /withdraw/550e8400-e29b-41d4-a716-446655440000
+
+### 5. List All Agents
+
+- **Endpoint**: GET /
+- **Purpose**: Retrieves a list of all registered agents.
+- **Response**: JSON array containing all registered agents' information.
+
+## Implementation Notes
+
+1. Agent capabilities should be stored and compared in lowercase to ensure case-insensitive matching.
+2. The current implementation uses an in-memory array to store agent information. For production use, consider using a persistent database like SQLite or a more scalable solution.
+3. The discovery process currently uses simple keyword matching. Future enhancements could include semantic matching for more accurate agent discovery.
+
+## Potential Enhancements
+
+1. **Persistent Storage**: Implement a database backend for storing agent information, ensuring data persistence across server restarts.
+2. **Authentication and Authorization**: Add security measures to protect sensitive endpoints and ensure only authorized agents can register or withdraw.
+3. **Semantic Matching**: Enhance the discovery process with natural language processing or vector search capabilities for more intelligent agent matching.
+4. **Agent Health Monitoring**: Implement periodic health checks on registered agents to ensure they are still active and available.
+5. **Versioning**: Add support for agent versioning to manage different versions of agents with similar capabilities.
+6. **Pagination**: Implement pagination for the discovery and list all endpoints to handle large numbers of agents efficiently.
+7. **Metrics and Logging**: Add comprehensive logging and metrics collection for better monitoring and debugging of the registry service.
+8. **API Rate Limiting**: Implement rate limiting to prevent abuse and ensure fair usage of the registry service.
+
+By implementing this API, developers can create a compatible Central Registry for the Agent99 Framework in their preferred language or framework, enabling seamless integration and communication between diverse agents in the ecosystem.
+