agentic 0.1.0 → 0.2.0

data/lib/agentic/default_agent_provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "llm_client"
+require_relative "llm_config"
+
+module Agentic
+  # Default implementation of an agent provider for use in the CLI
+  # This provider creates agents based on agent specs in tasks
+  class DefaultAgentProvider
+    # Initialize with optional LLM configuration
+    # @param llm_config [LlmConfig, nil] Configuration for the LLM client
+    def initialize(llm_config = nil)
+      @llm_config = llm_config || LlmConfig.new
+    end
+
+    # Creates and returns an agent for a task
+    # @param task [Task] The task that needs an agent
+    # @return [Agent] The agent created for the task
+    def get_agent_for_task(task)
+      agent_spec = task.agent_spec
+
+      # Create LLM client for this agent
+      llm_client = LlmClient.new(@llm_config)
+
+      # Create a new agent using the factory methods
+      Agent.build do |a|
+        a.name = agent_spec.name
+        a.role = agent_spec.name # Use name as role for simplicity
+        a.purpose = agent_spec.description
+        a.instructions = agent_spec.instructions
+        a.llm_client = llm_client
+      end
+    end
+  end
+end

data/lib/agentic/errors/llm_error.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Errors
+    # Base class for all LLM-related errors
+    class LlmError < StandardError
+      # @return [Hash, nil] The raw response from the LLM API, if available
+      attr_reader :response
+
+      # @return [Hash, nil] Additional context about the error
+      attr_reader :context
+
+      # @param message [String] The error message
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, response: nil, context: nil)
+        super(message)
+        @response = response
+        @context = context || {}
+      end
+    end
+
+    # Error raised when the LLM refuses to respond
+    class LlmRefusalError < LlmError
+      # @return [String] The refusal message from the LLM
+      attr_reader :refusal_message
+
+      # @return [Symbol] The category of refusal
+      attr_reader :refusal_category
+
+      # @param refusal_message [String] The refusal message from the LLM
+      # @param refusal_category [Symbol, nil] The category of refusal
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(refusal_message, refusal_category: nil, response: nil, context: nil)
+        super("LLM refused to respond: #{refusal_message}", response: response, context: context)
+        @refusal_message = refusal_message
+        @refusal_category = refusal_category || determine_refusal_category(refusal_message)
+      end
+
+      # Determines whether this refusal is retryable with modifications
+      # @return [Boolean] True if the refusal can be retried with modifications
+      def retryable_with_modifications?
+        [:unclear_instructions, :needs_clarification, :ambiguous_request, :format_error].include?(@refusal_category)
+      end
+
+      private
+
+      # Determines the category of refusal from the message
+      # @param message [String] The refusal message
+      # @return [Symbol] The category of refusal
+      def determine_refusal_category(message)
+        message = message.to_s.downcase
+
+        if message.include?("harmful") || message.include?("offensive") || message.include?("illegal")
+          :harmful_content
+        elsif message.include?("clarif") || message.include?("ambiguous")
+          :needs_clarification
+        elsif message.include?("format") || message.include?("structure")
+          :format_error
+        elsif message.include?("unclear") || message.include?("specific")
+          :unclear_instructions
+        elsif message.include?("capability") || message.include?("unable")
+          :capability_limitation
+        else
+          :general_refusal
+        end
+      end
+    end
+
+    # Error raised when the LLM response cannot be parsed
+    class LlmParseError < LlmError
+      # @return [Exception] The original parsing exception
+      attr_reader :parse_exception
+
+      # @param message [String] The error message
+      # @param parse_exception [Exception] The original parsing exception
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, parse_exception: nil, response: nil, context: nil)
+        super(message, response: response, context: context)
+        @parse_exception = parse_exception
+      end
+    end
+
+    # Error raised when there's a connection or network issue
+    class LlmNetworkError < LlmError
+      # @return [Exception] The original network exception
+      attr_reader :network_exception
+
+      # @param message [String] The error message
+      # @param network_exception [Exception] The original network exception
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, network_exception: nil, context: nil)
+        super(message, context: context)
+        @network_exception = network_exception
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        true
+      end
+    end
+
+    # Error raised when the API returns a rate limit error
+    class LlmRateLimitError < LlmError
+      # @return [Integer, nil] The number of seconds to wait before retrying
+      attr_reader :retry_after
+
+      # @param message [String] The error message
+      # @param retry_after [Integer, nil] The number of seconds to wait before retrying
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, retry_after: nil, response: nil, context: nil)
+        super(message, response: response, context: context)
+        @retry_after = retry_after
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        true
+      end
+    end
+
+    # Error raised when the API returns an authentication error
+    class LlmAuthenticationError < LlmError
+      # @param message [String] The error message
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, response: nil, context: nil)
+        super(message, response: response, context: context)
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        false
+      end
+    end
+
+    # Error raised when the API returns a server error
+    class LlmServerError < LlmError
+      # @param message [String] The error message
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, response: nil, context: nil)
+        super(message, response: response, context: context)
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        true
+      end
+    end
+
+    # Error raised when the request to the LLM times out
+    class LlmTimeoutError < LlmError
+      # @param message [String] The error message
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, context: nil)
+        super(message, context: context)
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        true
+      end
+    end
+
+    # Error raised when an invalid request is made to the LLM API
+    class LlmInvalidRequestError < LlmError
+      # @param message [String] The error message
+      # @param response [Hash, nil] The raw response from the LLM API
+      # @param context [Hash, nil] Additional context about the error
+      def initialize(message, response: nil, context: nil)
+        super(message, response: response, context: context)
+      end
+
+      # @return [Boolean] Whether this error is retryable
+      def retryable?
+        false
+      end
+    end
+  end
+end

data/lib/agentic/execution_plan.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Value object representing an execution plan with tasks and expected answer
+  #
+  # This class is part of the data-presentation separation pattern:
+  # 1. TaskPlanner generates the core plan data
+  # 2. ExecutionPlan serves as a structured value object to hold this data
+  # 3. The to_s method provides presentation capabilities when needed
+  #
+  # Using a value object instead of raw hashes provides:
+  # - Type safety
+  # - Domain-specific methods
+  # - Encapsulation of presentation logic
+  # - Clearer interfaces between components
+  class ExecutionPlan
+    # @return [Array<TaskDefinition>] The list of tasks to accomplish the goal
+    attr_reader :tasks
+
+    # @return [ExpectedAnswerFormat] The expected answer format
+    attr_reader :expected_answer
+
+    # @param tasks [Array<TaskDefinition>] The list of tasks to accomplish the goal
+    # @param expected_answer [ExpectedAnswerFormat] The expected answer format
+    def initialize(tasks, expected_answer)
+      @tasks = tasks
+      @expected_answer = expected_answer
+    end
+
+    # Returns a hash representation of the execution plan
+    # @return [Hash] The execution plan as a hash
+    def to_h
+      {
+        tasks: @tasks.map(&:to_h),
+        expected_answer: @expected_answer.to_h
+      }
+    end
+
+    # Returns a formatted string representation of the execution plan
+    # @return [String] The formatted execution plan
+    def to_s
+      plan = "Execution Plan:\n\n"
+      @tasks.each_with_index do |task, index|
+        plan += "#{index + 1}. #{task.description} (Agent: #{task.agent.name})\n"
+      end
+      plan += "\nExpected Answer:\n"
+      plan += "Format: #{@expected_answer.format}\n"
+      plan += "Sections: #{@expected_answer.sections.join(", ")}\n"
+      plan += "Length: #{@expected_answer.length}\n"
+      plan
+    end
+  end
+end

data/lib/agentic/execution_result.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Value object representing the results of plan execution
+  class ExecutionResult
+    # @return [String] The ID of the plan
+    attr_reader :plan_id
+
+    # @return [Symbol] The status of the execution (:completed, :partial_failure, :failed)
+    attr_reader :status
+
+    # @return [Float] The total execution time in seconds
+    attr_reader :execution_time
+
+    # @return [Hash] The tasks that were executed, keyed by ID
+    attr_reader :tasks
+
+    # @return [Hash] The results of the tasks, keyed by task ID
+    attr_reader :results
+
+    # Initializes a new execution result
+    # @param plan_id [String] The ID of the plan
+    # @param status [Symbol] The status of the execution
+    # @param execution_time [Float] The total execution time in seconds
+    # @param tasks [Hash] The tasks that were executed, keyed by ID
+    # @param results [Hash] The results of the tasks, keyed by task ID
+    def initialize(plan_id:, status:, execution_time:, tasks:, results:)
+      @plan_id = plan_id
+      @status = status
+      @execution_time = execution_time
+      @tasks = tasks
+      @results = results
+    end
+
+    # Returns the result for a specific task
+    # @param task_id [String] The ID of the task
+    # @return [TaskResult, nil] The result of the task, or nil if not found
+    def task_result(task_id)
+      @results[task_id]
+    end
+
+    # Checks if the execution was fully successful
+    # @return [Boolean] True if all tasks succeeded
+    def successful?
+      @status == :completed
+    end
+
+    # Checks if the execution partially failed
+    # @return [Boolean] True if some tasks failed but the plan completed
+    def partial_failure?
+      @status == :partial_failure
+    end
+
+    # Checks if the execution completely failed
+    # @return [Boolean] True if the plan failed to complete
+    def failed?
+      @status == :failed
+    end
+
+    # Returns a hash representation of the execution result
+    # @return [Hash] The execution result as a hash
+    def to_h
+      {
+        plan_id: @plan_id,
+        status: @status,
+        execution_time: @execution_time,
+        tasks: @tasks.transform_values { |task| task.is_a?(Task) ? task.to_h : task },
+        results: @results.transform_values { |result| result.is_a?(TaskResult) ? result.to_h : result }
+      }
+    end
+
+    # Returns a summary of the execution result
+    # @return [Hash] A summary of the execution result
+    def summary
+      total_tasks = @tasks.size
+      successful_tasks = @results.count { |_, result| result.successful? }
+      failed_tasks = @results.count { |_, result| result.failed? }
+
+      {
+        plan_id: @plan_id,
+        status: @status,
+        execution_time: @execution_time,
+        task_counts: {
+          total: total_tasks,
+          successful: successful_tasks,
+          failed: failed_tasks
+        }
+      }
+    end
+  end
+end

data/lib/agentic/expected_answer_format.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Value object representing expected answer format
+  class ExpectedAnswerFormat
+    # @return [String] The format of the expected answer
+    attr_reader :format
+
+    # @return [Array<String>] The sections expected in the answer
+    attr_reader :sections
+
+    # @return [String] The expected length of the answer
+    attr_reader :length
+
+    # Initializes a new expected answer format
+    # @param format [String] The format of the expected answer
+    # @param sections [Array<String>] The sections expected in the answer
+    # @param length [String] The expected length of the answer
+    def initialize(format:, sections:, length:)
+      @format = format
+      @sections = sections
+      @length = length
+    end
+
+    # Returns a serializable representation of the expected answer format
+    # @return [Hash] The expected answer format as a hash
+    def to_h
+      {
+        "format" => @format,
+        "sections" => @sections,
+        "length" => @length
+      }
+    end
+
+    # Creates an ExpectedAnswerFormat from a hash
+    # @param hash [Hash] The hash representation
+    # @return [ExpectedAnswerFormat] A new expected answer format
+    def self.from_hash(hash)
+      new(
+        format: hash["format"],
+        sections: hash["sections"],
+        length: hash["length"]
+      )
+    end
+  end
+end

data/lib/agentic/extension/domain_adapter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Extension
+    # The DomainAdapter integrates domain-specific knowledge into the general agent framework.
+    # It provides mechanisms for adapting prompts, tasks, and verification strategies
+    # to specific domains like healthcare, finance, legal, etc.
+    class DomainAdapter
+      # Initialize a new DomainAdapter
+      #
+      # @param [String] domain The identifier for the domain (e.g., "healthcare", "finance")
+      # @param [Hash] options Configuration options
+      # @option options [Logger] :logger Custom logger instance
+      # @option options [Hash] :domain_config Domain-specific configuration
+      def initialize(domain, options = {})
+        @domain = domain
+        @logger = options[:logger] || Agentic.logger
+        @domain_config = options[:domain_config] || {}
+        @adapters = {}
+        @domain_knowledge = {}
+
+        initialize_default_adapters
+      end
+
+      # Register an adapter for a specific component
+      #
+      # @param [Symbol] component The component to adapt (e.g., :prompt, :task, :verification)
+      # @param [Proc] adapter A callable that performs the adaptation
+      # @return [Boolean] True if registration was successful
+      def register_adapter(component, adapter)
+        return false unless adapter.respond_to?(:call)
+
+        @adapters[component] = adapter
+        true
+      end
+
+      # Add domain-specific knowledge
+      #
+      # @param [Symbol] key The knowledge identifier
+      # @param [Object] knowledge The domain knowledge to store
+      def add_knowledge(key, knowledge)
+        @domain_knowledge[key] = knowledge
+      end
+
+      # Get domain-specific knowledge
+      #
+      # @param [Symbol] key The knowledge identifier
+      # @return [Object, nil] The stored knowledge or nil if not found
+      def get_knowledge(key)
+        @domain_knowledge[key]
+      end
+
+      # Apply domain-specific adaptation to a component
+      #
+      # @param [Symbol] component The component to adapt
+      # @param [Object] target The target to apply adaptation to
+      # @param [Hash] context Additional context for adaptation
+      # @return [Object] The adapted target
+      def adapt(component, target, context = {})
+        return target unless @adapters.key?(component)
+
+        adapter = @adapters[component]
+        context = context.merge(domain: @domain, domain_knowledge: @domain_knowledge)
+
+        begin
+          result = adapter.call(target, context)
+          @logger.debug("Applied #{@domain} domain adaptation to #{component}")
+          result
+        rescue => e
+          @logger.error("Failed to apply #{@domain} domain adaptation to #{component}: #{e.message}")
+          target # Return original if adaptation fails
+        end
+      end
+
+      # Check if the adapter supports a specific component
+      #
+      # @param [Symbol] component The component to check
+      # @return [Boolean] True if an adapter exists for the component
+      def supports?(component)
+        @adapters.key?(component)
+      end
+
+      # Get the domain identifier
+      #
+      # @return [String] The domain identifier
+      attr_reader :domain
+
+      # Get domain configuration
+      #
+      # @return [Hash] The domain configuration
+      def configuration
+        @domain_config
+      end
+
+      private
+
+      # Initialize default adapters for common components
+      def initialize_default_adapters
+        # Identity adapter (returns input unchanged) as fallback
+        identity_adapter = ->(target, _context) { target }
+
+        # Register default adapters for common components
+        register_adapter(:prompt, identity_adapter)
+        register_adapter(:task, identity_adapter)
+        register_adapter(:verification, identity_adapter)
+      end
+    end
+  end
+end

data/lib/agentic/extension/plugin_manager.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Extension
+    # The PluginManager coordinates third-party extension loading, registration,
+    # and lifecycle management. It provides a central registry for all extensions
+    # and ensures they conform to the extension contracts.
+    class PluginManager
+      # Initialize a new PluginManager
+      #
+      # @param [Hash] options Configuration options for the plugin manager
+      # @option options [Logger] :logger Custom logger instance
+      # @option options [Boolean] :auto_discovery Whether to automatically discover plugins
+      # @option options [Array<String>] :plugin_paths Additional paths to search for plugins
+      def initialize(options = {})
+        @logger = options[:logger] || Agentic.logger
+        @auto_discovery = options.fetch(:auto_discovery, true)
+        @plugin_paths = options[:plugin_paths] || []
+        @plugin_paths << default_plugin_path
+        @plugins = {}
+        @hooks = Hash.new { |h, k| h[k] = [] }
+
+        discover_plugins if @auto_discovery
+      end
+
+      # Register a plugin with the manager
+      #
+      # @param [String] name The unique name of the plugin
+      # @param [Object] plugin The plugin instance
+      # @param [Hash] metadata Additional information about the plugin
+      # @return [Boolean] True if registration was successful
+      def register(name, plugin, metadata = {})
+        if @plugins.key?(name)
+          @logger.warn("Plugin '#{name}' is already registered. Use force: true to override.")
+          return false
+        end
+
+        unless valid_plugin?(plugin)
+          @logger.error("Plugin '#{name}' does not conform to the plugin contract")
+          return false
+        end
+
+        @plugins[name] = {
+          instance: plugin,
+          metadata: metadata.merge(registered_at: Time.now),
+          enabled: true
+        }
+
+        @logger.info("Plugin '#{name}' registered successfully")
+        true
+      end
+
+      # Register a plugin with the manager, overriding any existing plugin with the same name
+      #
+      # @param [String] name The unique name of the plugin
+      # @param [Object] plugin The plugin instance
+      # @param [Hash] metadata Additional information about the plugin
+      # @return [Boolean] True if registration was successful
+      def register!(name, plugin, metadata = {})
+        @plugins.delete(name) if @plugins.key?(name)
+        register(name, plugin, metadata)
+      end
+
+      # Enable a registered plugin
+      #
+      # @param [String] name The name of the plugin to enable
+      # @return [Boolean] True if the plugin was enabled
+      def enable(name)
+        return false unless @plugins.key?(name)
+
+        @plugins[name][:enabled] = true
+        @logger.info("Plugin '#{name}' enabled")
+        true
+      end
+
+      # Disable a registered plugin
+      #
+      # @param [String] name The name of the plugin to disable
+      # @return [Boolean] True if the plugin was disabled
+      def disable(name)
+        return false unless @plugins.key?(name)
+
+        @plugins[name][:enabled] = false
+        @logger.info("Plugin '#{name}' disabled")
+        true
+      end
+
+      # Get a registered plugin by name
+      #
+      # @param [String] name The name of the plugin to retrieve
+      # @return [Object, nil] The plugin or nil if not found or disabled
+      def get(name)
+        return nil unless @plugins.key?(name) && @plugins[name][:enabled]
+
+        @plugins[name][:instance]
+      end
+
+      # List all registered plugins
+      #
+      # @param [Boolean] only_enabled Only return enabled plugins
+      # @return [Hash] A hash of all registered plugins and their metadata
+      def list(only_enabled: false)
+        if only_enabled
+          @plugins.select { |_, data| data[:enabled] }
+        else
+          @plugins
+        end
+      end
+
+      # Register a hook for plugin events
+      #
+      # @param [Symbol] event The event to hook into (:after_register, :before_enable, :after_enable, :before_disable, :after_disable)
+      # @yield [name, plugin] The callback to execute when the event occurs
+      # @yieldparam [String] name The name of the plugin
+      # @yieldparam [Object] plugin The plugin instance
+      # @return [Boolean] True if the hook was registered
+      def register_hook(event, &callback)
+        return false unless callback
+
+        @hooks[event] << callback
+        true
+      end
+
+      # Discover plugins in configured paths
+      #
+      # @return [Integer] The number of plugins discovered
+      def discover_plugins
+        return 0 unless @auto_discovery
+
+        discovered = 0
+        @plugin_paths.each do |path|
+          Dir.glob(File.join(path, "*.rb")).each do |file|
+            require file
+            discovered += 1
+          rescue => e
+            @logger.error("Failed to load plugin from #{file}: #{e.message}")
+          end
+        end
+
+        @logger.info("Discovered #{discovered} plugins")
+        discovered
+      end
+
+      private
+
+      # Get the default plugin path
+      #
+      # @return [String] The default path for plugins
+      def default_plugin_path
+        File.join(File.dirname(__FILE__), "../../../plugins")
+      end
+
+      # Check if a plugin conforms to the plugin contract
+      #
+      # @param [Object] plugin The plugin to validate
+      # @return [Boolean] True if the plugin is valid
+      def valid_plugin?(plugin)
+        # Check that the plugin implements both required methods
+        plugin.respond_to?(:initialize_plugin) && plugin.respond_to?(:call)
+      end
+    end
+  end
+end