rcrewai 0.3.0 → 0.5.0

data/lib/rcrewai/crew.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'logger'
 require_relative 'process'
 require_relative 'async_executor'
 require_relative 'events'
+require_relative 'planning'
 
 module RCrewAI
   class Crew
@@ -17,10 +19,37 @@ module RCrewAI
       @process_type = options.fetch(:process, :sequential)
       @verbose = options.fetch(:verbose, false)
       @max_iterations = options.fetch(:max_iterations, 10)
+      @planning = options.fetch(:planning, false)
+      @planning_llm = options[:planning_llm]
+      @planned = false
+      @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
+      @before_kickoff_hooks = []
+      @after_kickoff_hooks = []
+      @last_inputs = {}
       @process_instance = nil
       validate_process_type!
     end
 
+    attr_reader :knowledge, :stream_sink, :last_inputs
+
+    def planning?
+      @planning
+    end
+
+    # Register a callback run before execution. Receives the inputs hash and may
+    # return a transformed hash. Multiple hooks run in registration order.
+    def before_kickoff(&block)
+      @before_kickoff_hooks << block
+      self
+    end
+
+    # Register a callback run after execution. Receives the result and may
+    # return a transformed result. Multiple hooks run in registration order.
+    def after_kickoff(&block)
+      @after_kickoff_hooks << block
+      self
+    end
+
     def add_agent(agent)
       @agents << agent
     end
@@ -29,20 +58,55 @@ module RCrewAI
       @tasks << task
     end
 
-    def execute(async: false, stream: nil, **async_options, &block)
+    def execute(async: false, stream: nil, inputs: {}, **async_options, &block)
       sinks = []
       sinks << block if block_given?
       Array(stream).each { |s| sinks << s } if stream
       @stream_sink = sinks.empty? ? nil : RCrewAI::Events.fan_out(sinks)
 
-      if async
-        execute_async(**async_options)
-      else
-        execute_sync
+      run_before_hooks(inputs)
+
+      distribute_knowledge if @knowledge
+      run_planning_pass if planning?
+
+      result = async ? execute_async(**async_options) : execute_sync
+      run_after_hooks(result)
+    end
+
+    # Runs the crew once per input set, returning one result per input in order.
+    # Runs are isolated: each execution starts from only its own inputs.
+    def kickoff_for_each(inputs:)
+      Array(inputs).map { |input| execute(inputs: input) }
+    end
+
+    # Runs the crew repeatedly, collecting feedback after each iteration and
+    # persisting it to +filename+ as JSON. +feedback+ is a callable
+    # ->(iteration, result) { "..." }; it defaults to prompting a human.
+    # Mirrors CrewAI's crew.train.
+    def train(n_iterations:, filename:, feedback: nil)
+      feedback ||= method(:default_training_feedback)
+      entries = []
+
+      (1..n_iterations).each do |iteration|
+        result = execute
+        note = feedback.call(iteration, result)
+        entries << { iteration: iteration, feedback: note }
       end
+
+      write_training_file(filename, entries)
+      { iterations: n_iterations, filename: filename, entries: entries }
     end
 
-    attr_reader :stream_sink
+    # Runs the crew repeatedly and scores each run. +scorer+ is a callable
+    # ->(result) { Float }; it defaults to the run's success_rate.
+    # Mirrors CrewAI's crew.test.
+    def test(n_iterations:, scorer: nil, model: nil) # rubocop:disable Lint/UnusedMethodArgument
+      scorer ||= ->(result) { result[:success_rate].to_f }
+      scores = (1..n_iterations).map { scorer.call(execute) }
+      average = scores.empty? ? 0.0 : (scores.sum / scores.length).round(2)
+
+      { iterations: n_iterations, scores: scores, average_score: average }
+    end
 
     def execute_async(**options)
       puts "Executing crew: #{name} (async #{process_type} process)"
@@ -102,6 +166,58 @@ module RCrewAI
 
     private
 
+    def run_before_hooks(inputs)
+      # Assign before running hooks so a hook that reads #last_inputs sees this
+      # run's own inputs; update it as each hook transforms them.
+      @last_inputs = inputs || {}
+      @before_kickoff_hooks.each do |hook|
+        @last_inputs = hook.call(@last_inputs) || @last_inputs
+      end
+      @last_inputs
+    end
+
+    def run_after_hooks(result)
+      @after_kickoff_hooks.reduce(result) do |acc, hook|
+        hook.call(acc) || acc
+      end
+    end
+
+    def build_knowledge(knowledge, sources)
+      return knowledge if knowledge
+      return nil if sources.nil? || sources.empty?
+
+      Knowledge::Base.new(sources: sources)
+    end
+
+    def distribute_knowledge
+      @knowledge.build!
+      agents.each { |agent| agent.crew_knowledge = @knowledge if agent.respond_to?(:crew_knowledge=) }
+    end
+
+    def default_training_feedback(iteration, _result)
+      require_relative 'human_input'
+      response = HumanInput.new.request_input(
+        "Feedback for training iteration #{iteration} (press enter to skip):"
+      )
+      response.is_a?(Hash) ? response[:input].to_s : response.to_s
+    end
+
+    def write_training_file(filename, entries)
+      require 'json'
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(filename))
+      File.write(filename, JSON.pretty_generate(entries))
+    end
+
+    def run_planning_pass
+      return if @planned
+
+      logger = Logger.new($stdout)
+      logger.level = verbose ? Logger::DEBUG : Logger::INFO
+      Planning.new(self, llm: LLMClient.resolve(@planning_llm), logger: logger).plan!
+      @planned = true
+    end
+
     def validate_process_type!
       valid_processes = %i[sequential hierarchical consensual]
       return if valid_processes.include?(process_type)

data/lib/rcrewai/flow/state.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module RCrewAI
+  class Flow
+    # Mutable, schemaless flow state with a stable unique id. Access attributes
+    # as methods (state.foo, state.foo = 1) or via [] / to_h. Mirrors CrewAI's
+    # unstructured (dict-based) flow state, with an automatic UUID.
+    class State
+      def initialize(attributes = {})
+        @attributes = {}
+        attributes.each { |k, v| @attributes[k.to_sym] = v }
+        @attributes[:id] ||= SecureRandom.uuid
+      end
+
+      def id
+        @attributes[:id]
+      end
+
+      def [](key)
+        @attributes[key.to_sym]
+      end
+
+      def []=(key, value)
+        @attributes[key.to_sym] = value
+      end
+
+      def to_h
+        @attributes.dup
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      def method_missing(name, *args)
+        key = name.to_s
+        if key.end_with?('=')
+          @attributes[key[0..-2].to_sym] = args.first
+        else
+          @attributes[name]
+        end
+      end
+    end
+  end
+end

data/lib/rcrewai/flow/state_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RCrewAI
+  class Flow
+    # Persists flow state keyed by state id, so a flow can be resumed across
+    # restarts. Two built-ins: in-memory (tests / single process) and file-based
+    # (JSON on disk). Any object with #save(id, hash) and #load(id) works.
+    class MemoryStateStore
+      def initialize
+        @data = {}
+      end
+
+      def save(id, hash)
+        @data[id] = hash.dup
+      end
+
+      def load(id)
+        @data[id]
+      end
+    end
+
+    # Stores each state as a JSON file named <id>.json under a directory.
+    class FileStateStore
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def save(id, hash)
+        File.write(path_for(id), JSON.pretty_generate(hash))
+      end
+
+      def load(id)
+        path = path_for(id)
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      private
+
+      def path_for(id)
+        File.join(@dir, "#{id}.json")
+      end
+    end
+  end
+end

data/lib/rcrewai/flow.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require_relative 'flow/state'
+require_relative 'flow/state_store'
+
+module RCrewAI
+  # Event-driven workflow engine — CrewAI's second pillar, in Ruby.
+  #
+  # Subclass Flow and declare methods with the class-level DSL:
+  #
+  #   class GuideFlow < RCrewAI::Flow
+  #     start :pick_topic
+  #     def pick_topic = state.topic = 'ruby'
+  #
+  #     listen :pick_topic
+  #     def research(prev) = "researched #{prev}"
+  #
+  #     router :research
+  #     def route(prev) = prev.include?('ruby') ? :publish : :revise
+  #
+  #     listen :publish
+  #     def publish = state.done = true
+  #   end
+  #
+  #   GuideFlow.new.kickoff
+  #
+  # Triggers combine with and_/or_. State is a schemaless object with a UUID and
+  # can be persisted/restored via a state store.
+  class Flow
+    # --- Trigger descriptors -------------------------------------------------
+    Trigger = Struct.new(:mode, :names) do
+      def satisfied_by?(completed)
+        case mode
+        when :single, :or then names.any? { |n| completed.include?(n) }
+        when :and then names.all? { |n| completed.include?(n) }
+        end
+      end
+    end
+
+    # --- Class-level DSL -----------------------------------------------------
+    class << self
+      def start_methods
+        @start_methods ||= []
+      end
+
+      # name => Trigger. Populated when a listen/router declaration is bound to
+      # the next defined method.
+      def listeners
+        @listeners ||= {}
+      end
+
+      def routers
+        @routers ||= {}
+      end
+
+      def start(method_name)
+        start_methods << method_name.to_sym
+      end
+
+      def listen(trigger)
+        @pending = [:listen, normalize_trigger(trigger)]
+      end
+
+      def router(trigger)
+        @pending = [:router, normalize_trigger(trigger)]
+      end
+
+      def or_(*names)
+        Trigger.new(:or, names.map(&:to_sym))
+      end
+
+      def and_(*names)
+        Trigger.new(:and, names.map(&:to_sym))
+      end
+
+      # Binds a pending listen/router declaration to the method just defined.
+      def method_added(method_name)
+        super
+        return unless @pending
+
+        kind, trigger = @pending
+        @pending = nil
+        case kind
+        when :listen then listeners[method_name.to_sym] = trigger
+        when :router then routers[method_name.to_sym] = trigger
+        end
+      end
+
+      # Merge inherited declarations so subclasses of a Flow subclass compose.
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@start_methods, start_methods.dup)
+        subclass.instance_variable_set(:@listeners, listeners.dup)
+        subclass.instance_variable_set(:@routers, routers.dup)
+      end
+
+      private
+
+      def normalize_trigger(trigger)
+        return trigger if trigger.is_a?(Trigger)
+
+        Trigger.new(:single, [trigger.to_sym])
+      end
+    end
+
+    # --- Instance ------------------------------------------------------------
+    attr_reader :state
+
+    def initialize(state_store: nil, feedback_handler: nil)
+      @state = State.new
+      @state_store = state_store
+      @feedback_handler = feedback_handler
+    end
+
+    # A pause point for human feedback. Calls the configured feedback_handler
+    # with the prompt and returns its response; without a handler, prompts on
+    # the console. Mirrors CrewAI's @human_feedback.
+    def human_feedback(prompt)
+      return @feedback_handler.call(prompt) if @feedback_handler
+
+      require_relative 'human_input'
+      response = HumanInput.new.request_input(prompt)
+      response.is_a?(Hash) ? response[:input] : response
+    end
+
+    # Runs the flow to completion. Optional inputs seed the state.
+    def kickoff(inputs: {})
+      inputs.each { |k, v| @state[k] = v }
+
+      @completed = []       # method names that have finished
+      @outputs = {}         # method name => return value
+      @router_labels = []   # labels emitted by routers, act as pseudo-triggers
+
+      self.class.start_methods.each { |m| run_method(m) }
+      drain_listeners
+
+      persist
+      @state
+    end
+
+    # Restores state previously persisted under +id+.
+    def restore(id)
+      raise FlowError, 'no state store configured' unless @state_store
+
+      hash = @state_store.load(id)
+      raise FlowError, "no persisted state for id #{id}" unless hash
+
+      @state = State.new(symbolize(hash))
+      @state
+    end
+
+    private
+
+    def run_method(method_name)
+      trigger = self.class.listeners[method_name] || self.class.routers[method_name]
+      arg = trigger ? @outputs[last_trigger_name(trigger)] : nil
+
+      result = arity_for(method_name).zero? ? send(method_name) : send(method_name, arg)
+
+      @completed << method_name
+      @outputs[method_name] = result
+
+      # A router's return value becomes a label that listeners can trigger on.
+      @router_labels << result.to_sym if self.class.routers.key?(method_name) && result
+    end
+
+    # Repeatedly fire any listeners/routers whose triggers are now satisfied,
+    # until no new method runs (fixed point).
+    def drain_listeners
+      reactive = self.class.listeners.merge(self.class.routers)
+      loop do
+        ran = false
+        reactive.each do |method_name, trigger|
+          next if fired_enough?(method_name, trigger)
+
+          if trigger.satisfied_by?(satisfied_set)
+            run_listener(method_name, trigger)
+            ran = true
+          end
+        end
+        break unless ran
+      end
+    end
+
+    # For :single/:or triggers we fire once per completed trigger name; for :and
+    # we fire once. Track how many times each listener has fired.
+    def run_listener(method_name, trigger)
+      @fired ||= Hash.new { |h, k| h[k] = [] }
+
+      case trigger.mode
+      when :and
+        @fired[method_name] << :once
+        invoke_listener(method_name, @outputs[trigger.names.last])
+      else
+        pending = trigger.names.select { |n| satisfied_set.include?(n) } - @fired[method_name]
+        pending.each do |name|
+          @fired[method_name] << name
+          invoke_listener(method_name, @outputs[name])
+        end
+      end
+    end
+
+    def invoke_listener(method_name, arg)
+      result = arity_for(method_name).zero? ? send(method_name) : send(method_name, arg)
+      @completed << method_name
+      @outputs[method_name] = result
+      @router_labels << result.to_sym if self.class.routers.key?(method_name) && result
+    end
+
+    def fired_enough?(method_name, trigger)
+      @fired ||= Hash.new { |h, k| h[k] = [] }
+      case trigger.mode
+      when :and then @fired[method_name].any?
+      else (trigger.names & satisfied_set).all? { |n| @fired[method_name].include?(n) }
+      end
+    end
+
+    # Names available to satisfy triggers: completed methods + router labels.
+    def satisfied_set
+      @completed + @router_labels
+    end
+
+    def last_trigger_name(trigger)
+      (trigger.names & @completed).last || trigger.names.last
+    end
+
+    def arity_for(method_name)
+      method(method_name).arity
+    end
+
+    def persist
+      return unless @state_store
+
+      @state_store.save(@state.id, @state.to_h)
+    end
+
+    def symbolize(hash)
+      hash.transform_keys(&:to_sym)
+    end
+  end
+
+  class FlowError < Error; end
+end

data/lib/rcrewai/knowledge/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'chunker'
+require_relative 'store'
+require_relative 'sources'
+require_relative 'embedder'
+
+module RCrewAI
+  module Knowledge
+    # A knowledge base: loads sources, chunks their text, embeds the chunks, and
+    # answers similarity queries. Attach one to an Agent (role-specific) or a
+    # Crew (shared) via the +knowledge_sources:+ option.
+    class Base
+      attr_reader :sources
+
+      def initialize(sources: [], embedder: nil, chunk_size: 1000, overlap: 100)
+        @sources = Array(sources)
+        @embedder = embedder || Embedder.new
+        @chunker = Chunker.new(chunk_size: chunk_size, overlap: overlap)
+        @store = Store.new
+        @built = false
+      end
+
+      # Loads, chunks, and embeds all sources. Idempotent.
+      def build!
+        return self if @built
+
+        chunks = @sources.flat_map { |source| @chunker.chunk(source.read) }
+        unless chunks.empty?
+          vectors = @embedder.embed(chunks)
+          chunks.zip(vectors).each { |text, vector| @store.add(text, vector) }
+        end
+
+        @built = true
+        self
+      end
+
+      # Returns up to k chunks most relevant to the query string.
+      def search(query, k: 3)
+        build! unless @built
+        return [] if @store.empty?
+
+        query_vector = @embedder.embed([query]).first
+        @store.search(query_vector, k: k)
+      end
+
+      def empty?
+        @sources.empty?
+      end
+    end
+  end
+end

data/lib/rcrewai/knowledge/chunker.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  module Knowledge
+    # Splits text into fixed-size, overlapping character windows. Overlap keeps
+    # context from spilling across chunk boundaries during retrieval.
+    class Chunker
+      def initialize(chunk_size: 1000, overlap: 100)
+        raise ArgumentError, 'overlap must be smaller than chunk_size' if overlap >= chunk_size
+
+        @chunk_size = chunk_size
+        @overlap = overlap
+      end
+
+      def chunk(text)
+        text = text.to_s
+        return [] if text.empty?
+        return [text] if text.length <= @chunk_size
+
+        chunks = []
+        start = 0
+        step = @chunk_size - @overlap
+        while start < text.length
+          chunks << text[start, @chunk_size]
+          start += step
+        end
+        chunks
+      end
+    end
+  end
+end

data/lib/rcrewai/knowledge/embedder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday'
+
+module RCrewAI
+  module Knowledge
+    # Turns text into embedding vectors. Defaults to OpenAI's embeddings API;
+    # #embed takes an array of strings and returns an array of vectors. Any
+    # object responding to #embed can be substituted (see specs).
+    class Embedder
+      DEFAULT_MODEL = 'text-embedding-3-small'
+      OPENAI_URL = 'https://api.openai.com/v1/embeddings'
+
+      def initialize(model: DEFAULT_MODEL, api_key: nil, config: RCrewAI.configuration)
+        @model = model
+        @api_key = api_key || config.openai_api_key || config.api_key
+      end
+
+      def embed(texts)
+        texts = Array(texts)
+        return [] if texts.empty?
+
+        response = connection.post(OPENAI_URL) do |req|
+          req.headers['Authorization'] = "Bearer #{@api_key}"
+          req.headers['Content-Type'] = 'application/json'
+          req.body = JSON.generate(model: @model, input: texts)
+        end
+
+        raise EmbeddingError, "embedding request failed: #{response.status}" unless response.success?
+
+        body = response.body
+        body = JSON.parse(body) if body.is_a?(String)
+        body['data'].map { |d| d['embedding'] }
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new do |f|
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+
+    class EmbeddingError < RCrewAI::Error; end
+  end
+end