agentic 0.1.0 → 0.2.0

data/lib/agentic/task_planner.rb

@@ -1,15 +1,25 @@
 # frozen_string_literal: true
 
+require_relative "execution_plan"
+require_relative "agent_specification"
+require_relative "task_definition"
+require_relative "expected_answer_format"
+
 module Agentic
   # Handles the task planning process for Agentic using LLM
+  #
+  # This class follows separation of concerns by:
+  # 1. Focusing on core planning logic and data generation
+  # 2. Returning structured data (ExecutionPlan) instead of formatted strings
+  # 3. Delegating presentation concerns to the ExecutionPlan class
   class TaskPlanner
     # @return [String] The goal to be accomplished
     attr_reader :goal
 
-    # @return [Array<Hash>] The list of tasks to accomplish the goal
+    # @return [Array<TaskDefinition>] The list of tasks to accomplish the goal
     attr_reader :tasks
 
-    # @return [Hash] The expected answer format
+    # @return [ExpectedAnswerFormat] The expected answer format
     attr_reader :expected_answer
 
     # @return [LlmConfig] The configuration for the LLM
@@ -21,7 +31,11 @@ module Agentic
     def initialize(goal, llm_config = LlmConfig.new)
       @goal = goal
       @tasks = []
-      @expected_answer = {}
+      @expected_answer = ExpectedAnswerFormat.new(
+        format: "Undetermined",
+        sections: [],
+        length: "Undetermined"
+      )
       @llm_config = llm_config
     end
 
@@ -51,7 +65,22 @@ module Agentic
       end
 
       response = llm_request(system_message, user_message, schema)
-      @tasks = response[:content]["tasks"]
+
+      if response.successful?
+        @tasks = response.content["tasks"].map do |task_data|
+          TaskDefinition.new(
+            description: task_data["description"],
+            agent: AgentSpecification.new(
+              name: task_data["agent"]["name"],
+              description: task_data["agent"]["description"],
+              instructions: task_data["agent"]["instructions"]
+            )
+          )
+        end
+      else
+        Agentic.logger.error("Failed to analyze goal: #{response.error&.message || response.refusal}")
+        @tasks = []
+      end
     end
 
     # Determines the expected answer format using LLM
@@ -67,29 +96,35 @@ module Agentic
       end
 
       response = llm_request(system_message, user_message, schema)
-      @expected_answer = response[:content]
-    end
 
-    # Displays the execution plan
-    # @return [String] The formatted execution plan
-    def display_plan
-      plan = "Execution Plan:\n\n"
-      @tasks.each_with_index do |task, index|
-        plan += "#{index + 1}. #{task["description"]} (Agent: #{task["agent"].inspect})\n"
+      if response.successful?
+        @expected_answer = ExpectedAnswerFormat.new(
+          format: response.content["format"],
+          sections: response.content["sections"],
+          length: response.content["length"]
+        )
+      else
+        Agentic.logger.error("Failed to determine expected answer format: #{response.error&.message || response.refusal}")
+        @expected_answer = ExpectedAnswerFormat.new(
+          format: "Undetermined",
+          sections: [],
+          length: "Undetermined"
+        )
       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
+
+    # Returns an ExecutionPlan object representing the execution plan
+    # @return [ExecutionPlan] The structured execution plan
+    def execution_plan
+      ExecutionPlan.new(@tasks, @expected_answer)
     end
 
     # Executes the entire planning process
-    # @return [String] The formatted execution plan
+    # @return [ExecutionPlan] The structured execution plan
     def plan
       analyze_goal
       determine_expected_answer
-      display_plan
+      execution_plan
     end
 
     private

data/lib/agentic/task_result.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Agentic
+  # Represents the result of a task execution
+  # @attr_reader [String] task_id The ID of the task that produced this result
+  # @attr_reader [Boolean] success Whether the task execution was successful
+  # @attr_reader [Hash, nil] output The output produced by the task, nil if unsuccessful
+  # @attr_reader [TaskFailure, nil] failure The failure information, nil if successful
+  class TaskResult
+    attr_reader :task_id, :success, :output, :failure
+
+    # Initializes a new task result
+    # @param task_id [String] The ID of the task that produced this result
+    # @param success [Boolean] Whether the task execution was successful
+    # @param output [Hash, nil] The output produced by the task
+    # @param failure [TaskFailure, nil] The failure information
+    # @return [TaskResult] A new task result instance
+    def initialize(task_id:, success:, output: nil, failure: nil)
+      @task_id = task_id
+      @success = success
+      @output = output
+      @failure = failure
+    end
+
+    # Checks if the task execution was successful
+    # @return [Boolean] True if successful, false otherwise
+    def successful?
+      @success
+    end
+
+    # Checks if the task execution failed
+    # @return [Boolean] True if failed, false otherwise
+    def failed?
+      !@success
+    end
+
+    # Returns a serializable representation of the result
+    # @return [Hash] The result as a hash
+    def to_h
+      {
+        task_id: @task_id,
+        success: @success,
+        output: @output,
+        failure: @failure&.to_h
+      }
+    end
+  end
+end

data/lib/agentic/ui.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "tty-spinner"
+require "tty-progressbar"
+require "tty-box"
+require "tty-table"
+require "tty-cursor"
+require "pastel"
+
+module Agentic
+  # UI helpers for the CLI
+  module UI
+    # Creates and returns a new spinner
+    # @param message [String] The message to display with the spinner
+    # @param format [Symbol] The spinner format
+    # @return [TTY::Spinner] The spinner object
+    def self.spinner(message, format: :dots)
+      TTY::Spinner.new("[:spinner] #{message}", format: format)
+    end
+
+    # Creates and returns a new progress bar
+    # @param title [String] The progress bar title
+    # @param total [Integer] The total number of steps
+    # @param options [Hash] Additional options for the progress bar
+    # @return [TTY::ProgressBar] The progress bar object
+    def self.progress_bar(title, total, options = {})
+      TTY::ProgressBar.new("[:bar] #{title} :percent",
+        total: total,
+        width: 40,
+        **options)
+    end
+
+    # Creates a colored text box
+    # @param title [String] The box title
+    # @param content [String] The box content
+    # @param options [Hash] Additional options for the box
+    # @return [String] The formatted box
+    def self.box(title, content, options = {})
+      # Calculate width based on visible characters (strip ANSI codes)
+      visible_lines = content.lines.map { |line| line.gsub(/\e\[[0-9;]*m/, "") }
+      max_line_length = visible_lines.map(&:length).max || 0
+
+      TTY::Box.frame(
+        title: {top_left: title},
+        width: [100, max_line_length + 4].min,
+        padding: 1,
+        **options
+      ) { content }
+    end
+
+    # Returns a pastel instance for colorizing text
+    # @return [Pastel] The pastel instance
+    def self.pastel
+      @pastel ||= Pastel.new
+    end
+
+    # Returns colored text
+    # @param text [String] The text to colorize
+    # @param color [Symbol] The color to use
+    # @return [String] The colorized text
+    def self.colorize(text, color)
+      pastel.send(color, text)
+    end
+
+    # Returns a text with a colored status indicator
+    # @param text [String] The text to display
+    # @param status [Symbol] The status
+    # @return [String] The text with colored status
+    def self.status_text(text, status)
+      status_color = case status
+      when :success, :completed
+        :green
+      when :failure, :failed, :error
+        :red
+      when :warning, :pending
+        :yellow
+      when :info, :in_progress
+        :blue
+      else
+        :white
+      end
+
+      pastel.send(status_color, text)
+    end
+
+    # Formats a duration in seconds to a human-readable string
+    # @param seconds [Float] The duration in seconds
+    # @return [String] The formatted duration
+    def self.format_duration(seconds)
+      if seconds < 1
+        "#{(seconds * 1000).round}ms"
+      elsif seconds < 60
+        "#{seconds.round(2)}s"
+      elsif seconds < 3600
+        minutes = (seconds / 60).floor
+        remaining_seconds = (seconds % 60).round
+        "#{minutes}m #{remaining_seconds}s"
+      else
+        hours = (seconds / 3600).floor
+        minutes = ((seconds % 3600) / 60).floor
+        "#{hours}h #{minutes}m"
+      end
+    end
+
+    # Handles a long-running operation with a spinner
+    # @param message [String] The message to display
+    # @param quiet [Boolean] Whether to suppress output
+    # @yield The block to execute
+    # @return [Object] The return value of the block
+    def self.with_spinner(message, quiet: false)
+      return yield if quiet
+
+      spinner = self.spinner(message)
+      spinner.auto_spin
+
+      begin
+        result = yield
+        spinner.success("(#{colorize("✓", :green)}) #{message}")
+        result
+      rescue => e
+        spinner.error("(#{colorize("✗", :red)}) #{message}: #{e.message}")
+        raise
+      end
+    end
+
+    # Returns a task status indicator
+    # @param status [Symbol] The status
+    # @return [String] The status indicator
+    def self.task_status_indicator(status)
+      case status
+      when :completed
+        colorize("✓", :green)
+      when :failed
+        colorize("✗", :red)
+      when :in_progress
+        colorize("↻", :blue)
+      when :building_agent, :agent_ready
+        colorize("○", :yellow)  # Pending task execution
+      when :pending
+        colorize("○", :yellow)
+      when :canceled
+        colorize("⨯", :yellow)
+      else
+        colorize("?", :white)
+      end
+    end
+
+    # Creates a holistic task display table
+    # @param tasks [Array<Hash>] Array of task data with status, description, etc.
+    # @param options [Hash] Display options
+    # @return [String] The formatted table
+    def self.task_display_table(tasks, options = {})
+      return "" if tasks.empty?
+
+      # Use simplified headers when show_agent_column is false
+      show_agent_column = options.fetch(:show_agent_column, true)
+      headers = if show_agent_column
+        ["Status", "Task", "Agent", "Duration", "Output"]
+      else
+        ["Status", "Task", "Duration", "Output"]
+      end
+
+      table = TTY::Table.new(
+        header: headers,
+        rows: tasks.map { |task| format_task_row(task, show_agent_column: show_agent_column) }
+      )
+
+      table.render(:unicode,
+        padding: [0, 1],
+        **options)
+    end
+
+    # Returns a cursor instance for terminal positioning
+    # @return [TTY::Cursor] The cursor instance
+    def self.cursor
+      @cursor ||= TTY::Cursor
+    end
+
+    # Clears lines and repositions cursor for table updates
+    # @param line_count [Integer] Number of lines to clear
+    def self.clear_and_reposition(line_count)
+      print cursor.up(line_count) + cursor.clear_lines(line_count, :down)
+    end
+
+    # Formats a single task row for the display table
+    # @param task [Hash] Task data including status, description, duration, output
+    # @param show_agent_column [Boolean] Whether to include agent information in the row
+    # @return [Array] Formatted row data
+    def self.format_task_row(task, show_agent_column: true)
+      status_indicator = task_status_indicator(task[:status])
+
+      # Truncate description for display
+      description = truncate_text(task[:description] || "Unknown task", 35)
+
+      # Format agent information
+      agent_info = if task[:status] == :building_agent
+        colorize("🤖 Building...", :blue)
+      elsif task[:agent_role]
+        if task[:agent_duration]
+          colorize("✓ #{task[:agent_role]} (#{format_duration(task[:agent_duration])})", :green)
+        else
+          colorize("✓ #{task[:agent_role]}", :green)
+        end
+      else
+        "-"
+      end
+
+      # Format duration
+      duration = if task[:duration]
+        format_duration(task[:duration])
+      elsif [:in_progress, :building_agent, :agent_ready].include?(task[:status]) && task[:start_time]
+        format_duration(Time.now - task[:start_time])
+      else
+        "-"
+      end
+
+      # Format output preview
+      output = if task[:output] && !task[:output].to_s.empty?
+        truncate_text(task[:output].to_s.strip, 25)
+      elsif task[:status] == :failed && task[:error]
+        colorize(truncate_text(task[:error], 25), :red)
+      else
+        "-"
+      end
+
+      if show_agent_column
+        [status_indicator, description, agent_info, duration, output]
+      else
+        [status_indicator, description, duration, output]
+      end
+    end
+
+    # Truncates text to specified length with ellipsis
+    # @param text [String] Text to truncate
+    # @param max_length [Integer] Maximum length
+    # @return [String] Truncated text
+    def self.truncate_text(text, max_length)
+      return text if text.length <= max_length
+      "#{text[0..max_length - 4]}..."
+    end
+
+    private_class_method :format_task_row, :truncate_text
+  end
+end

data/lib/agentic/verification/critic_framework.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Verification
+    # Framework for multi-perspective evaluation of task results
+    class CriticFramework
+      # @return [Array<Critic>] The critics registered with this framework
+      attr_reader :critics
+
+      # @return [Hash] Configuration options for the framework
+      attr_reader :config
+
+      # Initializes a new CriticFramework
+      # @param critics [Array<Critic>] The critics to register
+      # @param config [Hash] Configuration options for the framework
+      def initialize(critics: [], config: {})
+        @critics = critics
+        @config = config
+      end
+
+      # Adds a critic to the framework
+      # @param critic [Critic] The critic to add
+      # @return [void]
+      def add_critic(critic)
+        @critics << critic
+      end
+
+      # Evaluates a task result using all registered critics
+      # @param task [Task] The task to evaluate
+      # @param result [TaskResult] The result to evaluate
+      # @return [CriticResult] The combined evaluation result
+      def evaluate(task, result)
+        evaluations = @critics.map { |critic| critic.critique(task, result) }
+
+        # Aggregate critic evaluations
+        positive_critiques = evaluations.count(&:positive?)
+        total_critiques = evaluations.size
+        confidence = (total_critiques > 0) ? positive_critiques.to_f / total_critiques : 0.5
+
+        comments = evaluations.flat_map(&:comments)
+
+        CriticResult.new(
+          task_id: task.id,
+          confidence: confidence,
+          verdict: confidence >= 0.7, # Pass if 70% or more critics give positive evaluation
+          comments: comments
+        )
+      end
+    end
+
+    # Represents the result of a critic's evaluation
+    class CriticResult
+      # @return [String] The ID of the task that was evaluated
+      attr_reader :task_id
+
+      # @return [Float] The confidence of the evaluation (0.0-1.0)
+      attr_reader :confidence
+
+      # @return [Boolean] The verdict of the evaluation (true = pass, false = fail)
+      attr_reader :verdict
+
+      # @return [Array<String>] Comments from the critic
+      attr_reader :comments
+
+      # Initializes a new CriticResult
+      # @param task_id [String] The ID of the task that was evaluated
+      # @param confidence [Float] The confidence of the evaluation (0.0-1.0)
+      # @param verdict [Boolean] The verdict of the evaluation (true = pass, false = fail)
+      # @param comments [Array<String>] Comments from the critic
+      def initialize(task_id:, confidence:, verdict:, comments: [])
+        @task_id = task_id
+        @confidence = confidence
+        @verdict = verdict
+        @comments = comments
+      end
+
+      # Checks if the evaluation is positive
+      # @return [Boolean] Whether the evaluation is positive
+      def positive?
+        @verdict
+      end
+
+      # Converts the critic result to a hash
+      # @return [Hash] The critic result as a hash
+      def to_h
+        {
+          task_id: @task_id,
+          confidence: @confidence,
+          verdict: @verdict,
+          comments: @comments
+        }
+      end
+    end
+
+    # Base class for critics
+    class Critic
+      # @return [Hash] Configuration options for the critic
+      attr_reader :config
+
+      # Initializes a new Critic
+      # @param config [Hash] Configuration options for the critic
+      def initialize(config = {})
+        @config = config
+      end
+
+      # Critiques a task result
+      # @param task [Task] The task to critique
+      # @param result [TaskResult] The result to critique
+      # @return [CriticResult] The critique result
+      # @raise [NotImplementedError] This method must be implemented by subclasses
+      def critique(task, result)
+        raise NotImplementedError, "Subclasses must implement critique"
+      end
+    end
+  end
+end

data/lib/agentic/verification/llm_verification_strategy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "verification_strategy"
+require_relative "verification_result"
+
+module Agentic
+  module Verification
+    # Verifies task results using an LLM
+    class LlmVerificationStrategy < VerificationStrategy
+      # Initializes a new LlmVerificationStrategy
+      # @param llm_client [LlmClient] The LLM client to use for verification
+      # @param config [Hash] Configuration options for the strategy
+      def initialize(llm_client, config = {})
+        super(config)
+        @llm_client = llm_client
+      end
+
+      # Verifies a task result using an LLM
+      # @param task [Task] The task to verify
+      # @param result [TaskResult] The result to verify
+      # @return [VerificationResult] The verification result
+      def verify(task, result)
+        unless result.successful?
+          return VerificationResult.new(
+            task_id: task.id,
+            verified: false,
+            confidence: 0.0,
+            messages: ["Task failed, skipping LLM verification"]
+          )
+        end
+
+        # In a real implementation, we would send the task and result to the LLM
+        # and analyze the LLM's assessment
+        # For this stub, we'll simulate a response
+
+        # Example verification prompt
+        #   Task Description: #{task.description}
+        #   Task Input: #{task.input.inspect}
+        #   Task Result: #{result.output.inspect}
+        #
+        #   Verify if the result satisfies the task requirements.
+        #   Consider correctness, completeness, and alignment with the task description.
+        #   Provide your assessment with a boolean verdict (verified: true/false) and a confidence score (0.0-1.0).
+
+        # In a real implementation, we would use the LLM client here
+        # For this stub, we'll return a simulated verification result
+        verified = rand > 0.1 # 90% chance of success for simulation purposes
+        confidence = verified ? (0.8 + rand * 0.2) : (0.3 + rand * 0.3)
+        message = verified ? "Result meets task requirements" : "Result does not fully satisfy task requirements"
+
+        VerificationResult.new(
+          task_id: task.id,
+          verified: verified,
+          confidence: confidence,
+          messages: [message]
+        )
+      end
+    end
+  end
+end

data/lib/agentic/verification/schema_verification_strategy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "verification_strategy"
+require_relative "verification_result"
+
+module Agentic
+  module Verification
+    # Verifies task results against a schema
+    class SchemaVerificationStrategy < VerificationStrategy
+      # Verifies a task result against a schema
+      # @param task [Task] The task to verify
+      # @param result [TaskResult] The result to verify
+      # @return [VerificationResult] The verification result
+      def verify(task, result)
+        unless result.successful?
+          return VerificationResult.new(
+            task_id: task.id,
+            verified: false,
+            confidence: 0.0,
+            messages: ["Task failed, skipping schema verification"]
+          )
+        end
+
+        # Extracting schema from task if available
+        schema = task.input["output_schema"] if task.input.is_a?(Hash)
+
+        unless schema
+          return VerificationResult.new(
+            task_id: task.id,
+            verified: true,
+            confidence: 0.5,
+            messages: ["No schema specified for verification, passing by default"]
+          )
+        end
+
+        # In a real implementation, we would validate the output against the schema
+        # For this stub, we'll assume validation passes
+        VerificationResult.new(
+          task_id: task.id,
+          verified: true,
+          confidence: 0.9,
+          messages: ["Output matches expected schema"]
+        )
+      end
+    end
+  end
+end

data/lib/agentic/verification/verification_hub.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Agentic
+  module Verification
+    # Coordinates verification strategies and manages the verification process
+    class VerificationHub
+      # @return [Array<VerificationStrategy>] The registered verification strategies
+      attr_reader :strategies
+
+      # @return [Hash] Configuration options for the verification hub
+      attr_reader :config
+
+      # Initializes a new VerificationHub
+      # @param strategies [Array<VerificationStrategy>] The verification strategies to use
+      # @param config [Hash] Configuration options for the verification hub
+      def initialize(strategies: [], config: {})
+        @strategies = strategies
+        @config = config
+      end
+
+      # Adds a verification strategy
+      # @param strategy [VerificationStrategy] The strategy to add
+      # @return [void]
+      def add_strategy(strategy)
+        @strategies << strategy
+      end
+
+      # Verifies a task result using the registered strategies
+      # @param task [Task] The task to verify
+      # @param result [TaskResult] The result to verify
+      # @return [VerificationResult] The verification result
+      def verify(task, result)
+        # Skip verification for failed tasks
+        if result.failed?
+          return VerificationResult.new(
+            task_id: task.id,
+            verified: false,
+            confidence: 0.0,
+            messages: ["Task failed, skipping verification"]
+          )
+        end
+
+        # Apply all strategies
+        strategy_results = @strategies.map do |strategy|
+          strategy.verify(task, result)
+        end
+
+        # Combine results
+        verified = strategy_results.all?(&:verified)
+        confidence = strategy_results.map(&:confidence).sum / strategy_results.size.to_f
+        messages = strategy_results.flat_map(&:messages)
+
+        VerificationResult.new(
+          task_id: task.id,
+          verified: verified,
+          confidence: confidence,
+          messages: messages
+        )
+      end
+    end
+  end
+end