agentic 0.1.0 → 0.2.0

data/lib/agentic/extension/protocol_handler.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Extension
+    # The ProtocolHandler standardizes connections to external systems through consistent
+    # interface definitions. It enables integration with various APIs, data sources,
+    # and services while providing a uniform access pattern regardless of the underlying
+    # protocol or system specifics.
+    class ProtocolHandler
+      # Initialize a new ProtocolHandler
+      #
+      # @param [Hash] options Configuration options
+      # @option options [Logger] :logger Custom logger instance
+      # @option options [Hash] :default_headers Default headers for all protocol requests
+      def initialize(options = {})
+        @logger = options[:logger] || Agentic.logger
+        @default_headers = options[:default_headers] || {}
+        @protocols = {}
+      end
+
+      # Register a protocol implementation
+      #
+      # @param [Symbol] protocol_name The name of the protocol (e.g., :http, :websocket, :grpc)
+      # @param [Object] implementation The protocol implementation
+      # @param [Hash] config Protocol-specific configuration
+      # @return [Boolean] True if registration was successful
+      def register_protocol(protocol_name, implementation, config = {})
+        if !valid_protocol?(implementation)
+          @logger.error("Protocol implementation for '#{protocol_name}' is invalid")
+          return false
+        end
+
+        @protocols[protocol_name] = {
+          implementation: implementation,
+          config: config
+        }
+
+        @logger.info("Protocol '#{protocol_name}' registered successfully")
+        true
+      end
+
+      # Send a request using a registered protocol
+      #
+      # @param [Symbol] protocol_name The protocol to use
+      # @param [String] endpoint The endpoint to send the request to
+      # @param [Hash] options Request options including :method, :headers, :body, etc.
+      # @return [Hash, nil] The response or nil if the protocol is not registered
+      def send_request(protocol_name, endpoint, options = {})
+        unless @protocols.key?(protocol_name)
+          @logger.error("Protocol '#{protocol_name}' is not registered")
+          return nil
+        end
+
+        protocol = @protocols[protocol_name]
+        options[:headers] = @default_headers.merge(options[:headers] || {})
+
+        begin
+          response = protocol[:implementation].send_request(endpoint, options.merge(protocol[:config]))
+          @logger.debug("Request sent using '#{protocol_name}' protocol to '#{endpoint}'")
+          response
+        rescue => e
+          @logger.error("Failed to send request using '#{protocol_name}' protocol: #{e.message}")
+          nil
+        end
+      end
+
+      # Get protocol configuration
+      #
+      # @param [Symbol] protocol_name The protocol to get configuration for
+      # @return [Hash, nil] The protocol configuration or nil if not registered
+      def protocol_config(protocol_name)
+        return nil unless @protocols.key?(protocol_name)
+
+        @protocols[protocol_name][:config]
+      end
+
+      # Update protocol configuration
+      #
+      # @param [Symbol] protocol_name The protocol to update
+      # @param [Hash] config The new configuration to merge
+      # @return [Boolean] True if update was successful
+      def update_protocol_config(protocol_name, config)
+        return false unless @protocols.key?(protocol_name)
+
+        @protocols[protocol_name][:config].merge!(config)
+        true
+      end
+
+      # Check if a protocol is registered
+      #
+      # @param [Symbol] protocol_name The protocol to check
+      # @return [Boolean] True if the protocol is registered
+      def protocol_registered?(protocol_name)
+        @protocols.key?(protocol_name)
+      end
+
+      # List all registered protocols
+      #
+      # @return [Array<Symbol>] List of registered protocol names
+      def list_protocols
+        @protocols.keys
+      end
+
+      private
+
+      # Check if a protocol implementation is valid
+      #
+      # @param [Object] implementation The implementation to validate
+      # @return [Boolean] True if the implementation is valid
+      def valid_protocol?(implementation)
+        # Check if implementation has required methods
+        implementation.respond_to?(:send_request)
+      end
+    end
+  end
+end

data/lib/agentic/extension.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "extension/domain_adapter"
+require_relative "extension/protocol_handler"
+require_relative "extension/plugin_manager"
+
+module Agentic
+  # The Extension module provides extensibility points for the Agentic framework.
+  # It includes three main components:
+  #
+  # 1. DomainAdapter - Adapts the framework for specific domains (e.g., healthcare, finance)
+  # 2. ProtocolHandler - Standardizes connections to external systems
+  # 3. PluginManager - Coordinates third-party extension loading and registration
+  #
+  # These components allow users to customize and extend Agentic's capabilities
+  # while maintaining a consistent interface.
+  module Extension
+    class << self
+      # Get or create a plugin manager instance
+      #
+      # @param [Hash] options Configuration options
+      # @return [PluginManager] The plugin manager instance
+      def plugin_manager(options = {})
+        @plugin_manager ||= PluginManager.new(options)
+      end
+
+      # Get or create a protocol handler instance
+      #
+      # @param [Hash] options Configuration options
+      # @return [ProtocolHandler] The protocol handler instance
+      def protocol_handler(options = {})
+        @protocol_handler ||= ProtocolHandler.new(options)
+      end
+
+      # Create a domain adapter for a specific domain
+      #
+      # @param [String] domain The domain identifier
+      # @param [Hash] options Configuration options
+      # @return [DomainAdapter] A new domain adapter instance
+      def domain_adapter(domain, options = {})
+        DomainAdapter.new(domain, options)
+      end
+    end
+  end
+end

data/lib/agentic/factory_methods.rb

@@ -21,7 +21,15 @@ module Agentic
 
       def configure(agent)
         configurable_attributes.each do |attr|
-          agent.public_send(:"#{attr}=", nil) unless agent.public_send(attr)
+          unless agent.public_send(attr)
+            default_value = case attr
+            when :tools
+              Set.new
+            when :capabilities
+              {}
+            end
+            agent.public_send(:"#{attr}=", default_value)
+          end
         end
       end
 

data/lib/agentic/generation_stats.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Value object representing statistics for an LLM generation
+  class GenerationStats
+    # @return [String] The ID of the generation
+    attr_reader :id
+
+    # @return [Integer] The number of prompt tokens
+    attr_reader :prompt_tokens
+
+    # @return [Integer] The number of completion tokens
+    attr_reader :completion_tokens
+
+    # @return [Integer] The total number of tokens
+    attr_reader :total_tokens
+
+    # @return [Hash] The raw statistics from the API
+    attr_reader :raw_stats
+
+    # Initializes a new generation statistics object
+    # @param id [String] The ID of the generation
+    # @param prompt_tokens [Integer] The number of prompt tokens
+    # @param completion_tokens [Integer] The number of completion tokens
+    # @param total_tokens [Integer] The total number of tokens
+    # @param raw_stats [Hash] The raw statistics from the API
+    def initialize(id:, prompt_tokens:, completion_tokens:, total_tokens:, raw_stats: {})
+      @id = id
+      @prompt_tokens = prompt_tokens
+      @completion_tokens = completion_tokens
+      @total_tokens = total_tokens
+      @raw_stats = raw_stats
+    end
+
+    # Returns a hash representation of the generation statistics
+    # @return [Hash] The generation statistics as a hash
+    def to_h
+      {
+        id: @id,
+        prompt_tokens: @prompt_tokens,
+        completion_tokens: @completion_tokens,
+        total_tokens: @total_tokens
+      }
+    end
+
+    # Creates a GenerationStats object from an API response
+    # @param response [Hash] The API response
+    # @return [GenerationStats] A new generation statistics object
+    def self.from_response(response)
+      usage = response&.dig("usage") || {}
+
+      new(
+        id: response&.dig("id") || "",
+        prompt_tokens: usage["prompt_tokens"] || 0,
+        completion_tokens: usage["completion_tokens"] || 0,
+        total_tokens: usage["total_tokens"] || 0,
+        raw_stats: response || {}
+      )
+    end
+  end
+end

data/lib/agentic/learning/README.md

@@ -0,0 +1,84 @@
+# Learning System Components
+
+The Learning System in Agentic provides capabilities for capturing and analyzing execution data, identifying patterns, and optimizing strategies based on historical performance.
+
+## Overview
+
+The Learning System consists of three main components:
+
+1. **ExecutionHistoryStore**: Captures and stores task and plan execution data.
+2. **PatternRecognizer**: Analyzes execution history to identify patterns and optimization opportunities.
+3. **StrategyOptimizer**: Uses insights from pattern analysis to optimize prompts, parameters, and task sequences.
+
+## Usage
+
+```ruby
+# Initialize components
+history_store = Agentic::Learning::ExecutionHistoryStore.new
+recognizer = Agentic::Learning::PatternRecognizer.new(history_store: history_store)
+optimizer = Agentic::Learning::StrategyOptimizer.new(
+  pattern_recognizer: recognizer,
+  history_store: history_store,
+  llm_client: llm_client # Optional
+)
+
+# Record execution data
+history_store.record_execution(
+  task_id: "task-123",
+  agent_type: "research_agent",
+  duration_ms: 1500,
+  success: true,
+  metrics: { tokens_used: 2000 }
+)
+
+# Analyze patterns
+patterns = recognizer.analyze_agent_performance("research_agent")
+
+# Get optimization recommendations
+recommendations = recognizer.recommend_optimizations("research_agent")
+
+# Optimize a prompt template
+improved_prompt = optimizer.optimize_prompt_template(
+  original_template: "Please research the topic: {topic}",
+  agent_type: "research_agent"
+)
+
+# Optimize LLM parameters
+improved_params = optimizer.optimize_llm_parameters(
+  original_params: { temperature: 0.7, max_tokens: 2000 },
+  agent_type: "research_agent"
+)
+
+# Generate a performance report
+report = optimizer.generate_performance_report("research_agent")
+```
+
+## Factory Method
+
+The Learning module provides a factory method to create all components at once:
+
+```ruby
+learning_system = Agentic::Learning.create(
+  storage_path: "/path/to/history",
+  llm_client: llm_client,
+  auto_optimize: false
+)
+
+# Access individual components
+history_store = learning_system[:history_store]
+recognizer = learning_system[:pattern_recognizer]
+optimizer = learning_system[:strategy_optimizer]
+```
+
+## Integration with PlanOrchestrator
+
+The Learning System can be integrated with the PlanOrchestrator to automatically record execution data:
+
+```ruby
+orchestrator = Agentic::PlanOrchestrator.new
+learning_system = Agentic::Learning.create
+
+Agentic::Learning.register_with_orchestrator(orchestrator, learning_system)
+```
+
+This will register event handlers to automatically record task and plan executions.