agent99 0.0.3 → 0.0.5

data/docs/core-concepts/agent-types.md

@@ -0,0 +1,255 @@
+# Agent Types
+
+Agent99 supports three fundamental agent types, each designed for different communication patterns and use cases. Understanding these types is crucial for designing effective distributed systems.
+
+## Overview
+
+![Agent Types Overview](../assets/images/agent-types-overview.svg)
+
+## Server Agents
+
+Server agents **receive and respond to requests** from other agents. They're the workhorses of the Agent99 ecosystem.
+
+### Characteristics
+
+- **Reactive**: Wait for incoming requests
+- **Stateless**: Each request is handled independently (by default)
+- **Specialized**: Usually focus on specific capabilities
+- **Discoverable**: Register their capabilities for others to find
+
+### Example: Server Agent
+
+```ruby
+class WeatherAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :server,  # This makes it a server agent
+      capabilities: ['weather', 'forecast', 'temperature']
+    }
+  end
+
+  def process_request(payload)
+    location = payload.dig(:location)
+    
+    # Simulate weather lookup
+    weather_data = {
+      location: location,
+      temperature: rand(15..35),
+      condition: ['sunny', 'cloudy', 'rainy'].sample,
+      timestamp: Time.now.iso8601
+    }
+    
+    send_response(weather_data)
+  end
+end
+```
+
+### When to Use Server Agents
+
+- **Services**: Database access, calculations, data processing
+- **APIs**: Wrapping external APIs or services  
+- **Workers**: Background job processing
+- **Specialists**: Domain-specific functionality
+
+## Client Agents
+
+Client agents **make requests to other agents** and handle their responses. They're the initiators of communication.
+
+### Characteristics
+
+- **Proactive**: Initiate communication
+- **Discovery-aware**: Find and connect to appropriate services
+- **Request-driven**: Send requests and wait for responses
+- **Orchestrating**: Can coordinate multiple service calls
+
+### Example: Client Agent
+
+```ruby
+class WeatherClientAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :client,  # This makes it a client agent
+      capabilities: ['weather_requester', 'data_aggregator']
+    }
+  end
+
+  def get_weather_report(locations)
+    # Find weather service agents
+    weather_agents = discover_agents(['weather'])
+    
+    if weather_agents.empty?
+      logger.warn "No weather agents available"
+      return nil
+    end
+
+    weather_agent = weather_agents.first
+    reports = []
+
+    locations.each do |location|
+      request = { location: location }
+      response = send_request(weather_agent[:name], request)
+      reports << response if response
+    end
+
+    reports
+  end
+end
+```
+
+### When to Use Client Agents
+
+- **Aggregators**: Combine data from multiple sources
+- **Workflows**: Multi-step business processes
+- **User Interfaces**: Frontend applications
+- **Schedulers**: Time-based or event-driven tasks
+
+## Hybrid Agents
+
+Hybrid agents can **both send and receive requests**. They're the most flexible but also the most complex.
+
+### Characteristics
+
+- **Bidirectional**: Can act as both client and server
+- **Mediating**: Often serve as intermediaries or proxies
+- **Stateful**: May maintain state across interactions
+- **Complex**: Handle multiple communication patterns
+
+### Example: Hybrid Agent
+
+```ruby
+class WeatherProxyAgent < Agent99::Base
+  def initialize
+    super
+    @cache = {}  # Simple caching
+    @stats = { requests: 0, cache_hits: 0 }
+  end
+
+  def info
+    {
+      name: self.class.to_s,
+      type: :hybrid,  # This makes it a hybrid agent
+      capabilities: ['weather_proxy', 'caching', 'analytics']
+    }
+  end
+
+  # Server behavior: respond to weather requests
+  def process_request(payload)
+    location = payload.dig(:location)
+    @stats[:requests] += 1
+
+    # Check cache first
+    if @cache[location] && fresh_enough?(@cache[location])
+      @stats[:cache_hits] += 1
+      logger.info "Cache hit for #{location}"
+      send_response(@cache[location][:data])
+      return
+    end
+
+    # Cache miss - get from weather service
+    weather_data = fetch_weather_data(location)
+    
+    if weather_data
+      @cache[location] = {
+        data: weather_data,
+        timestamp: Time.now
+      }
+      send_response(weather_data)
+    else
+      send_error("Weather data unavailable for #{location}")
+    end
+  end
+
+  # Client behavior: request from actual weather service
+  private def fetch_weather_data(location)
+    weather_agents = discover_agents(['weather'])
+    return nil if weather_agents.empty?
+
+    weather_agent = weather_agents.first
+    request = { location: location }
+    send_request(weather_agent[:name], request)
+  end
+
+  private def fresh_enough?(cache_entry)
+    Time.now - cache_entry[:timestamp] < 300  # 5 minutes
+  end
+
+  # Additional hybrid behavior: provide statistics
+  def get_statistics
+    {
+      total_requests: @stats[:requests],
+      cache_hits: @stats[:cache_hits],
+      cache_hit_rate: @stats[:requests] > 0 ? @stats[:cache_hits].to_f / @stats[:requests] : 0
+    }
+  end
+end
+```
+
+### When to Use Hybrid Agents
+
+- **Proxies**: Caching, load balancing, protocol translation
+- **Middleware**: Authentication, logging, monitoring
+- **State Managers**: Session management, workflow coordination
+- **Aggregators**: Collect, process, and redistribute data
+
+## Agent Type Comparison
+
+| Feature | Server | Client | Hybrid |
+|---------|--------|--------|---------|
+| **Receives Requests** | ✅ | ❌ | ✅ |
+| **Sends Requests** | ❌ | ✅ | ✅ |
+| **Complexity** | Low | Medium | High |
+| **Statefulness** | Usually stateless | Can be stateful | Often stateful |
+| **Use Cases** | Services, APIs | UIs, Schedulers | Proxies, Middleware |
+
+## Communication Patterns
+
+### Request-Response (Server/Client)
+
+![Request-Response Pattern](../assets/images/request-response-sequence.svg)
+
+### Proxy Pattern (Hybrid)
+
+![Proxy Pattern](../assets/images/proxy-pattern-sequence.svg)
+
+## Best Practices
+
+### Server Agents
+
+1. **Keep them focused**: One capability per agent
+2. **Make them stateless**: Each request independent
+3. **Validate inputs**: Use schemas for safety
+4. **Handle errors gracefully**: Always respond, even on error
+
+### Client Agents
+
+1. **Handle service unavailability**: Graceful degradation
+2. **Use timeouts**: Don't wait forever
+3. **Implement retries**: With exponential backoff
+4. **Cache discoveries**: Don't rediscover every time
+
+### Hybrid Agents
+
+1. **Separate concerns**: Clear distinction between client/server logic
+2. **Manage state carefully**: Consider thread safety
+3. **Monitor performance**: Track both directions
+4. **Document behavior**: Complex interactions need clear docs
+
+## Choosing the Right Type
+
+Ask yourself:
+
+- **Do I need to respond to requests?** → Server or Hybrid
+- **Do I need to make requests?** → Client or Hybrid  
+- **Do I need both?** → Hybrid
+- **Is simplicity important?** → Avoid Hybrid if possible
+- **Is this a leaf service?** → Probably Server
+- **Is this an orchestrator?** → Probably Client
+- **Is this middleware?** → Probably Hybrid
+
+## Next Steps
+
+- **[Agent Lifecycle](agent-lifecycle.md)** - How agents start, run, and stop
+- **[Architecture Overview](architecture.md)** - How agents fit into the bigger picture
+- **[Custom Agent Implementation](../agent-development/custom-agent-implementation.md)** - Build your own agents

data/docs/{architecture.md → core-concepts/architecture.md}

@@ -10,9 +10,9 @@ Agent99 is a Ruby-based framework designed for building and managing software ag
 
 ### System Components Diagram
 
-![High Level Architecture](diagrams/high_level_architecture.png)
+![Agent99 Architecture](../assets/images/agent99-architecture.svg)
 
-The diagram above (generated from `diagrams/high_level_architecture.dot`) illustrates the key components and their interactions:
+The diagram above illustrates the key components and their interactions:
 
 - **Agents**: Come in three types:
    - Client Agents: Only make requests
@@ -72,6 +72,6 @@ The framework supports three primary message types:
 ## 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
+- [API Reference](../api-reference/agent99-base.md) for method specifications
+- [Agent Lifecycle](agent-lifecycle.md) for lifecycle management
+- [Agent Discovery](../framework-components/agent-discovery.md) for discovery mechanisms

data/docs/core-concepts/what-is-an-agent.md

@@ -0,0 +1,293 @@
+# What is an Agent?
+
+An agent is a self-contained piece of code designed to perform a specific function or service. Unlike general-purpose classes or modules, agents can be autonomous entities that focus on doing one thing well. They embody the Single Responsibility Principle (SRP) by design.
+
+I will be using the Ruby programming language and the agent99 gem specifically to illustrate aspects of what I think good software agents should look like.  I choose Ruby because:
+
+- Ruby allows developers to create elegant and expressive AI applications.
+- It promotes paradigm shifts, challenging the Python status quo in AI development.
+- Developers who value clarity can find their niche in Ruby's design.
+- Ruby's metaprogramming capabilities pave the way for creative AI solutions.
+- Greater integration of Ruby-based frameworks makes them viable choices in the AI landscape.
+- Ruby's object-oriented style leads to more modular and testable code.
+- Ruby inspires a community that often prefers its syntax over Python's.
+
+## Getting Started with Agent99
+
+The `agent99` is a Ruby gem that serves as a framework for developing and managing software agents, allowing for the execution and communication of these agents in a distributed environment. It implements a reference protocol that supports agent registration, discovery, and messaging through a centralized registry and a messaging system like AMQP or NATS. Each agent, derived from the `Agent99::Base` class, is designed to perform specific tasks as defined by its capabilities, adhering to the Single Responsibility Principle (SRP) for enhanced maintainability and testability. The framework facilitates modular agent interactions, enabling developers to build innovative applications while taking advantage of Ruby’s expressive syntax and metaprogramming features. The library emphasizes best practices in software design, including error handling and lifecycle management for robust agent operations.
+
+To install the Agent99 gem, simply run:
+
+```bash
+gem install agent99
+```
+
+The [documentation](https://github.com/MadBomber/agent99/blob/main/docs/README.md) provides a comprehensive overview of the framework, but here, we will explore definitions of software agents and the Single Responsibility Principle (SRP), along with how Agent99 distinguishes itself in agent management and description.
+
+## What Is a Reference Implementation?
+
+The Agent99 gem implements a protocol in Ruby that can be replicated in other programming languages. This interoperability allows software agents, given they support the Agent99 protocol, to mix and match regardless of the language they were built in.
+
+## Understanding Software Agents and the Single Responsibility Principle
+
+Software agents and the Single Responsibility Principle (SRP) are crucial in contemporary software development. They decompose complex systems into manageable, autonomous components, while SRP promotes the creation of maintainable, testable, and adaptable systems. Utilizing both can boost code quality and nurture agility in development teams, particularly in AI, automation, and microservices contexts.
+
+## What Are Software Agents?
+
+In simple terms, a software agent is a designated piece of code that performs a single function effectively. Within the Agent99 framework, agents are instances of subclasses derived from the **Agent99::Base** class. These instances can be running in their own separate process or groups of instances of different Agent99 instances can run within separate Threads in a single process.
+
+Here's a simple example of an Agent99 agent class running in an independent process:
+
+```ruby
+# File: example_agent.rb
+
+require 'agent99'
+
+class ExampleAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     %w[ rubber_stamp yes_man example ],
+      # request_schema:   {}, # ExampleRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end  
+
+  def receive_request
+    logger.info "Example agent received request: #{payload}"
+    send_response(status: 'success')
+  end
+end
+
+ExampleAgent.new.run
+```
+
+```base
+ruby example_agent.rb
+```
+
+Each agent subclass is responsible for specific methods that define its unique capabilities and how it handles requests.  The `info` method provides a comprehensive information packet about the agent. It returns a hash containing key details that are crucial for agent registration and discovery within the system.  The **:capabilities** entry in the `info` packet in an Array of Strings - synonyms - for the thing that the agent does.
+
+For a server type agent, the only methods that are required to be defined, as in the ExampleAgent class above, are its **info** and its **receive_request** methods. Everything else from initialization, registration, message dispatching, and graceful shutdown are handled by the default methods within the **Agent99::Base** class.
+
+More complex agents will require methods like **receive_response** and **receive_control** and potentially custom implementations of **init**, **initialize**, or **fini** may be necessary for managing state or resources.
+
+> **RoadMap:** Currently, the Agent99 implementation defines the **capabilities** value as an `Array(String)`, with plans to enhance this functionality into descriptive unstructured text akin to defining tools for functional callbacks in LLM processing using semantic search.
+
+## The Single Responsibility Principle (SRP)
+
+The Single Responsibility Principle, part of the SOLID principles of object-oriented design, asserts that a class or module should have only one reason to change. This means it should fulfill a single job or responsibility effectively.
+
+### Why SRP Matters
+
+1. **Maintainability:** Code is easier to read and modify, leading to more maintainable systems.
+2. **Testability:** Isolated responsibilities facilitate independent unit testing.
+3. **Flexibility:** Minimal impact on other parts of the system when modifying one responsibility, reducing the risk of bugs.
+
+### Applying SRP in Software Development
+
+Implementing SRP involves:
+
+- **Identifying Responsibilities:** Break down functionalities into specific tasks; each class or module should focus on a particular duty.
+- **Modular Design:** Create a loosely coupled system to enhance separation of concerns.
+- **Utilizing Design Patterns:** Harness design patterns like Observer, Strategy, and Factory to ensure clear interfaces and responsibilities.
+
+## Alignment of Agents and SRP
+
+The notion of software agents naturally corresponds with the SRP. Each agent can be a distinct class or module that encapsulates a specific functionality. For instance:
+
+- An order processing agent focuses solely on order management.
+- A notification agent manages the sending of alerts or messages without getting involved in order processing logic.
+
+Designing agents with SRP in mind fosters modularity and reusability, allowing changes to one agent without affecting others and supporting more robust architecture.
+
+## Agent99 as a Reference Framework
+
+In its current iteration, the Agent99 Framework does not differ conceptually from other microservice architecture implementations. It enables centralized registration where agents list their capabilities for other agents or applications to discover. Agent communications occur via a distributed messaging system. The agent99 Ruby gem currently uses AMQP (via the Bunny gem and the RabbitMQ broker) and the NATS-server.
+
+### Agent Structure
+
+Agents in Agent99 inherit from **Agent99::Base**, which offers core functionality through crucial modules:
+
+- **HeaderManagement:** Handles message header processing.
+- **AgentDiscovery:** Facilitates capability advertisement and discovery.
+- **ControlActions:** Manages control messages.
+- **AgentLifecycle:** Oversees agent startup and shutdown functionality.
+- **MessageProcessing:** Manages message dispatch and handling.
+
+Every agent must define its type (server, client, or hybrid) and capabilities. The framework supports three message types: requests, responses, and control messages.
+
+```ruby
+class Agent99::Base
+  include Agent99::HeaderManagement
+  include Agent99::AgentDiscovery
+  include Agent99::ControlActions
+  include Agent99::AgentLifecycle
+  include Agent99::MessageProcessing
+
+  MESSAGE_TYPES = %w[request response control]
+
+  attr_reader :id, :capabilities, :name, :payload, :header, :logger, :queue
+  attr_accessor :registry_client, :message_client
+
+  ###################################################
+  private
+
+  def handle_error(message, error)
+    logger.error "#{message}: #{error.message}"
+    logger.debug error.backtrace.join("\n")
+  end
+
+  # the final rescue block
+  rescue StandardError => e
+    handle_error("Unhandled error in Agent99::Base", e)
+    exit(2)
+end
+```
+
+### Centralized Registry
+
+The registry service tracks agent availability and capabilities through a **RegistryClient**. A web-based application serves as the central registry, with a Sinatra implementation found in the `examples/registry.rb` file. Its primary function is to maintain a data store of registered agents.
+
+It supports three core operations:
+
+#### 1. Register
+
+![Central Registry Process](../assets/images/agent-registry-process.svg)
+
+Agents register by providing their information (e.g., name and capabilities) to the registry service. Here's how registration works in practice:
+
+```ruby
+class WeatherAgent < Agent99::Base
+  TYPE = :server
+
+  def capabilities
+    %w[get_temperature get_forecast]
+  end
+
+  def receive_request(message)
+    case message.payload[:action]
+    when 'get_temperature'
+      send_response({ temperature: 72, unit: 'F' })
+    when 'get_forecast'
+      send_response({ forecast: 'Sunny with a chance of rain' })
+    end
+  end
+end
+
+# Start the agent
+WeatherAgent.new.run
+```
+
+Upon successful registration, agents receive a universally unique ID (UUID) that identifies them in the system. The registration process is handled automatically by the Agent99 framework when you call `run`.
+
+#### 2. Discover
+
+Agents can query the registry to discover capabilities. The discovery operation retrieves information about agents offering specific capabilities via an HTTP GET request.
+
+#### 3. Withdraw
+
+When an agent needs to exit the system, it withdraws its registration using its UUID, removing it from the available agents list through an HTTP DELETE request.
+
+### Messaging Network
+
+The Ruby implementation of Agent99 currently focuses on AMQP messaging systems. Messages are formatted as JSON structures that adhere to defined schemas, allowing the **MessageClient** to validate messages effortlessly.
+
+Messages are validated against defined schemas, and invalid messages return to the sender without invoking agent-specific processes.
+
+Message types within the framework include:
+
+#### Request Messages
+
+These messages are validated against an agent-defined schema and include:
+
+- A header with routing information.
+- Agent-specific elements with their types and examples.
+
+Requests are handled by the `receive_request` handler in target agents.
+
+Here's an example of a request message schema using the [SimpleJsonSchemaBuilder gem](https://github.com/mooktakim/simple_json_schema_builder)
+
+```ruby
+# examples/maxwell_request.rb
+
+require 'agent99/header_schema'
+
+class MaxwellRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+
+    string :greeting, required: false, examples: ["Hello"]
+    string :name,     required: true,  examples: ["World"]
+  end
+end
+```
+
+This schema defines a `MaxwellRequest` with a header (using the `Agent99::HeaderSchema`), an optional greeting, and a required name. A valid JSON message conforming to this schema might look like:
+
+```json
+{
+  "header": {
+    "from_uuid": "123e4567-e89b-12d3-a456-426614174000",
+    "to_uuid": "987e6543-e21b-12d3-a456-426614174000",
+    "message_id": "msg-001",
+    "correlation_id": "corr-001",
+    "timestamp": "2023-04-01T12:00:00Z"
+  },
+  "greeting": "Hello",
+  "name": "Agent99"
+}
+```
+
+Using such schemas ensures that messages are well-structured and contain all necessary information before being processed by agents.
+
+Here is how the **MaxwellAgent** associates itself with its specific request schema:
+
+```ruby
+# examples/maxwell_agent86.rb
+
+require 'agent99'
+require_relative 'maxwell_request'
+
+class MaxwellAgent86 < Agent99::Base
+  def info
+    {
+      # ...
+      request_schema: MaxwellRequest.schema,
+      # ...
+    }
+  end
+```
+
+When an agent subclass defines a **:request_schema** in its `info`, the message processing of the **Agent99::Base** validates all incoming requests against the schema. If there are errors, those errors are returned to the sender without presenting the request message to the agent's custom **receive_request** method.
+
+#### Response Messages
+
+Responses are routed back to the requesting agent and include:
+
+- The original message header in reverse.
+- The response payload.
+- Status information.
+
+Responses are processed by the `receive_response` method.
+
+#### Control Messages
+
+Control messages manage agent lifecycles and configurations and include commands such as:
+
+- **shutdown:** Stop the agent.
+- **pause/resume:** Temporarily suspend or resume operations.
+- **update_config:** Modify agent configurations.
+- **status:** Query agent state.
+- **response:** Handle control operation results.
+
+Messages are queued with a 60-second TTL (Time To Live) to prevent buildup from inactive agents.
+
+## Additional Resources
+
+For further exploration, check out the documentation of the current Ruby implementation at [GitHub](https://github.com/MadBomber/agent99).
+
+Contributions to this initial Ruby reference implementation are welcome! It would be exciting to see additional language implementations.