agentic 0.1.0 → 0.2.0

data/lib/agentic/retry_config.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Configuration object for the RetryHandler
+  class RetryConfig
+    # @return [Integer] The maximum number of retry attempts
+    attr_accessor :max_retries
+
+    # @return [Array<Class, String>] List of retryable error types/names
+    attr_accessor :retryable_errors
+
+    # @return [Symbol] The backoff strategy to use
+    attr_accessor :backoff_strategy
+
+    # @return [Hash] Options for the backoff strategy
+    attr_accessor :backoff_options
+
+    # @return [Proc, nil] Optional block to run before each retry
+    attr_accessor :before_retry
+
+    # @return [Proc, nil] Optional block to run after each retry
+    attr_accessor :after_retry
+
+    # Initializes a new retry configuration
+    # @param max_retries [Integer] The maximum number of retry attempts
+    # @param retryable_errors [Array<Class, String>] List of retryable error types/names
+    # @param backoff_strategy [Symbol] The backoff strategy (:constant, :linear, :exponential)
+    # @param backoff_options [Hash] Options for the backoff strategy
+    # @param before_retry [Proc, nil] Optional block to run before each retry
+    # @param after_retry [Proc, nil] Optional block to run after each retry
+    def initialize(
+      max_retries: 3,
+      retryable_errors: [Errors::LlmTimeoutError, Errors::LlmRateLimitError, Errors::LlmServerError, Errors::LlmNetworkError],
+      backoff_strategy: :exponential,
+      backoff_options: {},
+      before_retry: nil,
+      after_retry: nil
+    )
+      @max_retries = max_retries
+      @retryable_errors = retryable_errors
+      @backoff_strategy = backoff_strategy
+      @backoff_options = {
+        base_delay: 1.0,
+        jitter_factor: 0.25
+      }.merge(backoff_options)
+      @before_retry = before_retry
+      @after_retry = after_retry
+    end
+
+    # Creates a RetryHandler from this configuration
+    # @return [RetryHandler] A new retry handler
+    def to_handler
+      RetryHandler.new(
+        max_retries: @max_retries,
+        retryable_errors: @retryable_errors,
+        backoff_strategy: @backoff_strategy,
+        backoff_options: @backoff_options,
+        before_retry: @before_retry,
+        after_retry: @after_retry
+      )
+    end
+  end
+end

data/lib/agentic/retry_handler.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Handles retrying operations with configurable backoff strategies
+  class RetryHandler
+    # @return [Integer] The maximum number of retry attempts
+    attr_reader :max_retries
+
+    # @return [Array<Class, String>] List of retryable error types/names
+    attr_reader :retryable_errors
+
+    # @return [Symbol] The backoff strategy to use
+    attr_reader :backoff_strategy
+
+    # @return [Proc, nil] Optional block to run before each retry
+    attr_reader :before_retry
+
+    # @return [Proc, nil] Optional block to run after each retry
+    attr_reader :after_retry
+
+    # Initializes a new RetryHandler
+    # @param max_retries [Integer] The maximum number of retry attempts
+    # @param retryable_errors [Array<Class, String>] List of retryable error types/names
+    # @param backoff_strategy [Symbol] The backoff strategy (:constant, :linear, :exponential)
+    # @param backoff_options [Hash] Options for the backoff strategy
+    # @param before_retry [Proc, nil] Optional block to run before each retry
+    # @param after_retry [Proc, nil] Optional block to run after each retry
+    # @option backoff_options [Float] :base_delay The base delay in seconds
+    # @option backoff_options [Float] :jitter_factor The jitter factor (0.0-1.0)
+    def initialize(
+      max_retries: 3,
+      retryable_errors: [Errors::LlmTimeoutError, Errors::LlmRateLimitError, Errors::LlmServerError, Errors::LlmNetworkError],
+      backoff_strategy: :exponential,
+      backoff_options: {},
+      before_retry: nil,
+      after_retry: nil
+    )
+      @max_retries = max_retries
+      @retryable_errors = retryable_errors
+      @backoff_strategy = backoff_strategy
+      @backoff_options = {
+        base_delay: 1.0,
+        jitter_factor: 0.25
+      }.merge(backoff_options)
+      @before_retry = before_retry
+      @after_retry = after_retry
+    end
+
+    # Executes the given block with retries
+    # @param block [Proc] The block to execute with retries
+    # @return [Object] The return value of the block
+    # @raise [StandardError] If the block failed after all retries
+    def with_retry(&block)
+      attempt = 0
+
+      begin
+        attempt += 1
+        block.call
+      rescue => e
+        error = e.is_a?(Errors::LlmError) ? e : Errors::LlmError.new(e.message, context: {original_error: e.class.name})
+
+        if retryable?(error) && attempt <= max_retries
+          delay = calculate_backoff_delay(attempt)
+          Agentic.logger.info("Retry #{attempt}/#{max_retries} for error: #{error.message}. Waiting #{delay.round(2)}s before retrying.")
+
+          @before_retry&.call(attempt: attempt, error: error, delay: delay)
+          sleep(delay)
+          @after_retry&.call(attempt: attempt, error: error, delay: delay)
+
+          retry
+        else
+          if attempt > max_retries
+            Agentic.logger.error("Max retries (#{max_retries}) exceeded for error: #{error.message}")
+          else
+            Agentic.logger.error("Non-retryable error: #{error.message}")
+          end
+
+          raise error
+        end
+      end
+    end
+
+    private
+
+    # Determines if an error is retryable
+    # @param error [StandardError] The error to check
+    # @return [Boolean] True if the error is retryable
+    def retryable?(error)
+      return true if error.respond_to?(:retryable?) && error.retryable?
+
+      @retryable_errors.any? do |retryable|
+        if retryable.is_a?(Class)
+          error.is_a?(retryable)
+        else
+          error.instance_of?(retryable).to_s
+        end
+      end
+    end
+
+    # Calculates the backoff delay for a given attempt
+    # @param attempt [Integer] The current attempt number (1-based)
+    # @return [Float] The delay in seconds
+    def calculate_backoff_delay(attempt)
+      base_delay = @backoff_options[:base_delay]
+
+      delay = case @backoff_strategy
+      when :constant
+        base_delay
+      when :linear
+        base_delay * attempt
+      when :exponential
+        base_delay * (2**(attempt - 1))
+      else
+        base_delay
+      end
+
+      if @backoff_options[:jitter_factor] && @backoff_options[:jitter_factor] > 0
+        jitter = rand(-delay * @backoff_options[:jitter_factor]..delay * @backoff_options[:jitter_factor])
+        delay += jitter
+      end
+
+      [delay, 0].max # Ensure positive delay
+    end
+  end
+end

data/lib/agentic/structured_outputs.rb

@@ -117,7 +117,7 @@ module Agentic
         max_child_depth = schema[:properties].values.map do |prop|
           calculate_max_depth(prop, current_depth + 1)
         end.max
-        [current_depth, max_child_depth].max
+        max_child_depth ? [current_depth, max_child_depth].max : current_depth
       end
     end
   end

data/lib/agentic/task.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+require_relative "observable"
+require_relative "task_definition"
+require_relative "agent_specification"
+
+module Agentic
+  # Represents an individual task to be executed by an agent
+  # @attr_reader [String] id Unique identifier for the task
+  # @attr_reader [String] description Human-readable description of the task
+  # @attr_reader [Hash] agent_spec Requirements for the agent that will execute this task
+  # @attr_reader [Hash] input Input data for the task
+  # @attr_reader [Hash, nil] output Output produced by the task, nil if not yet executed
+  # @attr_reader [Symbol] status Current status of the task (:pending, :in_progress, :completed, :failed)
+  # @attr_reader [TaskFailure, nil] failure Failure information if the task failed, nil otherwise
+  # @attr_reader [Boolean, nil] ready_to_execute Flag indicating if the task is ready to be executed
+  # @attr_accessor [Integer, nil] retry_count Number of times the task has been retried
+  # @attr_accessor [Symbol, nil] output_schema_name Name of the output schema to use
+  class Task
+    include Agentic::Observable
+
+    attr_reader :id, :description, :agent_spec, :input, :output, :status, :failure, :ready_to_execute
+    attr_accessor :retry_count, :output_schema_name
+
+    # Initializes a new task
+    # @param description [String] Human-readable description of the task
+    # @param agent_spec [Hash, AgentSpecification] Requirements for the agent that will execute this task
+    # @param input [Hash] Input data for the task
+    # @param output_schema_name [Symbol, nil] Name of the output schema to use for structured output
+    # @return [Task] A new task instance
+    def initialize(description:, agent_spec:, input: {}, output_schema_name: nil)
+      @id = SecureRandom.uuid
+      @description = description
+
+      # Convert agent_spec to AgentSpecification if it's a hash
+      @agent_spec = if agent_spec.is_a?(Hash)
+        AgentSpecification.new(
+          name: agent_spec["name"],
+          description: agent_spec["description"] || "",
+          instructions: agent_spec["instructions"]
+        )
+      else
+        agent_spec
+      end
+
+      @input = input
+      @output = nil
+      @failure = nil
+      @status = :pending
+      @ready_to_execute = nil
+      @output_schema_name = output_schema_name
+    end
+
+    # Creates a task from a TaskDefinition
+    # @param definition [TaskDefinition] The task definition
+    # @param input [Hash] Input data for the task
+    # @return [Task] A new task instance
+    def self.from_definition(definition, input = {})
+      new(
+        description: definition.description,
+        agent_spec: definition.agent,
+        input: input
+      )
+    end
+
+    # Executes the task using the given agent
+    # @param agent [Agent] The agent that will execute this task
+    # @return [TaskResult] The result of the task execution
+    def perform(agent)
+      old_status = @status
+      @status = :in_progress
+
+      notify_observers(:status_change, old_status, @status)
+
+      begin
+        @output = if has_output_schema?
+          agent.execute_with_schema(build_prompt, output_schema)
+        else
+          agent.execute(build_prompt)
+        end
+        old_status = @status
+        @status = :completed
+
+        notify_observers(:status_change, old_status, @status)
+
+        TaskResult.new(
+          task_id: @id,
+          success: true,
+          output: @output
+        )
+      rescue => e
+        @failure = TaskFailure.new(
+          message: e.message,
+          type: e.class.name,
+          context: {
+            backtrace: e.backtrace&.first(10),
+            agent_id: agent.respond_to?(:id) ? agent.id : nil
+          }
+        )
+
+        old_status = @status
+        @status = :failed
+
+        notify_observers(:status_change, old_status, @status)
+        notify_observers(:failure_occurred, @failure)
+
+        Agentic.logger.error("Task execution failed: #{e.message}")
+
+        TaskResult.new(
+          task_id: @id,
+          success: false,
+          failure: @failure
+        )
+      end
+    end
+
+    # Retries a failed task
+    # @param agent [Agent] The agent that will execute this task
+    # @return [TaskResult] The result of the task execution
+    # @raise [StandardError] If the task is not in a failed state
+    def retry(agent)
+      raise "Cannot retry a task that is not in a failed state" unless @status == :failed
+
+      old_status = @status
+      @status = :retrying
+
+      notify_observers(:status_change, old_status, @status)
+
+      perform(agent)
+    end
+
+    # Returns a serializable representation of the task
+    # @return [Hash] The task as a hash
+    def to_h
+      {
+        id: @id,
+        description: @description,
+        agent_spec: @agent_spec.is_a?(AgentSpecification) ? @agent_spec.to_h : @agent_spec,
+        input: @input,
+        output: @output,
+        status: @status,
+        failure: @failure&.to_h
+      }
+    end
+
+    # Returns the output schema for this task
+    # @return [Agentic::StructuredOutputs::Schema, nil] The schema or nil if none specified
+    def output_schema
+      return nil unless @output_schema_name
+      TaskOutputSchemas.get(@output_schema_name)
+    end
+
+    # Checks if this task has a structured output schema
+    # @return [Boolean] True if task has an output schema
+    def has_output_schema?
+      !@output_schema_name.nil? && TaskOutputSchemas.exists?(@output_schema_name)
+    end
+
+    # Sets the output schema for this task
+    # @param schema_name [Symbol] The name of the schema to use
+    def set_output_schema(schema_name)
+      @output_schema_name = schema_name
+    end
+
+    private
+
+    # Builds the prompt to be sent to the agent
+    # @return [String] The formatted prompt
+    def build_prompt
+      output_requirements = if has_output_schema?
+        "Provide your response as a structured JSON object that follows the specified schema. Do not include any markdown formatting, code blocks, or additional text - just the raw JSON."
+      else
+        "Provide your response as valid JSON only. Do not wrap the JSON in markdown code blocks or any other formatting. Return raw JSON that can be parsed directly."
+      end
+
+      <<~PROMPT
+        [System Instructions]
+        #{agent_spec.instructions}
+        
+        [Task Description]
+        #{description}
+        
+        [Input Parameters]
+        #{JSON.pretty_generate(input)}
+        
+        [Output Requirements]
+        #{output_requirements}
+      PROMPT
+    end
+  end
+end

data/lib/agentic/task_definition.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Value object representing a task definition
+  class TaskDefinition
+    # @return [String] A description of the task
+    attr_reader :description
+
+    # @return [AgentSpecification] The agent specification for this task
+    attr_reader :agent
+
+    # Initializes a new task definition
+    # @param description [String] A description of the task
+    # @param agent [AgentSpecification] The agent specification for this task
+    def initialize(description:, agent:)
+      @description = description
+      @agent = agent
+    end
+
+    # Returns a serializable representation of the task definition
+    # @return [Hash] The task definition as a hash
+    def to_h
+      {
+        "description" => @description,
+        "agent" => @agent.to_h
+      }
+    end
+
+    # Creates a TaskDefinition from a hash
+    # @param hash [Hash] The hash representation
+    # @return [TaskDefinition] A new task definition
+    def self.from_hash(hash)
+      new(
+        description: hash["description"],
+        agent: AgentSpecification.from_hash(hash["agent"])
+      )
+    end
+  end
+end

data/lib/agentic/task_execution_result.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "task_failure"
+
+module Agentic
+  # Value object representing the execution result of a task
+  class TaskExecutionResult
+    # @return [Symbol] The status of the task execution (:completed, :failed, :canceled)
+    attr_reader :status
+
+    # @return [Hash, nil] The output produced by the task (only if successful)
+    attr_reader :output
+
+    # @return [TaskFailure, nil] The failure details (only if failed)
+    attr_reader :failure
+
+    # @param status [Symbol] The status of the task execution
+    # @param output [Hash, nil] The output produced by the task
+    # @param failure [TaskFailure, nil] The failure details
+    def initialize(status:, output: nil, failure: nil)
+      @status = status
+      @output = output
+      @failure = failure
+    end
+
+    # Creates a successful execution result
+    # @param output [Hash] The task output
+    # @return [TaskExecutionResult] A successful execution result
+    def self.success(output)
+      new(status: :completed, output: output)
+    end
+
+    # Creates a failed execution result
+    # @param failure [TaskFailure] The failure details
+    # @return [TaskExecutionResult] A failed execution result
+    def self.failure(failure)
+      new(status: :failed, failure: failure)
+    end
+
+    # Creates a canceled execution result
+    # @return [TaskExecutionResult] A canceled execution result
+    def self.canceled
+      new(status: :canceled)
+    end
+
+    # Creates a task execution result from a hash
+    # @param hash [Hash] The hash representation of a task execution result
+    # @return [TaskExecutionResult] A task execution result
+    def self.from_hash(hash)
+      # Handle the case where hash is not actually a hash (could be nil, Integer, etc.)
+      return new(status: :completed) unless hash.is_a?(Hash)
+
+      # Convert string keys to symbols if necessary
+      hash = hash.transform_keys(&:to_sym) if hash.keys.first.is_a?(String)
+
+      failure = hash[:failure] ? TaskFailure.from_hash(hash[:failure]) : nil
+      new(
+        status: hash[:status] || :completed,
+        output: hash[:output],
+        failure: failure
+      )
+    end
+
+    # Checks if the task execution was successful
+    # @return [Boolean] True if successful, false otherwise
+    def successful?
+      @status == :completed
+    end
+
+    # Checks if the task execution failed
+    # @return [Boolean] True if failed, false otherwise
+    def failed?
+      @status == :failed
+    end
+
+    # Checks if the task execution was canceled
+    # @return [Boolean] True if canceled, false otherwise
+    def canceled?
+      @status == :canceled
+    end
+
+    # Returns a hash representation of the execution result
+    # @return [Hash] The execution result as a hash
+    def to_h
+      {
+        status: @status,
+        output: @output,
+        failure: @failure&.to_h
+      }
+    end
+  end
+end

data/lib/agentic/task_failure.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Represents a failure that occurred during task execution
+  # @attr_reader [String] message The failure message
+  # @attr_reader [String] type The type of failure
+  # @attr_reader [Time] timestamp When the failure occurred
+  # @attr_reader [Hash] context Additional context about the failure
+  class TaskFailure
+    attr_reader :message, :type, :timestamp, :context
+
+    # Initializes a new task failure
+    # @param message [String] The failure message
+    # @param type [String] The type of failure
+    # @param context [Hash] Additional context about the failure
+    # @return [TaskFailure] A new task failure instance
+    def initialize(message:, type:, context: {})
+      @message = message
+      @type = type
+      @timestamp = Time.now
+      @context = context
+    end
+
+    # Returns a serializable representation of the failure
+    # @return [Hash] The failure as a hash
+    def to_h
+      {
+        message: @message,
+        type: @type,
+        timestamp: @timestamp.iso8601,
+        context: @context
+      }
+    end
+
+    # Creates a task failure from an exception
+    # @param exception [Exception] The exception
+    # @param context [Hash] Additional context about the failure
+    # @return [TaskFailure] A new task failure instance
+    def self.from_exception(exception, context = {})
+      new(
+        message: exception.message,
+        type: exception.class.name,
+        context: context.merge(
+          backtrace: exception.backtrace&.first(10)
+        )
+      )
+    end
+
+    # Creates a task failure from a hash
+    # @param hash [Hash] The hash representation of a task failure
+    # @return [TaskFailure] A new task failure instance
+    def self.from_hash(hash)
+      # Handle the case where hash is not actually a hash
+      return new(message: "Unknown error", type: "UnknownError") unless hash.is_a?(Hash)
+
+      # Convert string keys to symbols if necessary
+      hash = hash.transform_keys(&:to_sym) if hash.keys.first.is_a?(String)
+
+      new(
+        message: hash[:message] || "Unknown error",
+        type: hash[:type] || "UnknownError",
+        context: hash[:context] || {}
+      )
+    end
+  end
+end

data/lib/agentic/task_output_schemas.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Registry for managing task output schemas
+  # Provides a centralized location for defining and accessing
+  # structured output schemas used by tasks
+  class TaskOutputSchemas
+    @schemas = {}
+
+    class << self
+      # Registers a new output schema
+      # @param name [Symbol] The schema name/identifier
+      # @param schema [Agentic::StructuredOutputs::Schema] The schema definition
+      def register(name, schema)
+        @schemas[name] = schema
+      end
+
+      # Retrieves a registered schema
+      # @param name [Symbol] The schema name/identifier
+      # @return [Agentic::StructuredOutputs::Schema, nil] The schema or nil if not found
+      def get(name)
+        @schemas[name] || ((name == :default) ? default_task_schema : nil)
+      end
+
+      # Lists all registered schema names
+      # @return [Array<Symbol>] Array of schema names
+      def list_schemas
+        (@schemas.keys + [:default]).uniq
+      end
+
+      # Checks if a schema is registered
+      # @param name [Symbol] The schema name/identifier
+      # @return [Boolean] True if schema exists
+      def exists?(name)
+        @schemas.key?(name) || name == :default
+      end
+
+      # Returns the default task output schema for general task responses
+      # @return [Agentic::StructuredOutputs::Schema] Default schema for task outputs
+      def default_task_schema
+        @default_schema ||= StructuredOutputs::Schema.new("task_output") do |schema|
+          # Simple, flexible schema for task results
+          schema.string(:status, enum: ["completed", "partial", "failed"])
+          schema.object(:result) do |result_schema|
+            result_schema.string(:summary)
+            # Additional properties will be allowed for flexible task outputs
+          end
+          schema.array(:steps, items: {type: "string"})
+        end
+      end
+
+      # Returns a simple object schema for maximum flexibility
+      # @return [Agentic::StructuredOutputs::Schema] Simple object schema
+      def simple_object_schema
+        @simple_object_schema ||= StructuredOutputs::Schema.new("simple_object") do |schema|
+          # Minimal schema that accepts any structured JSON object
+          # This is useful when we want structured JSON but maximum flexibility
+          schema.string(:type)
+          schema.object(:data) do
+            # Flexible data structure
+          end
+        end
+      end
+
+      # Returns a schema for code generation tasks
+      # @return [Agentic::StructuredOutputs::Schema] Code generation schema
+      def code_generation_schema
+        @code_generation_schema ||= StructuredOutputs::Schema.new("code_generation") do |schema|
+          schema.string(:language)
+          schema.string(:filename)
+          schema.string(:code)
+          schema.string(:description)
+          schema.array(:dependencies, items: {type: "string"})
+        end
+      end
+
+      # Returns a schema for analysis/research tasks
+      # @return [Agentic::StructuredOutputs::Schema] Analysis task schema
+      def analysis_schema
+        @analysis_schema ||= StructuredOutputs::Schema.new("analysis_result") do |schema|
+          schema.string(:summary)
+          schema.array(:key_findings, items: {type: "string"})
+          schema.object(:data) do
+            # Flexible analysis data
+          end
+          schema.array(:recommendations, items: {type: "string"})
+          schema.string(:confidence_level, enum: ["high", "medium", "low"])
+        end
+      end
+
+      # Resets all registered schemas (useful for testing)
+      def reset!
+        @schemas = {}
+        @default_schema = nil
+        @simple_object_schema = nil
+        @code_generation_schema = nil
+        @analysis_schema = nil
+      end
+
+      # Registers default schemas
+      def register_defaults!
+        register(:default, default_task_schema)
+        register(:simple_object, simple_object_schema)
+        register(:code_generation, code_generation_schema)
+        register(:analysis, analysis_schema)
+      end
+    end
+
+    # Register defaults when the class is loaded
+    register_defaults!
+  end
+end