agent99 0.0.3 → 0.0.5

data/lib/agent99/tcp_message_client.rb

@@ -0,0 +1,183 @@
+# lib/agent99/tcp_message_client.rb
+#
+# NOTE: This is an early attempt at a true
+#       peer-to-peer messaging platform.  Its not
+#       not ready for prime time.
+
+require 'socket'
+require 'json'
+require 'logger'
+
+class Agent99::TcpMessageClient
+  attr_accessor :agents
+
+  def initialize(
+      agents: {},
+      logger: Logger.new($stdout)
+    )
+    @agents             = agents
+    @logger             = logger
+    @server_socket      = nil
+    @client_connections = {}
+    @handlers           = {}
+    @running            = false
+  end
+
+  def listen_for_messages(queue, request_handler:, response_handler:, control_handler:)
+    @handlers = {
+      request:  request_handler,
+      response: response_handler,
+      control:  control_handler
+    }
+    
+    start_server(queue[:port])
+  end
+
+  def publish(message)
+    target = message.dig(:header, :to_uuid)
+    return unless target
+
+    agent_info = agents(target)
+    return unless agent_info
+
+    socket = connect_to_agent(agent_info[:ip], agent_info[:port])
+    return unless socket
+
+    begin
+      socket.puts(message.to_json)
+      true
+    
+    rescue StandardError => e
+      @logger.error("Failed to send message: #{e.message}")
+      false
+    
+    ensure
+      socket.close unless socket.closed?
+    end
+  end
+
+  def stop
+    @running = false
+    @server_socket&.close
+    @client_connections.each_value(&:close)
+    @client_connections.clear
+  end
+
+  private
+
+  def start_server(port)
+    @server_socket  = TCPServer.new(port)
+    @running        = true
+
+    Thread.new do
+      while @running
+        begin
+          client = @server_socket.accept
+          handle_client(client)
+        rescue StandardError => e
+          @logger.error("Server error: #{e.message}")
+        end
+      end
+    end
+  end
+
+  def handle_client(client)
+    Thread.new do
+      while @running
+        begin
+          message = client.gets
+          break if message.nil?
+
+          parsed_message = JSON.parse(message, symbolize_names: true)
+          route_message(parsed_message)
+        
+        rescue JSON::ParserError => e
+          @logger.error("Invalid JSON received: #{e.message}")
+        
+        rescue StandardError => e
+          @logger.error("Error handling client: #{e.message}")
+          break
+        end
+      end
+      
+      client.close unless client.closed?
+    end
+  end
+
+  def route_message(message)
+    type    = message.dig(:header, :type)&.to_sym
+    handler = @handlers[type]
+    
+    if handler
+      handler.call(message)
+    else
+      @logger.warn("No handler for message type: #{type}")
+    end
+  end
+
+  def connect_to_agent(ip, port)
+    TCPSocket.new(ip, port)
+  
+  rescue StandardError => e
+    @logger.error("Failed to connect to #{ip}:#{port}: #{e.message}")
+    nil
+  end
+end
+
+
+__END__
+
+Based on the provided code for the `Agent99::TcpMessageClient` class, here's an analysis of your questions:
+
+1. Does this class queue up JSON messages while a previous message is being processed?
+
+No, this class does not explicitly queue up JSON messages while a previous message is being processed. The class processes messages as they are received, without maintaining an internal queue. Each incoming message is handled in its own thread (see the `handle_client` method), which allows for concurrent processing of messages from multiple clients.
+
+2. Does it present a complete JSON message at once or does it only provide part of one?
+
+The class attempts to present complete JSON messages at once. Here's why:
+
+- In the `handle_client` method, messages are read using `client.gets`, which typically reads a full line of input (up to a newline character).
+- The received message is then parsed as JSON using `JSON.parse(message, symbolize_names: true)`.
+- If the parsing is successful, the entire parsed message is passed to the `route_message` method.
+
+However, there are a few potential issues to consider:
+
+- If a JSON message spans multiple lines, `client.gets` might not capture the entire message in one read.
+- There's no explicit handling for partial messages or message boundaries.
+- Large messages might be split across multiple TCP packets, and the current implementation doesn't account for reassembling these.
+
+To ensure complete message handling, you might want to consider implementing a more robust message framing protocol, such as using message length prefixes or delimiter-based framing.
+
+For example, you could modify the `handle_client` method to use a delimiter-based approach:
+
+```ruby
+def handle_client(client)
+  Thread.new do
+    buffer = ""
+    while @running
+      begin
+        chunk = client.readpartial(1024)
+        buffer += chunk
+        while (message_end = buffer.index("\n"))
+          message      = buffer[0...message_end]
+          buffer       = buffer[(message_end + 1)..]
+          parsed_message = JSON.parse(message, symbolize_names: true)
+          route_message(parsed_message)
+        end
+      rescue EOFError
+        break
+      rescue JSON::ParserError => e
+        @logger.error("Invalid JSON received: #{e.message}")
+      rescue StandardError => e
+        @logger.error("Error handling client: #{e.message}")
+        break
+      end
+    end
+    client.close unless client.closed?
+  end
+end
+```
+
+This modification would allow for handling of messages that might be split across multiple reads, ensuring that complete JSON messages are processed.
+

data/lib/agent99/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Agent99
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 
   def self.version  = VERSION
 end

data/lib/agent99.rb

@@ -4,7 +4,7 @@ require 'debug_me'
 include DebugMe
 
 require 'json'
-require 'json_schema'
+require 'simple_json_schema_builder'
 require 'securerandom'
 
 module Agent99; end  # Establish a namespace

data/mkdocs.yml

@@ -0,0 +1,195 @@
+# MkDocs Configuration for Agent99 Documentation
+site_name: Agent99 Framework Documentation
+site_description: Comprehensive documentation for the Agent99 Ruby gem - A framework for building distributed AI agents
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/agent99
+copyright: Copyright © 2015-2025 Dewayne VanHoozer
+
+# Repository information
+repo_url: https://github.com/MadBomber/agent99
+repo_name: MadBomber/agent99
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme - Default to light mode
+  palette:
+    # Palette toggle for light mode (default)
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Theme features
+  features:
+    # Navigation
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+
+    # Table of contents
+    - toc.follow
+
+    # Search
+    - search.suggest
+    - search.highlight
+    - search.share
+
+    # Header
+    - header.autohide
+
+    # Content
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+# Extensions
+markdown_extensions:
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+      title: On this page
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: agent99
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS and JavaScript
+extra_css:
+  - assets/css/custom.css
+
+extra_javascript:
+  # - assets/js/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/agemt99
+      name: AIA on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/agemt99
+      name: AIA on RubyGems
+
+  # version:
+  #   provider: mike
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Overview: getting-started/overview.md
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+      - Basic Example: getting-started/basic-example.md
+  - Core Concepts:
+      - What is an Agent?: core-concepts/what-is-an-agent.md
+      - Architecture Overview: core-concepts/architecture.md
+      - Agent Lifecycle: core-concepts/agent-lifecycle.md
+      - Agent Types: core-concepts/agent-types.md
+  - Framework Components:
+      - Agent Registry: framework-components/agent-registry.md
+      - Agent Discovery: framework-components/agent-discovery.md
+      - Messaging System: framework-components/messaging-system.md
+      - Message Processing: framework-components/message-processing.md
+  - Agent Development:
+      - Custom Agent Implementation: agent-development/custom-agent-implementation.md
+      - Schema Definition: agent-development/schema-definition.md
+      - Request & Response Handling: agent-development/request-response-handling.md
+      - Error Handling: agent-development/error-handling-and-logging.md
+  - Advanced Topics:
+      - Control Actions: advanced-topics/control-actions.md
+      - Advanced Features: advanced-topics/advanced-features.md
+      - Multi-Agent Processing: advanced-topics/multi-agent-processing.md
+      - A2A Protocol: advanced-topics/a2a-protocol.md
+      - Model Context Protocol: advanced-topics/model-context-protocol.md
+      - Extending the Framework: advanced-topics/extending-the-framework.md
+  - API Reference:
+      - Overview: api-reference/overview.md
+      - Agent99::Base: api-reference/agent99-base.md
+      - Registry Client: api-reference/registry-client.md
+      - Message Clients: api-reference/message-clients.md
+      - Schemas: api-reference/schemas.md
+  - Operations:
+      - Configuration: operations/configuration.md
+      - Security: operations/security.md
+      - Performance Considerations: operations/performance-considerations.md
+      - Troubleshooting: operations/troubleshooting.md
+      - Breaking Changes: operations/breaking-changes.md
+  - Examples:
+      - Basic Examples: examples/basic-examples.md
+      - Advanced Examples: examples/advanced-examples.md
+  - AI Concepts:
+      - HTM: AI/htm.md
+      - Notes on HTM Implementation: AI/notes_on_htm_implementation.md
+  - Internal Framework:
+      - Central Registry: agent99_framework/central_registry.md
+      - Message Client: agent99_framework/message_client.md
+      - Registry Client: agent99_framework/registry_client.md