agent99 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 827e521c4a6580cfe954cf07cf04f1a822c00b9ed6eebf75598d925aeb555626
+  data.tar.gz: 1b3e9b499610b9b3853757432fd4e3e39acab8fb70e29feb94eae1d22f6097aa
+SHA512:
+  metadata.gz: ce549f64fb88cd2f152e7af27b9724dbfedfda0f6255033ea1773dda7eaf89dd71a6b622667d023b3093ae1eca72ae3a55e7bd6b1f538e3035fe889ab52ac7c4
+  data.tar.gz: 959b0c9c342738bb9ee75f2dd82a4caaa825a13656f6d12dba2a11434857c08f11d746c1754f03ce1902f9e4ced1f3b7e1067ab1cdbe39c054250b23592ae94f

data/.envrc

@@ -0,0 +1,3 @@
+# ai_agent/.envrc
+
+export RR=`pwd`

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-28
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# Agent99 Framework (AFW)
+
+**Under Development**  Initial release has no AI components - its just a generic client-server / request-response micro-services system using a peer-to-peer messaging broker and a centralized agent registry.
+
+Agent99 is a Ruby-based framework for building and managing AI agents in a distributed system. It provides a robust foundation for creating intelligent agents that can communicate, discover each other, and perform various tasks.
+
+## Features
+
+- Agent Lifecycle Management: Easy setup and teardown of agents
+- Message Processing: Handle requests, responses, and control messages
+- Agent Discovery: Find other agents based on capabilities
+- Flexible Communication: Support for both AMQP and NATS messaging systems
+- Registry Integration: Register and discover agents through a central registry
+- Error Handling and Logging: Built-in error management and logging capabilities
+- Control Actions: Pause, resume, update configuration, and request status of agents
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'agent99'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install agent99
+```
+
+## Usage
+
+Here's a basic example of how to create an AI agent:
+
+```ruby
+require 'agent99'
+
+class MyAgentRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+
+    # Define your agents parameters ....
+    string :greeting, required: false,  examples: ["Hello"]
+    string :name,     required: true,   examples: ["World"]
+  end
+end
+
+class MyAgent < Agent99::Base
+  REQUEST_SCHEMA  = MyAgentRequest.schema
+
+  def capabilities
+    ['text_processing', 'sentiment_analysis']
+    # TODO: make up mind on keyword or unstructured text
+  end
+
+  def receive_request
+    # Handle the validated incoming requests
+    response = { result: "Processed request" }
+
+    # Not every request needs a response
+    send_response(response)
+  end
+
+  def receive_response
+    # You sent a request to another agent
+    # now handle the response.
+  end
+end
+
+agent = MyAgent.new
+agent.run
+```
+
+## Configuration
+
+The framework can be configured through environment variables:
+
+- `REGISTRY_BASE_URL`: URL of the agent registry service (default: 'http://localhost:4567')  See the default registry service in the examples folder.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/agent99.
+
+## Short-term Roadmap
+
+- In the example registry, replace the Array(Hash) datastore with sqlite3 with a vector table to support discovery using semantic search.
+- Treat the agent like a Tool w/r/t RAG for prompts.
+- Add AgentRequest schema to agent's info in the registry.
+- Add AgentResponse schema to define the `result` element in the response JSON payload
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/docs/todo.md

@@ -0,0 +1,66 @@
+# Documentation
+
+TODO: Lets get some more detailed documentation underway that can be linked to from the main README.md file.
+
+Here are some key areas that should be covered in comprehensive documentation files:
+
+1. Architecture Overview:
+   - Explain the overall structure of the AiAgent framework
+   - Describe the roles of different components (Base, MessageClient, RegistryClient, etc.)
+   - Illustrate how agents communicate and interact within the system
+
+2. Agent Lifecycle:
+   - Detail the process of creating, initializing, running, and shutting down an agent
+   - Explain the registration and withdrawal process with the registry service
+
+3. Message Processing:
+   - Describe the different types of messages (request, response, control)
+   - Explain how messages are routed and processed
+   - Detail the schema validation process for incoming messages
+
+4. Agent Discovery:
+   - Explain how agents can discover other agents based on capabilities
+   - Describe the process of querying the registry for available agents
+
+5. Control Actions:
+   - List and explain all available control actions (shutdown, pause, resume, etc.)
+   - Describe how to implement custom control actions
+
+6. Configuration:
+   - Detail all configuration options available for agents
+   - Explain how to use environment variables for configuration
+
+7. Error Handling and Logging:
+   - Describe the error handling mechanisms in place
+   - Explain how to configure and use the logging system effectively
+
+8. Messaging Systems:
+   - Provide details on both AMQP and NATS messaging systems
+   - Explain how to switch between different messaging backends
+
+9. Custom Agent Implementation:
+   - Provide a step-by-step guide on creating a custom agent
+   - Explain how to define capabilities, handle requests, and send responses
+
+10. Schema Definition:
+    - Explain how to define and use request and response schemas
+    - Provide examples of complex schema definitions
+
+11. Performance Considerations:
+    - Discuss any performance optimizations in the framework
+    - Provide guidelines for writing efficient agents
+
+12. Security:
+    - Explain any security measures in place (if any)
+    - Provide best practices for securing agent communications
+
+13. Extending the Framework:
+    - Describe how to add new features or modify existing functionality
+    - Explain the plugin system (if one exists)
+
+14. Troubleshooting:
+    - Provide a list of common issues and their solutions
+    - Explain how to debug agents effectively
+
+15. API Reference:
+    - Provide a comprehensive API reference for all public methods and classes

data/examples/README.md

@@ -0,0 +1,79 @@
+# Agent99 Framework Examples
+
+- TODO
+    - Review and edit
+    - Add instructions for brew install rabbitmq nats-server boxes
+    - review example agents to see code can be tightened
+
+This folder contains example implementations using the Agent99 framework. The framework provides a foundation for building AI agents that can communicate with each other through a message-based system.
+
+## Files
+
+### 1. hello_world.rb
+
+This file demonstrates a basic AI agent implementation using the Agent99 framework.
+
+- Class: `HelloWorld < Agent99::Base`
+- Functionality: Responds to "hello world" requests
+- Key methods:
+  - `receive_request`: Handles incoming requests
+  - `validate_request`: Validates the request against a schema
+  - `process`: Generates the response
+
+### 2. hello_world_client.rb
+
+This file shows how to create a client that interacts with the HelloWorld agent.
+
+- Class: `HelloWorldClient < Agent99::Base`
+- Functionality: Sends a request to a HelloWorld agent and processes the response
+- Key methods:
+  - `init`: Initiates the request sending process
+  - `send_request`: Builds and sends the request
+  - `receive_response`: Handles the response from the HelloWorld agent
+
+### 3. hello_world_request.rb
+
+This file defines the schema for HelloWorld requests using SimpleJsonSchemaBuilder.
+
+- Class: `HelloWorldRequest < SimpleJsonSchemaBuilder::Base`
+- Defines the structure of a valid HelloWorld request
+
+### 4. registry.rb
+
+This file implements a simple registry service for AI agents using Sinatra.
+
+- Functionality: Allows agents to register, discover other agents, and withdraw from the registry
+- Endpoints:
+  - GET `/healthcheck`: Returns the number of registered agents
+  - POST `/register`: Registers a new agent
+  - GET `/discover`: Discovers agents by capability
+  - DELETE `/withdraw/:uuid`: Withdraws an agent from the registry
+  - GET `/`: Lists all registered agents
+
+## Usage
+
+1. Start the registry service:
+   ```
+   ruby registry.rb
+   ```
+
+2. Run the HelloWorld agent:
+   ```
+   ruby hello_world.rb
+   ```
+
+3. Run the HelloWorld client:
+   ```
+   ruby hello_world_client.rb
+   ```
+
+## Dependencies
+
+- Ruby 3.3+
+- Gems: json, json_schema, sinatra, bunny, securerandom
+
+## Notes
+
+- The framework uses modern Ruby 3.3 syntax, especially for hashes and method signatures with named parameters.
+- The examples demonstrate basic usage of the Agent99 framework, including request/response handling, validation, and agent discovery.
+- The registry service uses an in-memory store (AGENT_REGISTRY) for simplicity, but it's recommended to use a more robust solution like SQLite for production use.

data/examples/hello_world.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# examples/hello_world.rb
+
+require 'json'
+require 'json_schema'
+
+require_relative '../lib/agent99'
+require_relative 'hello_world_request'
+
+class HelloWorld < Agent99::Base
+  REQUEST_SCHEMA  = HelloWorldRequest.schema
+  # RESPONSE_SCHEMA = Agent99::RESPONSE.schema
+  # ERROR_SCHEMA    = Agent99::ERROR.schema
+
+  # The request is in @payload
+  def receive_request
+    send_response( validate_request || process )
+  end
+
+  # This method validates the incoming request and returns any errors found
+  # or nil if there are no errors.
+  # It allows for returning an array of errors.
+  #
+  # TODO: consider a 4th message type of error
+  #
+  def validate_request
+    responses = []
+
+    # Check if the ID matches
+    unless id == to_uuid
+      logger.error <<~ERROR
+        #{name} received someone else's request
+        id: #{id}  timestamp: #{timestamp}
+        to_uuid:   #{to_uuid}
+        from_uuid: #{from_uuid}
+        event_uuid:#{event_uuid}
+      ERROR
+      responses << {
+        error: "Incorrect message queue for header",
+        details: {
+          id:     id,
+          header: header
+        }
+      }
+    end
+
+    # Validate the incoming request body against the schema
+    validation_errors = validate_schema
+    unless validation_errors.empty?
+      logger.error "Validation errors: #{validation_errors}"
+      responses << {
+        error:    "Invalid request", 
+        details:  validation_errors
+      }
+    end
+
+    responses.empty? ? nil : responses
+  end
+
+  # Returns the response value
+  # All response message have the same schema in that
+  # they have a header (all messages have headers) and
+  # a result element that is a String.  Could it be
+  # a JSON string, sure but then we would need a 
+  # RESPONSE_SCHEMA constant for the class.
+  def process
+    {
+      result: get(:greeting) + ' ' + get(:name)
+    }
+  end
+
+
+  # As a server type, HelloWorld should never receive
+  # a response message.
+  def receive_response(response)
+    loger.warn("Unexpected response type message: response.inspect")
+  end
+
+  private
+
+  # NOTE: what I'm thinking about here is similar to the
+  #       prompt tool (aka function) callback facility
+  #       where descriptive text is used to describe
+  #       what the tool does.
+  #
+  # TODO: scale this idea back to just keywords
+  #       until the registry program gets more
+  #       stuff added to its discovery process.
+  #
+  def capabilities
+    %w[ greeter hello_world hello-world hello]   
+  end
+end
+
+# Example usage
+agent = HelloWorld.new
+agent.run # Starts listening for messages

data/examples/hello_world_client.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# examples/hello_world_client.rb
+
+require 'json'
+require 'json_schema'
+require 'securerandom'
+require_relative '../lib/agent99'
+
+class HelloWorldClient < Agent99::Base
+  def init
+    send_request
+  end
+
+  def send_request
+    to_uuid = discover_agent(capability: 'greeter', how_many: 1).first[:uuid]
+
+    request = build_request(
+                to_uuid:,
+                greeting: 'Hey',
+                name:     'MadBomber'
+              )
+
+    result = @message_client.publish(request)
+    logger.info "Sent request: #{request.inspect}; status? #{result.inspect}"
+  end
+
+  def build_request(
+                to_uuid:,
+                greeting: 'Hello',
+                name:     'World'
+              )
+
+    {
+      header: {
+        type:       'request',
+        from_uuid:  @id,
+        to_uuid:,
+        event_uuid: SecureRandom.uuid,
+        timestamp:  Agent99::Timestamp.new.to_i
+      },
+      greeting:,
+      name:
+    }
+  end
+
+
+  def receive_response
+    logger.info "Received response: #{payload.inspect}"
+    result = payload[:result]
+
+    puts
+    puts `echo "#{result}" | boxes -d info`
+    puts
+
+    exit(0)
+  end
+
+  #####################################################
+  private
+
+  def capabilities
+    ['hello_world_client']
+  end
+end
+
+
+# Example usage
+client = HelloWorldClient.new
+client.run
+

data/examples/hello_world_request.rb

@@ -0,0 +1,12 @@
+# examples/hello_world_request.rb
+
+require_relative '../lib/agent99/header_schema'
+
+class HelloWorldRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+
+    string :greeting, required: false,  examples: ["Hello"]
+    string :name,     required: true,   examples: ["World"]
+  end
+end

data/examples/registry.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# examples/registry.rb
+
+require 'debug_me'
+include DebugMe
+
+require 'sinatra'
+require 'json'
+require 'bunny'
+require 'securerandom'
+
+# In-memory registry to store agent capabilities
+# Array(Hash)
+# TODO: change this data store to a sqlite database
+#       maybe with a vector search capability.
+#
+AGENT_REGISTRY = []
+
+# Health check endpoint
+get '/healthcheck' do
+  content_type :json
+  { agent_count: AGENT_REGISTRY.size }.to_json
+end
+
+# Endpoint to register an agent
+post '/register' do
+  request.body.rewind
+  agent_info = JSON.parse(request.body.read, symbolize_names: true)
+
+  agent_name = agent_info[:name]
+  capabilities = agent_info[:capabilities]
+
+  agent_uuid = SecureRandom.uuid
+
+  AGENT_REGISTRY << agent_info.merge({uuid: agent_uuid})
+
+  status 201
+  content_type :json
+  { uuid: agent_uuid }.to_json
+end
+
+# Endpoint to discover agents by capability
+# TODO: This is a simple keyword matcher.  Looking
+# =>    for a semantic match process.
+get '/discover' do
+  capability = params['capability']
+
+  matching_agents = AGENT_REGISTRY.select do |agent|
+    agent[:capabilities].include?(capability)
+  end
+
+  content_type :json
+  matching_agents.to_json 
+end
+
+# Withdraw an agent from the registry
+delete '/withdraw/:uuid' do
+  uuid      = params['uuid']
+  how_many  = AGENT_REGISTRY.size
+
+  AGENT_REGISTRY.delete_if { |agent_info| agent_info[:uuid] == uuid }
+
+  if AGENT_REGISTRY.size == how_many
+    status 404 # Not Found
+    content_type :json
+    { error: "Agent with UUID #{uuid} not found." }.to_json
+  else
+    status 204 # No Content
+  end
+end
+
+# Display all registered agents
+get '/' do
+  content_type :json
+  AGENT_REGISTRY.to_json
+end
+
+# Start the Sinatra server
+if __FILE__ == $PROGRAM_NAME
+  Sinatra::Application.run!
+end

data/examples/start_agents.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Start the registry server
+echo "Starting registry server..."
+# Assuming the registry server is a separate process, replace with actual command
+# e.g., ruby registry_server.rb &
+# Replace 'registry_server_command' with the actual command to start your registry server
+# Example: ruby registry_server.rb &
+./registry.rb &
+
+# Start the HelloWorld agent
+echo "Starting HelloWorld agent..."
+./hello_world.rb &
+
+# Start the HelloWorldClient agent
+echo "Starting HelloWorldClient agent..."
+./hello_world_client.rb &
+
+# Wait for all background processes to finish
+wait

data/lib/agent99/.irbrc

@@ -0,0 +1,5 @@
+module Agent99
+  # empty namespace
+end
+
+require_relative 'timestamp'

data/lib/agent99/agent_discovery.rb

@@ -0,0 +1,35 @@
+# lib/agent99/agent_discovery.rb
+
+module Agent99::AgentDiscovery
+
+  # Returns the agent's capabilities (to be overridden by subclasses).
+  #
+  # @return [Array<String>] The agent's capabilities
+  #
+  def capabilities
+    []
+  end
+
+  
+  ################################################
+  private
+  
+  # Discovers other agents with a specific capability.
+  #
+  # @param capability [String] The capability to search for
+  # @param how_many [Integer] The number of agents to return
+  # @param all [Boolean] Whether to return all matching agents
+  # @return [Array<Hash>] The discovered agents
+  # @raise [RuntimeError] If no agents are found
+  #
+  def discover_agent(capability:, how_many: 1, all: false)
+    result = @registry_client.discover(capability:)
+
+    if result.empty?
+      logger.error "No agents found for capability: #{capability}"
+      raise "No agents available"
+    end
+
+    all ? result : result.sample(how_many)
+  end
+end