agentic 0.1.0 → 0.2.0

data/lib/agentic/learning.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "learning/execution_history_store"
+require_relative "learning/pattern_recognizer"
+require_relative "learning/strategy_optimizer"
+
+module Agentic
+  # The Learning module provides components for capturing execution history,
+  # recognizing patterns, and optimizing strategies based on feedback and metrics.
+  #
+  # @example Using the Learning System components
+  #   # 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
+  #   )
+  #
+  #   # 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")
+  #
+  #   # Optimize strategies
+  #   improved_prompt = optimizer.optimize_prompt_template(
+  #     original_template: "Please research the topic: {topic}",
+  #     agent_type: "research_agent"
+  #   )
+  module Learning
+    # Factory method to create a complete learning system
+    #
+    # @param options [Hash] Configuration options for all components
+    # @option options [Logger] :logger Custom logger (defaults to Agentic.logger)
+    # @option options [String] :storage_path Path for storing execution history
+    # @option options [Boolean] :auto_optimize Whether to auto-apply optimizations
+    # @option options [Symbol] :optimization_strategy Strategy (:conservative, :balanced, :aggressive)
+    # @option options [LlmClient] :llm_client Optional LLM client for optimizations
+    # @return [Hash] Hash containing all initialized learning system components
+    def self.create(options = {})
+      history_store = ExecutionHistoryStore.new(
+        logger: options[:logger],
+        storage_path: options[:storage_path],
+        anonymize: options.fetch(:anonymize, true)
+      )
+
+      pattern_recognizer = PatternRecognizer.new(
+        logger: options[:logger],
+        history_store: history_store,
+        min_sample_size: options[:min_sample_size] || 10
+      )
+
+      strategy_optimizer = StrategyOptimizer.new(
+        logger: options[:logger],
+        pattern_recognizer: pattern_recognizer,
+        history_store: history_store,
+        llm_client: options[:llm_client],
+        auto_apply_optimizations: options.fetch(:auto_optimize, false)
+      )
+
+      {
+        history_store: history_store,
+        pattern_recognizer: pattern_recognizer,
+        strategy_optimizer: strategy_optimizer
+      }
+    end
+
+    # Register a learning system with a plan orchestrator
+    #
+    # @param plan_orchestrator [PlanOrchestrator] The plan orchestrator to integrate with
+    # @param learning_system [Hash] The learning system components from Learning.create
+    # @return [Boolean] true if successfully registered
+    def self.register_with_orchestrator(plan_orchestrator, learning_system)
+      # Register execution history tracking
+      plan_orchestrator.on(:task_completed) do |task, result|
+        learning_system[:history_store].record_execution(
+          task_id: task.id,
+          plan_id: task.context[:plan_id],
+          agent_type: task.agent_spec&.type,
+          duration_ms: result.metrics[:duration_ms],
+          success: result.success?,
+          metrics: result.metrics,
+          context: {
+            task_description: task.description,
+            task_type: task.type,
+            input_size: task.input ? task.input.to_s.length : 0
+          }
+        )
+      end
+
+      plan_orchestrator.on(:plan_completed) do |plan, results|
+        # Record overall plan execution
+        task_durations = {}
+        task_dependencies = {}
+
+        results.each do |task_id, result|
+          task_durations[task_id] = result.metrics[:duration_ms] if result.metrics[:duration_ms]
+        end
+
+        # Extract dependencies from plan
+        plan.tasks.each do |task|
+          task_dependencies[task.id] = task.dependencies if task.dependencies&.any?
+        end
+
+        learning_system[:history_store].record_execution(
+          plan_id: plan.id,
+          success: results.values.all?(&:success?),
+          duration_ms: results.values.sum { |r| r.metrics[:duration_ms] || 0 },
+          metrics: {
+            total_tasks: results.size,
+            successful_tasks: results.values.count(&:success?),
+            failed_tasks: results.values.count { |r| !r.success? }
+          },
+          context: {
+            task_durations: task_durations,
+            task_dependencies: task_dependencies
+          }
+        )
+      end
+
+      true
+    end
+  end
+end

data/lib/agentic/llm_assisted_composition_strategy.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Agentic
+  # LLM-assisted strategy for agent composition
+  # Uses an LLM to analyze requirements and suggest capabilities
+  class LlmAssistedCompositionStrategy < AgentCompositionStrategy
+    # Initialize a new LLM-assisted composition strategy
+    # @param llm_config_or_client [LlmConfig, LlmClient, nil] The LLM configuration or client to use
+    def initialize(llm_config_or_client = nil)
+      if llm_config_or_client.is_a?(LlmClient)
+        @llm_client = llm_config_or_client
+      else
+        @llm_config = llm_config_or_client || LlmConfig.new
+      end
+    end
+
+    # Select capabilities based on requirements
+    # @param requirements [Hash] The capability requirements
+    # @param registry [AgentCapabilityRegistry] The capability registry
+    # @return [Array<Hash>] The selected capabilities
+    def select_capabilities(requirements, registry)
+      # Get all available capabilities from the registry
+      available_capabilities = registry.list
+
+      # Use existing client or create a new one
+      client = @llm_client || Agentic.client(@llm_config)
+
+      # Create a prompt for the LLM
+      prompt = build_llm_prompt(requirements, available_capabilities)
+
+      # Get LLM response
+      response = client.complete(
+        prompt: prompt,
+        response_format: {type: "json"}
+      )
+
+      # Parse the response
+      suggested_capabilities = parse_llm_response(response.to_s, registry)
+
+      # Fall back to default strategy if LLM suggestion fails
+      if suggested_capabilities.empty?
+        Agentic.logger.warn("LLM capability suggestion failed, falling back to default strategy")
+        return DefaultCompositionStrategy.new.select_capabilities(requirements, registry)
+      end
+
+      # Add dependencies
+      add_dependencies(suggested_capabilities, registry)
+    end
+
+    private
+
+    # Build a prompt for the LLM to suggest capabilities
+    # @param requirements [Hash] The capability requirements
+    # @param available_capabilities [Hash] The available capabilities in the registry
+    # @return [String] The prompt for the LLM
+    def build_llm_prompt(requirements, available_capabilities)
+      # Format the requirements
+      req_text = requirements.map do |name, info|
+        "- #{name} (importance: #{info[:importance]}, version: #{info[:version_constraint] || "any"})"
+      end.join("\n")
+
+      # Format the available capabilities
+      avail_text = available_capabilities.map do |name, info|
+        versions_text = info[:versions].join(", ")
+        "- #{name} (versions: #{versions_text}, latest: #{info[:latest]})"
+      end.join("\n")
+
+      <<~PROMPT
+        You are an AI assistant helping to select the most appropriate capabilities for an agent.
+
+        Given the following requirements and available capabilities, select the most appropriate
+        capabilities for the agent. Consider the importance of each requirement and ensure all
+        high-importance requirements are satisfied.
+
+        # Requirements:
+        #{req_text.empty? ? "No specific requirements provided." : req_text}
+
+        # Available Capabilities:
+        #{avail_text}
+
+        For each requirement, select the most appropriate capability and version.
+        Also consider dependencies between capabilities and ensure all necessary capabilities are included.
+
+        Provide your response in JSON format with this structure:
+        {
+          "selected_capabilities": [
+            {"name": "capability_name", "version": "version_string", "reason": "Reason for selection"},
+            ...
+          ],
+          "rationale": "Overall explanation of your selection logic"
+        }
+      PROMPT
+    end
+
+    # Parse the LLM response to get suggested capabilities
+    # @param response [String] The LLM response
+    # @param registry [AgentCapabilityRegistry] The capability registry
+    # @return [Array<Hash>] The selected capabilities
+    def parse_llm_response(response, registry)
+      # Extract JSON from the response
+      json_match = response.match(/\{.*"selected_capabilities".*\}/m)
+      return [] unless json_match
+
+      json_str = json_match[0]
+
+      # Parse the JSON response
+      json_response = JSON.parse(json_str, symbolize_names: true)
+
+      # Extract the selected capabilities
+      selected = json_response[:selected_capabilities] || []
+
+      # Log the rationale if provided
+      if json_response[:rationale]
+        Agentic.logger.info("LLM capability selection rationale: #{json_response[:rationale]}")
+      end
+
+      # Validate the selected capabilities
+      validated = []
+
+      selected.each do |cap|
+        name = cap[:name]
+        version = cap[:version]
+
+        # Log the reason if provided
+        if cap[:reason]
+          Agentic.logger.info("Selected #{name} v#{version}: #{cap[:reason]}")
+        end
+
+        # Check if the capability exists in the registry
+        capability = registry.get(name, version)
+
+        if capability
+          validated << {
+            name: capability.name,
+            version: capability.version
+          }
+        else
+          Agentic.logger.warn("LLM suggested non-existent capability: #{name} v#{version}")
+        end
+      end
+
+      validated
+    rescue => e
+      Agentic.logger.error("Failed to parse LLM response: #{e.message}")
+      []
+    end
+
+    # Add dependencies to the selected capabilities
+    # @param selected [Array<Hash>] The selected capabilities
+    # @param registry [AgentCapabilityRegistry] The capability registry
+    # @return [Array<Hash>] The selected capabilities with dependencies
+    def add_dependencies(selected, registry)
+      # Track dependencies to add
+      to_add = []
+
+      # Check each selected capability for dependencies
+      selected.each do |cap_info|
+        capability = registry.get(cap_info[:name], cap_info[:version])
+        next unless capability
+
+        # Check each dependency
+        capability.dependencies.each do |dep|
+          # Skip if we already selected this dependency
+          next if selected.any? { |sel| sel[:name] == dep[:name] } ||
+            to_add.any? { |sel| sel[:name] == dep[:name] }
+
+          # Find the dependency in the registry
+          dep_capability = registry.get(dep[:name], dep[:version])
+
+          # Skip if not found
+          next unless dep_capability
+
+          # Add to the list of dependencies to add
+          to_add << {
+            name: dep_capability.name,
+            version: dep_capability.version
+          }
+
+          Agentic.logger.info("Added dependency: #{dep_capability.name} v#{dep_capability.version}")
+        end
+      end
+
+      # Add the dependencies to the selected capabilities
+      selected.concat(to_add)
+      selected
+    end
+  end
+end

data/lib/agentic/llm_client.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require "openai"
+require "net/http"
+require_relative "llm_response"
+require_relative "errors/llm_error"
+require_relative "retry_handler"
+require_relative "retry_config"
 
 module Agentic
   # Generic wrapper for LLM API clients
@@ -8,19 +13,44 @@ module Agentic
     # @return [OpenAI::Client] The underlying LLM client instance
     attr_reader :client, :last_response
 
+    # @return [RetryHandler] The retry handler for transient errors
+    attr_reader :retry_handler
+
     # Initializes a new LlmClient
     # @param config [LlmConfig] The configuration for the LLM
-    def initialize(config)
-      @client = OpenAI::Client.new(access_token: Agentic.configuration.access_token)
+    # @param retry_config [RetryConfig, Hash] Configuration for the retry handler
+    def initialize(config, retry_config = {})
+      client_options = {access_token: Agentic.configuration.access_token}
+
+      # Add custom base URL if configured (for Ollama, etc.)
+      if Agentic.configuration.api_base_url
+        client_options[:uri_base] = Agentic.configuration.api_base_url
+      end
+
+      @client = OpenAI::Client.new(client_options)
       @config = config
       @last_response = nil
+
+      # Convert retry_config to RetryConfig if it's a hash
+      @retry_handler = if retry_config.is_a?(RetryConfig)
+        retry_config.to_handler
+      else
+        RetryHandler.new(**retry_config)
+      end
     end
 
     # Sends a completion request to the LLM
     # @param messages [Array<Hash>] The messages to send
-    # @return [Hash] The response from the LLM
-    def complete(messages, output_schema: nil)
-      parameters = {model: @config.model, messages: messages}
+    # @param output_schema [Agentic::StructuredOutputs::Schema, nil] Optional schema for structured output
+    # @param fail_on_error [Boolean] Whether to raise errors or return them as part of the response
+    # @param use_retries [Boolean] Whether to retry on transient errors
+    # @param options [Hash] Additional options to override the config
+    # @return [LlmResponse] The structured response from the LLM
+    def complete(messages, output_schema: nil, fail_on_error: false, use_retries: true, options: {})
+      # Start with base parameters from the config
+      parameters = @config.to_api_parameters({messages: messages})
+
+      # Add response format if schema is provided
       if output_schema
         parameters[:response_format] = {
           type: "json_schema",
@@ -28,32 +58,202 @@ module Agentic
         }
       end
 
+      # Override with any additional options
+      parameters.merge!(options)
+
+      execution_method = use_retries ? method(:with_retry) : method(:without_retry)
+      execution_method.call(messages, parameters, output_schema, fail_on_error)
+    end
+
+    # Executes the API call with retries for transient errors
+    # @param messages [Array<Hash>] The messages being sent
+    # @param parameters [Hash] The request parameters
+    # @param output_schema [Agentic::StructuredOutputs::Schema, nil] Optional schema for structured output
+    # @param fail_on_error [Boolean] Whether to raise errors or return them as part of the response
+    # @return [LlmResponse] The structured response from the LLM
+    def with_retry(messages, parameters, output_schema, fail_on_error)
+      retry_handler.with_retry do
+        without_retry(messages, parameters, output_schema, fail_on_error)
+      end
+    rescue Errors::LlmError => e
+      # If we get here, we've exhausted retries or hit a non-retryable error
+      Agentic.logger.error("Failed after retries: #{e.message}")
+      handle_error(e, fail_on_error)
+    end
+
+    # Executes the API call without retries
+    # @param messages [Array<Hash>] The messages being sent
+    # @param parameters [Hash] The request parameters
+    # @param output_schema [Agentic::StructuredOutputs::Schema, nil] Optional schema for structured output
+    # @param fail_on_error [Boolean] Whether to raise errors or return them as part of the response
+    # @return [LlmResponse] The structured response from the LLM
+    def without_retry(messages, parameters, output_schema, fail_on_error)
       @last_response = client.chat(parameters: parameters)
 
-      if output_schema
-        content = JSON.parse(@last_response.dig("choices", 0, "message", "content"))
+      # Check for API-level refusal
+      if (refusal = @last_response.dig("choices", 0, "message", "refusal"))
+        refusal_error = Errors::LlmRefusalError.new(
+          refusal,
+          response: @last_response,
+          context: {input_messages: extract_message_content(messages)}
+        )
+
+        Agentic.logger.warn("LLM refused the request: #{refusal} (Category: #{refusal_error.refusal_category})")
 
-        if (refusal = @last_response.dig("choices", 0, "message", "refusal"))
-          {refusal: refusal, content: nil}
+        if fail_on_error
+          raise refusal_error
         else
-          {content: content}
+          return LlmResponse.refusal(@last_response, refusal, refusal_error)
+        end
+      end
+
+      # Process the response based on whether we expect structured output
+      if output_schema
+        begin
+          content_text = @last_response.dig("choices", 0, "message", "content")
+          if content_text.nil? || content_text.empty?
+            error = Errors::LlmParseError.new("Empty content returned from LLM", response: @last_response)
+            Agentic.logger.error(error.message)
+            return handle_error(error, fail_on_error)
+          end
+
+          content = JSON.parse(content_text)
+          LlmResponse.success(@last_response, content)
+        rescue JSON::ParserError => e
+          error = Errors::LlmParseError.new(
+            "Failed to parse JSON response: #{e.message}",
+            parse_exception: e,
+            response: @last_response
+          )
+          Agentic.logger.error(error.message)
+          handle_error(error, fail_on_error)
         end
       else
-        @last_response.dig("choices", 0, "message", "content")
+        content = @last_response.dig("choices", 0, "message", "content")
+        LlmResponse.success(@last_response, content)
       end
+    rescue OpenAI::Error => e
+      error = map_openai_error(e)
+      Agentic.logger.error("OpenAI API error: #{error.message}")
+      handle_error(error, fail_on_error)
+    rescue Net::ReadTimeout, Net::OpenTimeout => e
+      error = Errors::LlmTimeoutError.new("Request to LLM timed out: #{e.message}", context: {timeout_type: e.class.name})
+      Agentic.logger.error(error.message)
+      handle_error(error, fail_on_error)
+    rescue JSON::ParserError => e
+      error = Errors::LlmParseError.new("Failed to parse LLM response: #{e.message}", parse_exception: e)
+      Agentic.logger.error(error.message)
+      handle_error(error, fail_on_error)
+    rescue => e
+      error = Errors::LlmError.new("Unexpected error in LLM request: #{e.message}", context: {error_class: e.class.name})
+      Agentic.logger.error("#{error.message}\n#{e.backtrace.join("\n")}")
+      handle_error(error, fail_on_error)
     end
 
     # Fetches available models from the LLM provider
-    # @return [Array<Hash>] The list of available models
-    def models
+    # @param fail_on_error [Boolean] Whether to raise errors or return nil on error
+    # @return [Array<Hash>, nil] The list of available models, or nil if an error occurred and fail_on_error is false
+    # @raise [Agentic::Errors::LlmError] If an error occurred and fail_on_error is true
+    def models(fail_on_error: false)
       client.models.list&.dig("data")
+    rescue OpenAI::Error => e
+      error = map_openai_error(e)
+      Agentic.logger.error("OpenAI API error when listing models: #{error.message}")
+      handle_error(error, fail_on_error)
+      nil
+    rescue => e
+      error = Errors::LlmError.new("Unexpected error listing models: #{e.message}")
+      Agentic.logger.error("#{error.message}\n#{e.backtrace.join("\n")}")
+      handle_error(error, fail_on_error)
+      nil
     end
 
     # Queries generation stats for a given generation ID
     # @param generation_id [String] The ID of the generation
-    # @return [Hash] The generation stats
-    def query_generation_stats(generation_id)
+    # @param fail_on_error [Boolean] Whether to raise errors or return nil on error
+    # @return [Hash, nil] The generation stats, or nil if an error occurred and fail_on_error is false
+    # @raise [Agentic::Errors::LlmError] If an error occurred and fail_on_error is true
+    def query_generation_stats(generation_id, fail_on_error: false)
       client.query_generation_stats(generation_id)
+    rescue OpenAI::Error => e
+      error = map_openai_error(e)
+      Agentic.logger.error("OpenAI API error when querying generation stats: #{error.message}")
+      handle_error(error, fail_on_error)
+      nil
+    rescue => e
+      error = Errors::LlmError.new("Unexpected error querying generation stats: #{e.message}")
+      Agentic.logger.error("#{error.message}\n#{e.backtrace.join("\n")}")
+      handle_error(error, fail_on_error)
+      nil
+    end
+
+    private
+
+    # Extracts content from messages for logging purposes
+    # @param messages [Array<Hash>] The messages
+    # @return [Array<String>] The extracted content
+    def extract_message_content(messages)
+      messages.map do |msg|
+        content = msg[:content] || msg["content"]
+        role = msg[:role] || msg["role"]
+        "#{role}: #{if content
+                      content[0..100] + ((content.length > 100) ? "..." : "")
+                    else
+                      "[no content]"
+                    end}"
+      end
+    end
+
+    # Maps OpenAI error types to our custom error classes
+    # @param error [OpenAI::Error] The original error from the OpenAI gem
+    # @return [Agentic::Errors::LlmError] A mapped error
+    def map_openai_error(error)
+      case error
+      when OpenAI::Timeout
+        Errors::LlmTimeoutError.new("OpenAI API request timed out: #{error.message}")
+      when OpenAI::RateLimitError
+        retry_after = error.response&.headers&.[]("retry-after")&.to_i
+        Errors::LlmRateLimitError.new(
+          "OpenAI API rate limit exceeded: #{error.message}",
+          retry_after: retry_after,
+          response: error.response&.to_h
+        )
+      when OpenAI::AuthenticationError
+        Errors::LlmAuthenticationError.new(
+          "OpenAI API authentication error: #{error.message}",
+          response: error.response&.to_h
+        )
+      when OpenAI::APIConnectionError
+        Errors::LlmNetworkError.new(
+          "OpenAI API connection error: #{error.message}",
+          network_exception: error
+        )
+      when OpenAI::InvalidRequestError
+        Errors::LlmInvalidRequestError.new(
+          "Invalid request to OpenAI API: #{error.message}",
+          response: error.response&.to_h
+        )
+      when OpenAI::APIError
+        Errors::LlmServerError.new(
+          "OpenAI API server error: #{error.message}",
+          response: error.response&.to_h
+        )
+      else
+        Errors::LlmError.new(
+          "Unexpected OpenAI API error: #{error.message}",
+          response: error.response&.to_h
+        )
+      end
+    end
+
+    # Handles an error based on whether to fail or return it in the response
+    # @param error [Agentic::Errors::LlmError] The error to handle
+    # @param fail_on_error [Boolean] Whether to raise the error
+    # @return [LlmResponse] An error response if fail_on_error is false
+    # @raise [Agentic::Errors::LlmError] If fail_on_error is true
+    def handle_error(error, fail_on_error)
+      raise error if fail_on_error
+      LlmResponse.error(error, @last_response)
     end
   end
 end

data/lib/agentic/llm_config.rb

@@ -1,11 +1,75 @@
 # frozen_string_literal: true
 
 module Agentic
+  # Configuration object for LLM API calls
   class LlmConfig
+    # @return [String] The model to use for LLM requests
     attr_accessor :model
 
-    def initialize(model: "gpt-4o-2024-08-06")
+    # @return [Integer] The maximum number of tokens to generate
+    attr_accessor :max_tokens
+
+    # @return [Float] The temperature parameter (controls randomness)
+    attr_accessor :temperature
+
+    # @return [Float] The top_p parameter (nucleus sampling)
+    attr_accessor :top_p
+
+    # @return [Integer] The frequency penalty
+    attr_accessor :frequency_penalty
+
+    # @return [Integer] The presence penalty
+    attr_accessor :presence_penalty
+
+    # @return [Hash] Additional options to pass to the API
+    attr_accessor :additional_options
+
+    # Initializes a new LLM configuration
+    # @param model [String] The model to use
+    # @param max_tokens [Integer, nil] The maximum number of tokens to generate
+    # @param temperature [Float] The temperature parameter (0.0-2.0)
+    # @param top_p [Float] The top_p parameter (0.0-1.0)
+    # @param frequency_penalty [Float] The frequency penalty (-2.0-2.0)
+    # @param presence_penalty [Float] The presence penalty (-2.0-2.0)
+    # @param additional_options [Hash] Additional options to pass to the API
+    def initialize(
+      model: "gpt-4o-2024-08-06",
+      max_tokens: nil,
+      temperature: 0.7,
+      top_p: 1.0,
+      frequency_penalty: 0.0,
+      presence_penalty: 0.0,
+      additional_options: {}
+    )
       @model = model
+      @max_tokens = max_tokens
+      @temperature = temperature
+      @top_p = top_p
+      @frequency_penalty = frequency_penalty
+      @presence_penalty = presence_penalty
+      @additional_options = additional_options
+    end
+
+    # Returns a hash of parameters for the API call
+    # @param base_params [Hash] Base parameters to include
+    # @return [Hash] Parameters for the API call
+    def to_api_parameters(base_params = {})
+      params = {
+        model: @model,
+        temperature: @temperature,
+        top_p: @top_p,
+        frequency_penalty: @frequency_penalty,
+        presence_penalty: @presence_penalty
+      }
+
+      # Add max_tokens if specified
+      params[:max_tokens] = @max_tokens if @max_tokens
+
+      # Merge any additional options
+      params.merge!(@additional_options)
+
+      # Merge with base parameters
+      base_params.merge(params)
     end
   end
 end