agent99 0.0.4 → 0.0.5

data/docs/getting-started/installation.md

@@ -0,0 +1,160 @@
+# Installation
+
+This guide will help you install Agent99 and set up your development environment.
+
+## Prerequisites
+
+Agent99 requires **Ruby 3.3.0** or higher.
+
+Check your Ruby version:
+
+```bash
+ruby --version
+```
+
+If you need to install or upgrade Ruby, we recommend using [rbenv](https://github.com/rbenv/rbenv) or [RVM](https://rvm.io/).
+
+## Install the Gem
+
+### From RubyGems
+
+```bash
+gem install agent99
+```
+
+### From Bundler
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'agent99'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### From Source
+
+Clone the repository and install:
+
+```bash
+git clone https://github.com/MadBomber/agent99.git
+cd agent99
+bundle install
+```
+
+## Dependencies
+
+Agent99 automatically installs the following dependencies:
+
+- **bunny** - AMQP messaging client
+- **nats-pure** - NATS messaging client  
+- **simple_json_schema_builder** - JSON schema validation
+- **sinatra** - For the registry service
+
+## Message Broker Setup
+
+Agent99 supports multiple messaging backends. Choose one:
+
+### Option 1: NATS (Recommended for Development)
+
+Install NATS server:
+
+```bash
+# macOS
+brew install nats-server
+
+# Ubuntu/Debian
+apt-get install nats-server
+
+# Or download from https://nats.io/download/
+```
+
+Start NATS server:
+
+```bash
+nats-server
+```
+
+### Option 2: RabbitMQ (AMQP)
+
+Install RabbitMQ:
+
+```bash
+# macOS
+brew install rabbitmq
+
+# Ubuntu/Debian  
+apt-get install rabbitmq-server
+
+# Or download from https://www.rabbitmq.com/download.html
+```
+
+Start RabbitMQ:
+
+```bash
+# macOS
+brew services start rabbitmq
+
+# Ubuntu/Debian
+systemctl start rabbitmq-server
+```
+
+## Registry Service
+
+Agent99 uses a central registry for agent discovery. You can use the example registry or create your own.
+
+Start the example registry:
+
+```bash
+# From the agent99 source directory
+ruby examples/registry.rb
+```
+
+The registry will start on http://localhost:4567 by default.
+
+## Environment Variables
+
+Configure Agent99 using environment variables:
+
+```bash
+# Registry URL (default: http://localhost:4567)
+export AGENT99_REGISTRY_URL=http://localhost:4567
+
+# Message broker settings (see messaging documentation)
+export RABBITMQ_URL=amqp://localhost
+export NATS_URL=nats://localhost:4222
+```
+
+## Verification
+
+Verify your installation by running a simple test:
+
+```ruby
+require 'agent99'
+puts "Agent99 version: #{Agent99.version}"
+```
+
+## Development Dependencies
+
+If you're contributing to Agent99, install development dependencies:
+
+```bash
+bundle install --with development
+```
+
+This includes:
+- **amazing_print** - Pretty printing
+- **debug_me** - Debugging utilities
+- **hashdiff** - Hash comparison
+- **mocha** - Testing framework
+- **tocer** - Documentation generation
+
+## Next Steps
+
+- [Quick Start](quick-start.md) - Build your first agent
+- [Basic Example](basic-example.md) - Detailed walkthrough
+- [Configuration](../operations/configuration.md) - Advanced setup options

data/docs/getting-started/overview.md

@@ -0,0 +1,64 @@
+# Agent99 Framework Overview
+
+Agent99 is a Ruby framework for building distributed AI agents with peer-to-peer messaging capabilities. It provides a robust foundation for creating intelligent agents that can communicate, discover each other, and perform various tasks in a microservices architecture.
+
+## Current Status
+
+**Version**: 0.0.4 (Under Development)
+
+!!! warning "Development Status"
+    Agent99 is currently under active development. The initial release has no AI components - it's a generic client-server / request-response microservices system using peer-to-peer messaging brokers and a centralized agent registry.
+
+## Key Features
+
+- **Agent Types**: Support for Server (responds to requests), Client (makes requests), and Hybrid (both) agents
+- **Messaging**: Multiple messaging backends including AMQP (via Bunny) and NATS
+- **Agent Discovery**: Central registry for finding agents by capabilities
+- **Lifecycle Management**: Complete agent registration, message processing, and control actions
+- **Dynamic Loading**: Runtime agent deployment via AgentWatcher
+- **Multi-threading**: Run multiple agents in the same process with thread isolation
+
+## Architecture Highlights
+
+- **Modular Design**: Built with mixins for HeaderManagement, AgentDiscovery, ControlActions, AgentLifecycle, and MessageProcessing
+- **Multiple Message Clients**: AMQP, NATS, and TCP implementations
+- **HTTP Registry**: Simple HTTP-based service for agent discovery (default: localhost:4567)
+- **Schema Validation**: JSON schema validation for requests and responses
+
+## Future Vision
+
+The framework is designed with AI integration in mind, referencing protocols like:
+- **Agent2Agent (A2A)**: Now under the Linux Foundation
+- **Model Context Protocol**: For AI model integration
+
+## Quick Example
+
+```ruby
+require 'agent99'
+
+class GreeterAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :server,
+      capabilities: ['greeter', 'hello_world']
+    }
+  end
+
+  def process_request(payload)
+    name = payload.dig(:name)
+    response = { result: "Hello, #{name}!" }
+    send_response(response)
+  end
+end
+
+# Create and run the agent
+agent = GreeterAgent.new
+agent.run
+```
+
+## Next Steps
+
+- [Installation](installation.md) - Get Agent99 installed
+- [Quick Start](quick-start.md) - Build your first agent
+- [Basic Example](basic-example.md) - Detailed walkthrough

data/docs/getting-started/quick-start.md

@@ -0,0 +1,179 @@
+# Quick Start
+
+Get up and running with Agent99 in just a few minutes! This guide assumes you have Ruby 3.3.0+ installed.
+
+## Step 1: Install Agent99
+
+```bash
+gem install agent99
+```
+
+## Step 2: Start a Message Broker
+
+Agent99 needs a message broker for agent communication. Choose one:
+
+=== "NATS (Recommended)"
+    ```bash
+    # Install NATS server
+    brew install nats-server  # macOS
+    # OR download from https://nats.io/download/
+
+    # Start NATS
+    nats-server
+    ```
+
+=== "RabbitMQ"
+    ```bash
+    # Install RabbitMQ
+    brew install rabbitmq  # macOS
+
+    # Start RabbitMQ
+    brew services start rabbitmq
+    ```
+
+## Step 3: Start the Registry
+
+The registry helps agents discover each other:
+
+```bash
+# Clone the repository for examples
+git clone https://github.com/MadBomber/agent99.git
+cd agent99
+
+# Start the registry
+ruby examples/registry.rb
+```
+
+## Step 4: Create Your First Agent
+
+Create a file called `my_first_agent.rb`:
+
+```ruby
+require 'agent99'
+
+class MyFirstAgent < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :server,
+      capabilities: ['greeting', 'hello']
+    }
+  end
+
+  def process_request(payload)
+    name = payload.dig(:name) || "World"
+    logger.info "Processing greeting request for: #{name}"
+
+    response = {
+      message: "Hello, #{name}! Welcome to Agent99!",
+      timestamp: Time.now.iso8601
+    }
+
+    send_response(response)
+  end
+end
+
+# Run the agent
+if __FILE__ == $0
+  puts "🤖 Starting My First Agent..."
+  agent = MyFirstAgent.new
+  agent.run
+end
+```
+
+## Step 5: Run Your Agent
+
+```bash
+ruby my_first_agent.rb
+```
+
+You should see output like:
+```
+🤖 Starting My First Agent...
+INFO -- Agent MyFirstAgent registered successfully
+INFO -- Agent listening for messages...
+```
+
+## Step 6: Test Your Agent
+
+Create a simple client to test your agent (`test_client.rb`):
+
+```ruby
+require 'agent99'
+
+class TestClient < Agent99::Base
+  def info
+    {
+      name: self.class.to_s,
+      type: :client,
+      capabilities: ['testing']
+    }
+  end
+
+  def test_greeting
+    # Discover greeting agents
+    agents = discover_agents(['greeting'])
+
+    if agents.any?
+      target_agent = agents.first
+      puts "📡 Found agent: #{target_agent[:name]}"
+
+      # Send a request
+      request = { name: "Agent99 User" }
+      response = send_request(target_agent[:name], request)
+
+      puts "✅ Response: #{response[:message]}"
+    else
+      puts "❌ No greeting agents found"
+    end
+  end
+end
+
+# Run the test
+if __FILE__ == $0
+  client = TestClient.new
+  client.test_greeting
+end
+```
+
+Run the test client:
+```bash
+ruby test_client.rb
+```
+
+Expected output:
+```
+📡 Found agent: MyFirstAgent
+✅ Response: Hello, Agent99 User! Welcome to Agent99!
+```
+
+## 🎉 Success!
+
+You've successfully:
+
+- ✅ Installed Agent99
+- ✅ Started a message broker and registry
+- ✅ Created and ran your first agent
+- ✅ Tested agent communication
+
+## What's Next?
+
+- **[Basic Example](basic-example.md)** - More detailed walkthrough
+- **[Core Concepts](../core-concepts/what-is-an-agent.md)** - Understand how agents work
+- **[Examples](../examples/basic-examples.md)** - More agent patterns
+- **[Agent Development](../agent-development/custom-agent-implementation.md)** - Build complex agents
+
+## Troubleshooting
+
+**Agent not starting?**
+- Make sure NATS or RabbitMQ is running
+- Check that Ruby 3.3.0+ is installed: `ruby --version`
+- Verify the registry is running on port 4567
+
+**Can't find agents?**
+- Ensure all components (registry, broker, agents) are running
+- Check that agents are registering: visit http://localhost:4567/agents
+
+**Need help?**
+- Check the [Troubleshooting Guide](../operations/troubleshooting.md)
+- Visit the [GitHub repository](https://github.com/MadBomber/agent99) for issues and discussions

data/docs/index.md

@@ -0,0 +1,97 @@
+# Agent99 Framework Documentation
+
+Welcome to the comprehensive documentation for Agent99 - a Ruby framework for building distributed AI agents with peer-to-peer messaging capabilities.
+
+## 🚀 Getting Started
+
+New to Agent99? Start here to get up and running quickly:
+
+- **[Overview](getting-started/overview.md)** - What is Agent99 and what can it do?
+- **[Installation](getting-started/installation.md)** - Get Agent99 installed and configured
+- **[Quick Start](getting-started/quick-start.md)** - Build your first agent in minutes  
+- **[Basic Example](getting-started/basic-example.md)** - Detailed walkthrough of a complete system
+
+## 🧠 Core Concepts
+
+Understand the fundamental concepts behind Agent99:
+
+- **[What is an Agent?](core-concepts/what-is-an-agent.md)** - Basic agent concepts and philosophy
+- **[Agent Types](core-concepts/agent-types.md)** - Server, Client, and Hybrid agents explained
+- **[Agent Lifecycle](core-concepts/agent-lifecycle.md)** - How agents start, run, and stop
+- **[Architecture Overview](core-concepts/architecture.md)** - System design and component interaction
+
+## 🔧 Framework Components
+
+Deep dive into the Agent99 system components:
+
+- **[Agent Registry](framework-components/agent-registry.md)** - Central agent discovery service
+- **[Agent Discovery](framework-components/agent-discovery.md)** - How agents find each other
+- **[Messaging System](framework-components/messaging-system.md)** - AMQP, NATS, and TCP messaging
+- **[Message Processing](framework-components/message-processing.md)** - Request/response handling
+
+## 💻 Agent Development
+
+Build your own agents with these guides:
+
+- **[Custom Agent Implementation](agent-development/custom-agent-implementation.md)** - Create custom agents
+- **[Schema Definition](agent-development/schema-definition.md)** - Request/response validation  
+- **[Request & Response Handling](agent-development/request-response-handling.md)** - Message processing patterns
+- **[Error Handling & Logging](agent-development/error-handling-and-logging.md)** - Robust error strategies
+
+## 🎯 Advanced Topics
+
+Advanced features and integration patterns:
+
+- **[Control Actions](advanced-topics/control-actions.md)** - Agent control and management
+- **[Advanced Features](advanced-topics/advanced-features.md)** - Dynamic loading and multi-agent processing
+- **[A2A Protocol](advanced-topics/a2a-protocol.md)** - Agent-to-Agent communication protocol  
+- **[Model Context Protocol](advanced-topics/model-context-protocol.md)** - AI model integration
+- **[Extending the Framework](advanced-topics/extending-the-framework.md)** - Custom modules and extensions
+
+## 📚 API Reference
+
+Detailed API documentation:
+
+- **[Agent99::Base](api-reference/agent99-base.md)** - Core agent class reference
+- **[Registry Client](api-reference/registry-client.md)** - Registry service API  
+- **[Message Clients](api-reference/message-clients.md)** - Messaging client APIs
+- **[Schemas](api-reference/schemas.md)** - Schema validation system
+
+## ⚙️ Operations
+
+Deploy and maintain Agent99 in production:
+
+- **[Configuration](operations/configuration.md)** - Environment and runtime configuration
+- **[Security](operations/security.md)** - Security best practices and implementation
+- **[Performance Considerations](operations/performance-considerations.md)** - Optimization and scaling
+- **[Troubleshooting](operations/troubleshooting.md)** - Common issues and solutions
+- **[Breaking Changes](operations/breaking-changes.md)** - Version upgrade guide
+
+## 💡 Examples
+
+Working examples and tutorials:
+
+- **[Basic Examples](examples/basic-examples.md)** - Simple agent patterns and use cases
+- **[Advanced Examples](examples/advanced-examples.md)** - Complex multi-agent scenarios
+
+## 🔄 Recent Updates
+
+### 2024-12-12 - Version 0.0.4 Release
+- Breaking changes in agent registration and discovery
+- Improved message processing performance
+- Enhanced error handling and logging
+
+### 2025-04-09 - A2A Protocol Integration
+Google announced its Agent-to-Agent public protocol called A2A. Agent99 is designed to integrate with this protocol. For additional information see [A2A Protocol Documentation](advanced-topics/a2a-protocol.md).
+
+## 🤝 Contributing
+
+Agent99 is an open-source project and welcomes contributions:
+
+- **GitHub Repository**: [https://github.com/MadBomber/agent99](https://github.com/MadBomber/agent99)
+- **RubyGems Package**: [https://rubygems.org/gems/agent99](https://rubygems.org/gems/agent99)
+- **Issue Tracker**: Report bugs and request features on GitHub
+
+---
+
+*Ready to build distributed agent systems? Start with the [Getting Started](getting-started/overview.md) guide!*

data/examples/DEMO.md

@@ -0,0 +1,148 @@
+# Agent99 Demo Runner
+
+This is a comprehensive demo script that allows you to easily run and explore Agent99 framework examples.
+
+## Quick Start
+
+```bash
+# List available demo scenarios
+./run_demo.rb --list
+
+# Run the basic demo (Maxwell Agent86 + Chief interaction)
+./run_demo.rb
+
+# Run with verbose output to see what's happening
+./run_demo.rb -v -s basic
+```
+
+## Features
+
+- 🏗️ **Automatic Infrastructure**: Starts registry service and RabbitMQ (if available)
+- 🎬 **Orchestrated Execution**: Manages multiple agents with proper timing
+- 🧹 **Clean Shutdown**: Handles Ctrl+C gracefully, cleaning up all processes
+- 📊 **Progress Feedback**: Shows what's happening and estimated duration
+- 🔍 **Dependency Checking**: Warns about missing optional dependencies
+- 🎯 **Multiple Scenarios**: Choose from different demo configurations
+
+## Available Scenarios
+
+### Basic (`-s basic`) - Default, ~10 seconds
+- **Maxwell Agent86**: Service agent that responds to "hello world" requests
+- **Chief Agent**: Client agent that discovers agents and sends requests
+- **Demonstrates**: Basic agent-to-agent communication, discovery, request/response
+
+### Control (`-s control`) - ~15 seconds  
+- **Maxwell Agent86**: Service agent
+- **Control Agent**: Hybrid agent that manages other agents using control messages
+- **Demonstrates**: Control message system, agent management, pause/resume functionality
+
+### Watcher (`-s watcher`) - ~20 seconds
+- **Agent Watcher**: Monitors directory for new agent files
+- **Dynamic Loading**: Automatically loads and starts new agents
+- **Demonstrates**: Runtime agent loading, file system monitoring
+
+### Security (`-s security`) - ~10 seconds ⚠️ Educational Only
+- **Maxwell Agent86**: Service agent  
+- **KAOS Spy**: Malicious agent that demonstrates security vulnerabilities
+- **Demonstrates**: Security considerations, agent registry vulnerabilities
+- **Warning**: This shows attack patterns for educational purposes
+
+### All (`-s all`) - ~60 seconds
+- Runs multiple scenarios in sequence (skips security for safety)
+- **Demonstrates**: Full framework capabilities
+
+## Command Line Options
+
+```bash
+./run_demo.rb [options]
+
+Options:
+    -s, --scenario SCENARIO    Demo scenario to run (basic, control, watcher, security, all)
+    -l, --list                 List available scenarios
+    -v, --verbose              Show detailed output from agents
+        --no-cleanup           Keep processes running (for debugging)
+    -h, --help                 Show help message
+
+Examples:
+    ./run_demo.rb                    # Run basic demo with default settings
+    ./run_demo.rb -s watcher -v      # Run watcher demo with verbose output
+    ./run_demo.rb --list             # List all available scenarios
+```
+
+## What You'll See
+
+The demo runner shows:
+
+1. **🔍 Dependency Check**: Verifies required files exist, warns about optional dependencies
+2. **🏗️ Infrastructure Startup**: Registry service and RabbitMQ (if available)  
+3. **🎬 Scenario Execution**: Agents starting, registering, communicating
+4. **📊 Progress Updates**: What's happening and time remaining
+5. **🧹 Clean Shutdown**: All processes terminated gracefully
+
+## Dependencies
+
+### Required (Bundled)
+- Ruby 3.0+
+- Agent99 framework (in parent directory)
+- Example agent files
+
+### Optional (Enhanced Experience)
+```bash
+# Message broker for production-like messaging
+brew install rabbitmq-server
+
+# Enhanced output formatting for Chief agent
+brew install boxes
+```
+
+**Note**: Demo works without optional dependencies using fallback implementations.
+
+## Troubleshooting
+
+### "Permission denied" error
+```bash
+chmod +x run_demo.rb
+```
+
+### "No agents available" error
+- Check that registry service started successfully
+- Try running with `-v` flag to see detailed logs
+- Ensure no other processes are using port 4567
+
+### RabbitMQ connection issues
+- RabbitMQ is optional - demo works without it
+- If installed but not starting: `brew services restart rabbitmq`
+- Demo uses fallback message client if RabbitMQ unavailable
+
+### Ctrl+C doesn't stop everything
+- Demo has signal handlers for graceful shutdown
+- If processes persist: `./run_demo.rb --no-cleanup` then manually kill
+- Check for zombie processes: `ps aux | grep ruby`
+
+## Architecture
+
+The demo runner:
+
+1. **Validates Environment**: Checks for required files and optional dependencies
+2. **Starts Infrastructure**: Registry service (port 4567) and RabbitMQ if available
+3. **Orchestrates Agents**: Starts agents in proper sequence with timing
+4. **Monitors Execution**: Tracks agent processes and handles timeouts
+5. **Cleanup**: Terminates all spawned processes on completion or interrupt
+
+## Extending
+
+To add new scenarios:
+
+1. Edit `SCENARIOS` hash in `run_demo.rb`
+2. Add agent files to `agents` array
+3. Specify duration and any special handling
+4. Update documentation
+
+Example:
+```ruby
+'my_scenario' => {
+  description: 'My custom agent demonstration',
+  agents: ['my_agent1.rb', 'my_agent2.rb'],
+  duration: 15
+}
+```