agent99 0.0.3 → 0.0.5

data/docs/examples/basic-examples.md

@@ -0,0 +1,268 @@
+# Basic Examples
+
+This section contains basic examples to help you get started with Agent99.
+
+## Simple Greeter Agent
+
+Here's a basic server agent that responds to greeting requests:
+
+```ruby
+require 'agent99'
+require 'simple_json_schema_builder'
+
+# Define the request schema
+class GreeterRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+    string :name, required: true, examples: ["World"]
+  end
+end
+
+# Create the agent
+class GreeterAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     ['greeter', 'hello_world'],
+      request_schema:   GreeterRequest.schema
+    }
+  end
+
+  def process_request(payload)
+    name = payload.dig(:name) || "World"
+    response = { result: "Hello, #{name}!" }
+    send_response(response)
+  end
+end
+
+# Run the agent
+if __FILE__ == $0
+  agent = GreeterAgent.new
+  puts "Starting Greeter Agent..."
+  agent.run
+end
+```
+
+## Echo Agent
+
+An agent that echoes back whatever message it receives:
+
+```ruby
+require 'agent99'
+
+class EchoAgent < Agent99::Base
+  def info
+    {
+      name:           self.class.to_s,
+      type:           :server,
+      capabilities:   ['echo', 'mirror']
+    }
+  end
+
+  def process_request(payload)
+    logger.info "Echo agent received: #{payload}"
+    send_response(message: "You said: #{payload}")
+  end
+end
+
+# Run the agent
+if __FILE__ == $0
+  agent = EchoAgent.new
+  puts "Starting Echo Agent..."
+  agent.run
+end
+```
+
+## Calculator Agent
+
+A more complex agent that performs basic arithmetic operations:
+
+```ruby
+require 'agent99'
+require 'simple_json_schema_builder'
+
+class CalculatorRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+    string :operation, enum: %w[add subtract multiply divide], required: true
+    number :a, required: true
+    number :b, required: true
+  end
+end
+
+class CalculatorAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     ['calculator', 'math', 'arithmetic'],
+      request_schema:   CalculatorRequest.schema
+    }
+  end
+
+  def process_request(payload)
+    operation = payload.dig(:operation)
+    a = payload.dig(:a).to_f
+    b = payload.dig(:b).to_f
+
+    result = case operation
+    when 'add'
+      a + b
+    when 'subtract'
+      a - b
+    when 'multiply'
+      a * b
+    when 'divide'
+      return send_error("Division by zero") if b == 0
+      a / b
+    else
+      return send_error("Unknown operation: #{operation}")
+    end
+
+    send_response(result: result, operation: operation, inputs: { a: a, b: b })
+  end
+end
+
+# Run the agent
+if __FILE__ == $0
+  agent = CalculatorAgent.new
+  puts "Starting Calculator Agent..."
+  agent.run
+end
+```
+
+## Client Agent Example
+
+An agent that makes requests to other agents:
+
+```ruby
+require 'agent99'
+
+class ClientAgent < Agent99::Base
+  def info
+    {
+      name:           self.class.to_s,
+      type:           :client,
+      capabilities:   ['client', 'requester']
+    }
+  end
+
+  def start
+    # Find available agents
+    agents = discover_agents(['greeter'])
+    
+    if agents.any?
+      greeter = agents.first
+      logger.info "Found greeter agent: #{greeter[:name]}"
+      
+      # Send a request
+      request = {
+        name: "Agent99 Client"
+      }
+      
+      response = send_request(greeter[:name], request)
+      logger.info "Received response: #{response}"
+    else
+      logger.warn "No greeter agents found"
+    end
+  end
+end
+
+# Run the client
+if __FILE__ == $0
+  client = ClientAgent.new
+  puts "Starting Client Agent..."
+  
+  # Run once and exit
+  client.start
+end
+```
+
+## Hybrid Agent Example
+
+An agent that can both serve requests and make requests to other agents:
+
+```ruby
+require 'agent99'
+
+class HybridAgent < Agent99::Base
+  def info
+    {
+      name:           self.class.to_s,
+      type:           :hybrid,
+      capabilities:   ['proxy', 'forwarder']
+    }
+  end
+
+  def process_request(payload)
+    # This agent forwards requests to other agents
+    target_capability = payload.dig(:forward_to)
+    message = payload.dig(:message)
+
+    if target_capability && message
+      # Find agents with the target capability
+      agents = discover_agents([target_capability])
+      
+      if agents.any?
+        target_agent = agents.first
+        
+        # Forward the message
+        response = send_request(target_agent[:name], { name: message })
+        send_response(forwarded_response: response, target_agent: target_agent[:name])
+      else
+        send_error("No agents found with capability: #{target_capability}")
+      end
+    else
+      send_error("Missing 'forward_to' or 'message' in request")
+    end
+  end
+end
+
+# Run the agent
+if __FILE__ == $0
+  agent = HybridAgent.new
+  puts "Starting Hybrid Agent..."
+  agent.run
+end
+```
+
+## Running the Examples
+
+1. **Start the Registry**: 
+   ```bash
+   ruby examples/registry.rb
+   ```
+
+2. **Start a Message Broker** (NATS or RabbitMQ):
+   ```bash
+   nats-server
+   # OR
+   rabbitmq-server
+   ```
+
+3. **Run the Agents**:
+   ```bash
+   # In separate terminals
+   ruby greeter_agent.rb
+   ruby calculator_agent.rb
+   ruby client_agent.rb
+   ```
+
+## Testing Agent Communication
+
+You can test agent communication using the client example or by sending HTTP requests to the registry:
+
+```bash
+# List all registered agents
+curl http://localhost:4567/agents
+
+# Find agents by capability
+curl http://localhost:4567/agents/discover/greeter
+```
+
+## Next Steps
+
+- [Advanced Examples](advanced-examples.md) - More complex agent patterns
+- [Schema Definition](../agent-development/schema-definition.md) - Learn about request/response schemas
+- [Message Processing](../framework-components/message-processing.md) - Understand message handling

data/docs/{agent_discovery.md → framework-components/agent-discovery.md}

@@ -12,17 +12,21 @@ The agent discovery process involves the following steps:
 2. **Discovery**: When an agent needs to discover other agents, it queries the registry for agents with specific capabilities.
 3. **Response**: The registry responds with a list of available agents, allowing them to interact based on their capabilities.
 
-### Declaring Capabilities
+### Declaring Capabilities in the Info Method
 
-Each agent must implement the `capabilities` method to declare its capabilities as an array of strings:
+Each agent must implement the `info` method to declare its capabilities as an array of strings:
 
 ```ruby
-def capabilities
-  ['process_image', 'face_detection']
+def info
+  {
+    # ...
+    capabilities:  ['process_image', 'face_detection'],
+    # ...
+  }
 end
 ```
 
-**Note**: The discovery mechanism is based on an exact match (case insensitive) between the requested capability and the entries in the agent's capabilities array. For example, if an agent declares its capabilities as mentioned above, a discovery request for `'FACE_DETECTION'` will successfully match.
+**Note**: The discovery mechanism is based on an exact match (case insensitive) between the requested capability and the entries in the agent's capabilities array in its information packet. For example, if an agent declares its capabilities as mentioned above, a discovery request for `'FACE_DETECTION'` will successfully match.
 
 ### Discovery API
 

data/docs/{agent_registry_processes.md → framework-components/agent-registry.md}

@@ -38,8 +38,14 @@ end
 # Define the new Agent ....
 
 class MyAgent < Agent99::Base
-  REQUEST_SCHEMA    = MyAgentRequest.schema
-  def capabilities  = %w[ greeter hello_world ]
+  def info
+    {
+      # ...
+      request_schema: MyAgentRequest.schema
+      capabilities:   %w[ greeter hello_world ],
+      # ...
+    }
+  end
 end
 
 # You may create multiple instances of the agent if needed
@@ -60,7 +66,7 @@ my_agent.id
 
 The image below shows how the `Agent99::Base` class uses dependency injection in its constructor method to bring in an instance of the `RegristryClient` class to provide an interface to the centralized regristery service.
 
-![Agent Register, Discover and Withdraw Processes](diagrams/agent_registry_processes.png)
+![Agent Register, Discover and Withdraw Processes](../assets/images/agent-registry-processes.svg)
 
 The above image also show the other services provided via the RegistryClient class.
 

data/docs/{message_processing.md → framework-components/message-processing.md}

@@ -31,6 +31,8 @@ and validation rules.
 
 ### Message Processing Flow
 
+![Message Processing Flow](../assets/images/message-processing-flow.svg)
+
 #### Request Processing
 1. Message arrives and is validated against schema
 2. If validation passes:
@@ -42,7 +44,7 @@ and validation rules.
     - Error is logged
     - Request is not processed further
 
-![Request Message Processing Flow](diagrams/request_flow.png)
+![Request Message Processing Flow](../assets/images/request-flow.svg)
 
 #### Response Processing
 1. Response message is received

data/docs/getting-started/basic-example.md

@@ -0,0 +1,306 @@
+# Basic Example: Building a Calculator Service
+
+This detailed example walks you through creating a complete calculator service using Agent99, demonstrating key concepts like schema validation, error handling, and agent discovery.
+
+## What We'll Build
+
+A distributed calculator system with:
+- **Calculator Agent**: Performs arithmetic operations
+- **Client Agent**: Sends calculation requests
+- **Request/Response Schemas**: Validates input and output
+- **Error Handling**: Graceful error management
+
+## Step 1: Define the Request Schema
+
+Create `calculator_schemas.rb`:
+
+```ruby
+require 'simple_json_schema_builder'
+
+# Request schema for calculator operations
+class CalculatorRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+    string :operation, enum: %w[add subtract multiply divide], required: true,
+           description: "The arithmetic operation to perform"
+    number :a, required: true, description: "First operand"
+    number :b, required: true, description: "Second operand"
+  end
+end
+
+# Response schema for calculator results
+class CalculatorResponse < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+    number :result, required: true, description: "The calculation result"
+    string :operation, required: true, description: "The operation performed"
+    object :operands do
+      number :a, required: true
+      number :b, required: true
+    end
+    string :timestamp, required: true, description: "When the calculation was performed"
+  end
+end
+```
+
+## Step 2: Create the Calculator Agent
+
+Create `calculator_agent.rb`:
+
+```ruby
+require 'agent99'
+require_relative 'calculator_schemas'
+
+class CalculatorAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     ['calculator', 'math', 'arithmetic'],
+      description:      'Performs basic arithmetic operations',
+      request_schema:   CalculatorRequest.schema,
+      response_schema:  CalculatorResponse.schema
+    }
+  end
+
+  def process_request(payload)
+    logger.info "Received calculation request: #{payload}"
+    
+    # Extract and validate inputs
+    operation = payload.dig(:operation)
+    a = payload.dig(:a).to_f
+    b = payload.dig(:b).to_f
+
+    # Perform calculation
+    result = perform_calculation(operation, a, b)
+    
+    if result.is_a?(Hash) && result[:error]
+      # Send error response
+      send_error(result[:error], result[:code] || 'CALCULATION_ERROR')
+    else
+      # Send successful response
+      response = {
+        result: result,
+        operation: operation,
+        operands: { a: a, b: b },
+        timestamp: Time.now.iso8601
+      }
+      
+      send_response(response)
+    end
+  end
+
+  private
+
+  def perform_calculation(operation, a, b)
+    case operation
+    when 'add'
+      a + b
+    when 'subtract'
+      a - b
+    when 'multiply'
+      a * b
+    when 'divide'
+      return { error: "Division by zero is not allowed", code: 'DIVISION_BY_ZERO' } if b == 0
+      a / b
+    else
+      { error: "Unknown operation: #{operation}", code: 'INVALID_OPERATION' }
+    end
+  end
+end
+
+# Run the agent if this file is executed directly
+if __FILE__ == $0
+  puts "🧮 Starting Calculator Agent..."
+  agent = CalculatorAgent.new
+  
+  # Handle graceful shutdown
+  trap('INT') do
+    puts "\n👋 Shutting down Calculator Agent..."
+    agent.shutdown
+    exit
+  end
+  
+  agent.run
+end
+```
+
+## Step 3: Create a Client Agent
+
+Create `calculator_client.rb`:
+
+```ruby
+require 'agent99'
+
+class CalculatorClient < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :client,
+      capabilities: ['calculator_client', 'testing']
+    }
+  end
+
+  def perform_calculations
+    # Find calculator agents
+    calculators = discover_agents(['calculator'])
+    
+    if calculators.empty?
+      puts "❌ No calculator agents found!"
+      return
+    end
+
+    calculator = calculators.first
+    puts "🎯 Found calculator: #{calculator[:name]}"
+
+    # Test calculations
+    test_cases = [
+      { operation: 'add', a: 10, b: 5, expected: 15 },
+      { operation: 'subtract', a: 10, b: 3, expected: 7 },
+      { operation: 'multiply', a: 4, b: 7, expected: 28 },
+      { operation: 'divide', a: 20, b: 4, expected: 5 },
+      { operation: 'divide', a: 10, b: 0, expected: 'ERROR' }  # This should error
+    ]
+
+    test_cases.each_with_index do |test_case, index|
+      puts "\n📋 Test #{index + 1}: #{test_case[:a]} #{test_case[:operation]} #{test_case[:b]}"
+      
+      begin
+        response = send_request(calculator[:name], test_case.reject { |k, _| k == :expected })
+        
+        if response[:error]
+          puts "⚠️  Error: #{response[:error]} (#{response[:code]})"
+          puts "✅ Expected error!" if test_case[:expected] == 'ERROR'
+        else
+          result = response[:result]
+          puts "📊 Result: #{result}"
+          
+          if test_case[:expected] != 'ERROR'
+            if (result - test_case[:expected]).abs < 0.001  # Handle floating point comparison
+              puts "✅ Test passed!"
+            else
+              puts "❌ Test failed! Expected #{test_case[:expected]}, got #{result}"
+            end
+          end
+        end
+      rescue => e
+        puts "💥 Request failed: #{e.message}"
+      end
+    end
+  end
+end
+
+# Run the client if this file is executed directly
+if __FILE__ == $0
+  puts "📱 Starting Calculator Client..."
+  client = CalculatorClient.new
+  client.perform_calculations
+end
+```
+
+## Step 4: Run the Complete Example
+
+### Terminal 1: Start the Registry
+```bash
+# From the agent99 repository
+ruby examples/registry.rb
+```
+
+### Terminal 2: Start NATS (or RabbitMQ)
+```bash
+nats-server
+```
+
+### Terminal 3: Start the Calculator Agent
+```bash
+ruby calculator_agent.rb
+```
+
+Expected output:
+```
+🧮 Starting Calculator Agent...
+INFO -- Agent CalculatorAgent registered successfully
+INFO -- Agent listening for messages...
+```
+
+### Terminal 4: Run the Client
+```bash
+ruby calculator_client.rb
+```
+
+Expected output:
+```
+📱 Starting Calculator Client...
+🎯 Found calculator: CalculatorAgent
+
+📋 Test 1: 10 add 5
+📊 Result: 15.0
+✅ Test passed!
+
+📋 Test 2: 10 subtract 3
+📊 Result: 7.0
+✅ Test passed!
+
+📋 Test 3: 4 multiply 7
+📊 Result: 28.0
+✅ Test passed!
+
+📋 Test 4: 20 divide 4
+📊 Result: 5.0
+✅ Test passed!
+
+📋 Test 5: 10 divide 0
+⚠️  Error: Division by zero is not allowed (DIVISION_BY_ZERO)
+✅ Expected error!
+```
+
+## Step 5: Explore the Registry
+
+While everything is running, visit http://localhost:4567/agents in your browser to see registered agents, or use curl:
+
+```bash
+# List all agents
+curl http://localhost:4567/agents | jq
+
+# Find calculator agents
+curl http://localhost:4567/agents/discover/calculator | jq
+```
+
+## Key Concepts Demonstrated
+
+### 🏗️ **Agent Architecture**
+- **Server Agent**: Waits for and processes requests
+- **Client Agent**: Discovers and communicates with other agents
+- **Registry**: Central discovery service
+
+### 📝 **Schema Validation**
+- **Request Schema**: Validates incoming requests
+- **Response Schema**: Defines response structure
+- **Type Safety**: Ensures data integrity
+
+### 🛡️ **Error Handling**
+- **Validation Errors**: Invalid input handling
+- **Business Logic Errors**: Division by zero, invalid operations
+- **Network Errors**: Communication failures
+
+### 🔍 **Agent Discovery**
+- **Capability-based**: Find agents by what they can do
+- **Dynamic**: Agents can join and leave at runtime
+- **Fault-tolerant**: Graceful handling of missing agents
+
+## What's Next?
+
+- **[Core Concepts](../core-concepts/what-is-an-agent.md)** - Deep dive into agent theory
+- **[Schema Definition](../agent-development/schema-definition.md)** - Advanced schema patterns
+- **[Advanced Examples](../examples/advanced-examples.md)** - Complex multi-agent scenarios
+- **[Error Handling](../agent-development/error-handling-and-logging.md)** - Comprehensive error strategies
+
+## Exercises
+
+Try extending this example:
+
+1. **Add more operations**: power, square root, factorial
+2. **Add validation**: check for reasonable input ranges
+3. **Add persistence**: log all calculations to a file
+4. **Add monitoring**: track success/failure rates
+5. **Add authentication**: require API keys for requests