rcrewai 0.2.1 → 0.4.0

data/lib/rcrewai/task.rb

@@ -2,12 +2,14 @@
 
 require_relative 'async_executor'
 require_relative 'human_input'
+require_relative 'output_schema'
 
 module RCrewAI
   class Task
     include AsyncExtensions
     include HumanInteractionExtensions
-    attr_reader :name, :description, :agent, :context, :expected_output, :tools, :async
+    attr_reader :name, :description, :agent, :context, :expected_output, :tools, :async,
+                :raw_result, :structured_output
     attr_accessor :result, :status, :start_time, :end_time, :execution_time
 
     def initialize(name:, description:, agent: nil, **options)
@@ -19,13 +21,23 @@ module RCrewAI
       @tools = options[:tools] || []      # Additional tools for this specific task
       @async = options[:async] || false   # Whether task can run asynchronously
       @callback = options[:callback]      # Callback function after completion
-      
+
+      # Output processing (0.4.0)
+      @output_schema = options[:output_schema]            # JSON-schema for structured output
+      @guardrail = options[:guardrail]                    # ->(output) { [ok, value_or_error] }
+      @guardrail_max_retries = options.fetch(:guardrail_max_retries, 3)
+      @output_file = options[:output_file]                # Path to write result to
+      @create_directory = options.fetch(:create_directory, true)
+      @markdown = options.fetch(:markdown, false)
+      @raw_result = nil                                   # Unprocessed string content
+      @structured_output = nil                            # Parsed object when output_schema set
+
       # Human interaction options
       @human_input_enabled = options[:human_input] || false
       @require_human_confirmation = options[:require_confirmation] || false
       @allow_human_guidance = options[:allow_guidance] || false
       @human_review_points = options[:human_review_points] || []
-      
+
       @result = nil
       @status = :pending
       @start_time = nil
@@ -53,7 +65,7 @@ module RCrewAI
         if agent
           validate_dependencies!
           provide_context_to_agent
-          
+
           # Enable human input for agent if task allows it
           if @human_input_enabled && agent.respond_to?(:enable_human_input)
             agent.enable_human_input(
@@ -61,31 +73,28 @@ module RCrewAI
               require_approval_for_final_answer: @allow_human_guidance
             )
           end
-          
-          @result = agent.execute_task(self)
-          
+
+          @result = run_agent_with_output_processing
+
           # Post-execution human review if configured
           if @human_input_enabled && @human_review_points.include?(:completion)
             review_result = request_task_completion_review
-            if review_result && !review_result[:approved]
-              @result = handle_completion_review_feedback(review_result)
-            end
+            @result = handle_completion_review_feedback(review_result) if review_result && !review_result[:approved]
           end
-          
+
           @status = :completed
         else
-          @result = "Task requires an agent"
+          @result = 'Task requires an agent'
           @status = :failed
         end
 
         @end_time = Time.now
         @execution_time = @end_time - @start_time
-        
+
         # Execute callback if provided
         @callback&.call(self, @result)
-        
-        @result
 
+        @result
       rescue TaskDependencyError => e
         # Don't retry dependency errors - they need dependencies to be completed first
         @status = :failed
@@ -93,16 +102,16 @@ module RCrewAI
         @execution_time = @end_time - @start_time if @start_time
         @result = "Task dependencies not met: #{e.message}"
         raise e
-      rescue => e
+      rescue StandardError => e
         @status = :failed
         @end_time = Time.now
         @execution_time = @end_time - @start_time if @start_time
-        
+
         # Retry logic with human intervention
         if @retry_count < @max_retries
           @retry_count += 1
           puts "Task #{name} failed, retrying (#{@retry_count}/#{@max_retries})"
-          
+
           # Ask human for retry guidance if enabled
           if @human_input_enabled
             retry_decision = request_retry_guidance(e)
@@ -113,15 +122,13 @@ module RCrewAI
             when 'modify'
               # Allow human to modify task parameters
               modification_result = request_task_modification
-              if modification_result[:modified]
-                apply_task_modifications(modification_result[:changes])
-              end
-            # 'retry' is the default - continue with retry logic
+              apply_task_modifications(modification_result[:changes]) if modification_result[:modified]
+              # 'retry' is the default - continue with retry logic
             end
           end
-          
+
           @status = :pending
-          sleep(2 ** @retry_count) # Exponential backoff
+          sleep(2**@retry_count) # Exponential backoff
           return execute
         end
 
@@ -129,14 +136,12 @@ module RCrewAI
         raise TaskExecutionError, "Task '#{name}' failed: #{e.message}"
       ensure
         # Disable human input for agent after task completion
-        if @human_input_enabled && agent.respond_to?(:disable_human_input)
-          agent.disable_human_input
-        end
+        agent.disable_human_input if @human_input_enabled && agent.respond_to?(:disable_human_input)
       end
     end
 
     def context_data
-      return "" if context.empty?
+      return '' if context.empty?
 
       context_results = context.map do |task|
         if task.completed?
@@ -173,6 +178,12 @@ module RCrewAI
       @context << task unless @context.include?(task)
     end
 
+    # Appends supplementary guidance (e.g. a planning step) to the task's
+    # description without discarding the original instructions.
+    def enrich_description(text)
+      @description = "#{@description}\n\n#{text}"
+    end
+
     def add_tool(tool)
       @tools << tool unless @tools.include?(tool)
     end
@@ -197,16 +208,83 @@ module RCrewAI
 
     private
 
+    # Runs the agent, then applies guardrail validation and schema coercion.
+    # Guardrail/schema failures re-run the agent (up to @guardrail_max_retries)
+    # with the failure fed back in, rather than raising immediately.
+    def run_agent_with_output_processing
+      attempts = 0
+      feedback = nil
+
+      loop do
+        attempts += 1
+        raw = extract_content(agent.execute_task(self))
+        @raw_result = raw
+
+        begin
+          apply_guardrail!(raw)
+          @structured_output = OutputSchema.coerce(raw, @output_schema) if @output_schema
+        rescue OutputProcessingError, OutputSchemaError => e
+          if attempts <= @guardrail_max_retries
+            feedback = e.message
+            append_feedback_to_description(feedback)
+            next
+          end
+          raise
+        end
+
+        write_output_file(guardrail_value_or(raw)) if @output_file
+        return guardrail_value_or(raw)
+      end
+    end
+
+    # Accepts either the legacy plain-string return or the 0.3.0 result hash.
+    def extract_content(agent_result)
+      return agent_result[:content].to_s if agent_result.is_a?(Hash)
+
+      agent_result.to_s
+    end
+
+    def apply_guardrail!(raw)
+      return unless @guardrail
+
+      ok, value = @guardrail.call(raw)
+      raise OutputProcessingError, "guardrail rejected output: #{value}" unless ok
+
+      @guardrail_value = value
+    end
+
+    def guardrail_value_or(raw)
+      @guardrail ? @guardrail_value : raw
+    end
+
+    def append_feedback_to_description(feedback)
+      @description = "#{@description}\n\n[Retry] Previous attempt was rejected: #{feedback}. " \
+                     'Please correct the output.'
+    end
+
+    def write_output_file(content)
+      dir = File.dirname(@output_file)
+      if @create_directory
+        require 'fileutils'
+        FileUtils.mkdir_p(dir)
+      elsif !Dir.exist?(dir)
+        raise OutputProcessingError, "output directory does not exist: #{dir}"
+      end
+
+      body = content.to_s
+      body = "# #{name}\n\n#{body}" if @markdown && !body.lstrip.start_with?('#')
+      File.write(@output_file, body)
+    end
+
     def confirm_task_execution
       message = "Confirm execution of task: #{name}"
       context = "Description: #{description}\nExpected Output: #{expected_output || 'Not specified'}\nAssigned Agent: #{agent&.name || 'No agent'}"
-      consequences = "The task will be executed with the specified agent and may use external tools."
-      
+      consequences = 'The task will be executed with the specified agent and may use external tools.'
+
       request_human_approval(message,
-        context: context,
-        consequences: consequences,
-        timeout: 60
-      )
+                             context: context,
+                             consequences: consequences,
+                             timeout: 60)
     end
 
     def request_task_completion_review
@@ -214,30 +292,30 @@ module RCrewAI
         Task: #{name}
         Description: #{description}
         Expected Output: #{expected_output || 'Not specified'}
-        
+
         Actual Result:
         #{result}
-        
+
         Execution Time: #{execution_time&.round(2)} seconds
         Agent: #{agent&.name || 'Unknown'}
       CONTENT
 
       request_human_review(
         review_content,
-        review_criteria: ["Accuracy", "Completeness", "Meets expectations"],
+        review_criteria: ['Accuracy', 'Completeness', 'Meets expectations'],
         timeout: 120
       )
     end
 
     def handle_completion_review_feedback(review_result)
-      if review_result[:suggested_changes] && review_result[:suggested_changes].any?
+      if review_result[:suggested_changes]&.any?
         # Ask human how to handle the feedback
         choice_result = request_human_choice(
-          "Task completed but received feedback. How should I proceed?",
+          'Task completed but received feedback. How should I proceed?',
           [
-            "Accept result as-is despite feedback",
-            "Request agent revision based on feedback", 
-            "Let me provide the correct result"
+            'Accept result as-is despite feedback',
+            'Request agent revision based on feedback',
+            'Let me provide the correct result'
           ],
           timeout: 60
         )
@@ -247,13 +325,13 @@ module RCrewAI
           result # Return original result
         when 1
           # Request agent to revise (simplified)
-          revised_result = "#{result}\n\nNote: Human feedback received: #{review_result[:feedback]}"
-          revised_result
+          "#{result}\n\nNote: Human feedback received: #{review_result[:feedback]}"
+
         when 2
           # Get corrected result from human
           correction_result = request_human_input(
-            "Please provide the corrected task result:",
-            help_text: "Enter the complete, corrected result for this task"
+            'Please provide the corrected task result:',
+            help_text: 'Enter the complete, corrected result for this task'
           )
           correction_result[:input] || result
         else
@@ -266,9 +344,9 @@ module RCrewAI
 
     def request_retry_guidance(error)
       choices = [
-        "Retry with current settings",
-        "Modify task parameters and retry",
-        "Abort task execution"
+        'Retry with current settings',
+        'Modify task parameters and retry',
+        'Abort task execution'
       ]
 
       choice_result = request_human_choice(
@@ -290,9 +368,9 @@ module RCrewAI
 
     def request_task_modification
       modification_input = request_human_input(
-        "Please specify task modifications (JSON format):",
+        'Please specify task modifications (JSON format):',
         type: :json,
-        help_text: "Provide modifications as JSON, e.g. {\"description\": \"new description\", \"expected_output\": \"new output\"}"
+        help_text: 'Provide modifications as JSON, e.g. {"description": "new description", "expected_output": "new output"}'
       )
 
       if modification_input[:valid]
@@ -316,38 +394,38 @@ module RCrewAI
         when 'expected_output'
           @expected_output = value
         when 'max_retries'
-          @max_retries = value.to_i if value.to_i > 0
+          @max_retries = value.to_i if value.to_i.positive?
         end
       end
     end
 
     def validate_dependencies!
-      unless dependencies_met?
-        incomplete_deps = context.reject(&:completed?).map(&:name)
-        raise TaskDependencyError, "Dependencies not met: #{incomplete_deps.join(', ')}"
-      end
+      return if dependencies_met?
+
+      incomplete_deps = context.reject(&:completed?).map(&:name)
+      raise TaskDependencyError, "Dependencies not met: #{incomplete_deps.join(', ')}"
     end
 
     def provide_context_to_agent
       # Temporarily add task-specific tools to agent
       original_tools = agent.tools.dup
       combined_tools = (agent.tools + @tools).uniq
-      
+
       # Use metaprogramming to temporarily extend agent's tools
       agent.instance_variable_set(:@tools, combined_tools)
-      
+
       # Restore original tools after execution (handled by ensure in execute method)
       at_exit { agent.instance_variable_set(:@tools, original_tools) }
     end
 
     class CLI < Thor
-      desc "new NAME", "Create a new task"
+      desc 'new NAME', 'Create a new task'
       option :description, type: :string, required: true
       option :agent, type: :string
       option :expected_output, type: :string
       option :async, type: :boolean, default: false
       def new(name)
-        task = Task.new(
+        Task.new(
           name: name,
           description: options[:description],
           agent: options[:agent],
@@ -361,16 +439,17 @@ module RCrewAI
         puts "Async: #{options[:async]}"
       end
 
-      desc "list", "List all tasks"
+      desc 'list', 'List all tasks'
       def list
-        puts "Available tasks:"
-        puts "  - research_topic (Agent: researcher)"
-        puts "  - write_article (Agent: writer)"
-        puts "  - analyze_data (Agent: analyst)"
+        puts 'Available tasks:'
+        puts '  - research_topic (Agent: researcher)'
+        puts '  - write_article (Agent: writer)'
+        puts '  - analyze_data (Agent: analyst)'
       end
     end
   end
 
   class TaskExecutionError < Error; end
   class TaskDependencyError < TaskExecutionError; end
-end
+  class OutputProcessingError < TaskExecutionError; end
+end

data/lib/rcrewai/tool_runner.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'events'
+require_relative 'provider_schema'
+
+module RCrewAI
+  class ToolRunner
+    DEFAULT_MAX_ITERATIONS = 10
+
+    def initialize(agent:, llm:, tools:, max_iterations: DEFAULT_MAX_ITERATIONS, event_sink: nil)
+      @agent = agent
+      @llm = llm
+      @tools = tools
+      @tools_by_name = tools.each_with_object({}) { |t, h| h[t.name] = t }
+      @max_iterations = max_iterations
+      @sink = event_sink || ->(_) {}
+    end
+
+    def run(messages:) # rubocop:disable Metrics/AbcSize
+      msgs = messages.dup
+      history = []
+      iter = 0
+      total_usage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+
+      while iter < @max_iterations
+        iter += 1
+        emit(Events::IterationStart, iteration: iter, iteration_index: iter)
+
+        response = @llm.chat(
+          messages: msgs,
+          tools: @tools.map(&:json_schema),
+          stream: ->(e) { @sink.call(retag(e, iter)) }
+        )
+        accumulate_usage(total_usage, response[:usage])
+
+        if response[:tool_calls].nil? || response[:tool_calls].empty?
+          emit(Events::IterationEnd, iteration: iter, finish_reason: response[:finish_reason])
+          return finalize(content: response[:content], history: history, iter: iter,
+                          finish_reason: response[:finish_reason], usage: total_usage)
+        end
+
+        msgs << { role: 'assistant', content: response[:content], tool_calls: response[:tool_calls] }
+
+        response[:tool_calls].each do |tc|
+          tool = @tools_by_name[tc[:name]]
+          emit(Events::ToolCallStart, iteration: iter,
+                                      tool: tc[:name], args: tc[:arguments], call_id: tc[:id])
+
+          if tool.nil?
+            err = "tool not found: #{tc[:name]}"
+            emit(Events::ToolCallError, iteration: iter,
+                                        tool: tc[:name], call_id: tc[:id], error: err)
+            msgs << tool_result_message(tc[:id], "ERROR: #{err}")
+            next
+          end
+
+          started = monotonic_ms
+          begin
+            result = tool.execute_with_validation(tc[:arguments] || {})
+            duration = monotonic_ms - started
+            @agent.memory.add_tool_usage(tc[:name], tc[:arguments], result) if @agent.respond_to?(:memory) && @agent.memory
+            emit(Events::ToolCallResult, iteration: iter,
+                                         tool: tc[:name], call_id: tc[:id], result: result,
+                                         duration_ms: duration)
+            history << { tool: tc[:name], args: tc[:arguments], result: result, duration_ms: duration }
+            msgs << tool_result_message(tc[:id], result.to_s)
+          rescue StandardError => e
+            emit(Events::ToolCallError, iteration: iter,
+                                        tool: tc[:name], call_id: tc[:id], error: e.message)
+            msgs << tool_result_message(tc[:id], "ERROR: #{e.message}")
+          end
+        end
+
+        emit(Events::IterationEnd, iteration: iter, finish_reason: :tool_calls)
+      end
+
+      finalize(content: nil, history: history, iter: iter,
+               finish_reason: :max_iterations, usage: total_usage)
+    end
+
+    private
+
+    def tool_result_message(call_id, content)
+      { role: 'tool', tool_call_id: call_id, content: content }
+    end
+
+    def emit(klass, iteration:, **attrs)
+      type_sym = klass.name.split('::').last
+                      .gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }
+                      .sub(/^_/, '').to_sym
+      @sink.call(klass.new(
+                   type: type_sym,
+                   timestamp: Time.now,
+                   agent: agent_name,
+                   iteration: iteration,
+                   **attrs
+                 ))
+    end
+
+    def agent_name
+      @agent.respond_to?(:name) ? @agent.name : nil
+    end
+
+    def retag(event, iter)
+      event.agent = agent_name if event.respond_to?(:agent=) && event.agent.nil?
+      event.iteration = iter if event.respond_to?(:iteration=) && event.iteration.nil?
+      event
+    end
+
+    def accumulate_usage(total, partial)
+      return unless partial.is_a?(Hash)
+
+      total[:prompt_tokens]     += partial[:prompt_tokens]     || 0
+      total[:completion_tokens] += partial[:completion_tokens] || 0
+      total[:total_tokens]      += partial[:total_tokens]      || 0
+    end
+
+    def finalize(content:, history:, iter:, finish_reason:, usage:)
+      {
+        content: content,
+        tool_calls_history: history,
+        usage: usage,
+        iterations: iter,
+        finish_reason: finish_reason
+      }
+    end
+
+    def monotonic_ms
+      (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) * 1000).to_i
+    end
+  end
+end

data/lib/rcrewai/tool_schema.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  module ToolSchema
+    TYPE_MAP = {
+      string: 'string', integer: 'integer', number: 'number',
+      boolean: 'boolean', array: 'array', object: 'object', enum: 'string'
+    }.freeze
+
+    def self.extended(base)
+      base.instance_variable_set(:@params, [])
+      base.instance_variable_set(:@tool_name, nil)
+      base.instance_variable_set(:@description, nil)
+    end
+
+    def tool_name(name = nil)
+      return @tool_name || name_default if name.nil?
+
+      @tool_name = name.to_s
+    end
+
+    def description(desc = nil)
+      return @description || '' if desc.nil?
+
+      @description = desc.to_s
+    end
+
+    def param(name, type:, required: false, default: nil, description: nil, # rubocop:disable Metrics/ParameterLists
+              items: nil, values: nil, properties: nil)
+      @params ||= []
+      @params << {
+        name: name, type: type, required: required, default: default,
+        description: description, items: items, values: values, properties: properties
+      }
+    end
+
+    def params
+      @params || []
+    end
+
+    def json_schema
+      props = {}
+      required = []
+      params.each do |p|
+        entry = { type: TYPE_MAP.fetch(p[:type]) }
+        entry[:description] = p[:description] if p[:description]
+        entry[:default]     = p[:default]     unless p[:default].nil?
+        entry[:items]       = stringify_type(p[:items])   if p[:items]
+        entry[:enum]        = p[:values]      if p[:type] == :enum
+        entry[:properties]  = p[:properties]  if p[:properties]
+        props[p[:name]] = entry
+        required << p[:name].to_s if p[:required]
+      end
+
+      if params.empty?
+        warn_once_no_dsl!
+        return {
+          name: tool_name,
+          description: description,
+          parameters: { type: 'object', additionalProperties: true }
+        }
+      end
+
+      {
+        name: tool_name,
+        description: description,
+        parameters: {
+          type: 'object',
+          properties: props,
+          required: required
+        }
+      }
+    end
+
+    private
+
+    def name_default
+      raw = name.to_s.split('::').last
+      return '' if raw.nil? || raw.empty?
+
+      raw.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    def stringify_type(hash)
+      return hash unless hash.is_a?(Hash) && hash[:type].is_a?(Symbol)
+
+      hash.merge(type: TYPE_MAP.fetch(hash[:type]))
+    end
+
+    def warn_once_no_dsl!
+      return if @warned_no_dsl
+
+      @warned_no_dsl = true
+      Kernel.warn "[rcrewai] Tool #{name} has no DSL declarations; using permissive schema. Declare tool_name/description/param to opt in to a strict JSON schema."
+    end
+  end
+end