rcrewai 0.3.0 → 0.5.0

data/lib/rcrewai/knowledge/sources.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  module Knowledge
+    # A knowledge source yields plain text via #read. Concrete sources load from
+    # strings, files, PDFs, CSVs, or URLs.
+    class Source
+      def read
+        raise NotImplementedError, 'Subclasses must implement #read'
+      end
+    end
+
+    class StringSource < Source
+      def initialize(text)
+        super()
+        @text = text.to_s
+      end
+
+      def read
+        @text
+      end
+    end
+
+    class FileSource < Source
+      def initialize(path)
+        super()
+        @path = path
+      end
+
+      def read
+        File.read(@path)
+      end
+    end
+
+    class PdfSource < Source
+      def initialize(path)
+        super()
+        @path = path
+      end
+
+      def read
+        require 'pdf-reader'
+        reader = PDF::Reader.new(@path)
+        reader.pages.map(&:text).join("\n")
+      end
+    end
+
+    class CsvSource < Source
+      def initialize(path)
+        super()
+        @path = path
+      end
+
+      def read
+        require 'csv'
+        CSV.read(@path).map { |row| row.join(', ') }.join("\n")
+      end
+    end
+
+    class UrlSource < Source
+      def initialize(url, fetcher: nil)
+        super()
+        @url = url
+        @fetcher = fetcher
+      end
+
+      def read
+        html = @fetcher ? @fetcher.call(@url) : fetch(@url)
+        require 'nokogiri'
+        doc = Nokogiri::HTML(html)
+        doc.search('script, style').remove
+        doc.text.gsub(/\s+/, ' ').strip
+      end
+
+      private
+
+      def fetch(url)
+        require 'faraday'
+        Faraday.get(url).body
+      end
+    end
+  end
+end

data/lib/rcrewai/knowledge/store.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  module Knowledge
+    # In-memory vector store with cosine-similarity search. The default backing
+    # store for Knowledge — no external service required. The interface
+    # (#add, #search) is intentionally small so a Chroma/Qdrant-backed store can
+    # be swapped in later.
+    class Store
+      Entry = Struct.new(:text, :vector)
+
+      def initialize
+        @entries = []
+      end
+
+      def add(text, vector)
+        @entries << Entry.new(text, vector)
+      end
+
+      # Returns the texts of the top-k entries most similar to +query_vector+.
+      def search(query_vector, k: 3)
+        return [] if @entries.empty?
+
+        @entries
+          .map { |e| [e.text, cosine_similarity(query_vector, e.vector)] }
+          .sort_by { |(_text, score)| -score }
+          .first(k)
+          .map(&:first)
+      end
+
+      def size
+        @entries.length
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      def cosine_similarity(a, b)
+        dot = 0.0
+        norm_a = 0.0
+        norm_b = 0.0
+        a.each_index do |i|
+          ai = a[i].to_f
+          bi = (b[i] || 0).to_f
+          dot += ai * bi
+          norm_a += ai * ai
+          norm_b += bi * bi
+        end
+        return 0.0 if norm_a.zero? || norm_b.zero?
+
+        dot / (Math.sqrt(norm_a) * Math.sqrt(norm_b))
+      end
+    end
+  end
+end

data/lib/rcrewai/knowledge.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'knowledge/chunker'
+require_relative 'knowledge/store'
+require_relative 'knowledge/sources'
+require_relative 'knowledge/embedder'
+require_relative 'knowledge/base'
+
+module RCrewAI
+  # Retrieval-augmented knowledge for agents and crews. See Knowledge::Base.
+  module Knowledge
+  end
+end

data/lib/rcrewai/legacy_react_runner.rb

@@ -30,7 +30,7 @@ module RCrewAI
         iter += 1
         emit(Events::IterationStart, iteration: iter, iteration_index: iter)
 
-        response = @llm.chat(messages: msgs)
+        response = @llm.chat(messages: fit_context(msgs))
         accumulate_usage(total_usage, response[:usage])
         reasoning = response[:content] || ''
         last_reasoning = reasoning
@@ -60,6 +60,12 @@ module RCrewAI
 
     private
 
+    # Trims the message list to the model's context window when the agent
+    # supports it; a no-op otherwise.
+    def fit_context(messages)
+      @agent.respond_to?(:fit_context) ? @agent.fit_context(messages) : messages
+    end
+
     def parse_and_execute_actions(reasoning, iter)
       results = []
       iteration_history = []

data/lib/rcrewai/llm_client.rb

@@ -28,6 +28,29 @@ module RCrewAI
       end
     end
 
+    # Resolves a per-agent / per-pass LLM spec into a client.
+    #   nil            -> global provider
+    #   Symbol/String  -> that provider, global model
+    #   Hash           -> { provider:, model:, api_key:, temperature: } overrides
+    #   client object  -> returned as-is (anything responding to #chat)
+    def self.resolve(spec, config = RCrewAI.configuration)
+      case spec
+      when nil
+        for_provider(nil, config)
+      when Symbol, String
+        overridden = config.with_overrides(provider: spec)
+        for_provider(overridden.llm_provider, overridden)
+      when Hash
+        overridden = config.with_overrides(**spec)
+        for_provider(overridden.llm_provider, overridden)
+      else
+        return spec if spec.respond_to?(:chat)
+
+        raise ConfigurationError,
+              "Invalid llm: expected a provider symbol, an options hash, or a client responding to #chat, got #{spec.class}"
+      end
+    end
+
     def self.chat(messages:, **options)
       client = for_provider
       client.chat(messages: messages, **options)

data/lib/rcrewai/multimodal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module RCrewAI
+  # Builds multimodal message content (text + images) in the OpenAI
+  # chat-completions format:
+  #   [{ type: 'text', text: '...' },
+  #    { type: 'image_url', image_url: { url: '...' } }]
+  #
+  # Local image paths are base64-encoded into data URLs; URLs pass through.
+  # Only OpenAI-style multimodal is supported today; other providers raise.
+  module Multimodal
+    SUPPORTED_PROVIDERS = %i[openai azure].freeze
+
+    MIME_TYPES = {
+      '.png' => 'image/png',
+      '.jpg' => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif' => 'image/gif',
+      '.webp' => 'image/webp'
+    }.freeze
+
+    module_function
+
+    # Returns an OpenAI-style content-parts array for the given text and
+    # attachments. With no attachments this is a single text part.
+    def content_parts(text, attachments)
+      parts = [{ type: 'text', text: text.to_s }]
+      Array(attachments).each { |att| parts << image_part(att) }
+      parts
+    end
+
+    def supported_provider?(provider)
+      SUPPORTED_PROVIDERS.include?(provider.to_sym)
+    end
+
+    def ensure_supported_provider!(provider)
+      return if supported_provider?(provider)
+
+      raise UnsupportedProviderError,
+            "multimodal attachments are not supported for provider #{provider}"
+    end
+
+    def image_part(attachment)
+      type = attachment[:type] || attachment['type']
+      raise UnsupportedAttachmentError, "unsupported attachment type: #{type.inspect}" unless type.to_sym == :image
+
+      url = attachment[:url] || attachment['url']
+      path = attachment[:path] || attachment['path']
+      resolved = url || data_url_for(path)
+
+      { type: 'image_url', image_url: { url: resolved } }
+    end
+
+    def data_url_for(path)
+      raise UnsupportedAttachmentError, 'image attachment needs a :url or :path' unless path
+
+      mime = MIME_TYPES[File.extname(path).downcase] || 'application/octet-stream'
+      encoded = Base64.strict_encode64(File.binread(path))
+      "data:#{mime};base64,#{encoded}"
+    end
+
+    class UnsupportedAttachmentError < RCrewAI::Error; end
+    class UnsupportedProviderError < RCrewAI::Error; end
+  end
+end

data/lib/rcrewai/output_schema.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RCrewAI
+  # Validates and coerces a task's raw string output against a JSON-Schema
+  # subset (object / type / required / property types). Used by Task for the
+  # `output_schema:` option. Kept intentionally small: it covers the shapes an
+  # LLM is realistically asked to emit, not the whole JSON Schema spec.
+  module OutputSchema
+    module_function
+
+    # Returns the validated/coerced object.
+    # Raises OutputSchemaError if the string can't be parsed or doesn't conform.
+    def coerce(raw, schema)
+      data = parse(raw)
+      validate!(data, schema)
+      data
+    end
+
+    # Extracts a JSON document from a string that may contain surrounding prose,
+    # then parses it. Prefers a fenced ```json block, then the first balanced
+    # object/array, then the whole string.
+    def parse(raw)
+      candidate = extract_json(raw.to_s)
+      JSON.parse(candidate)
+    rescue JSON::ParserError => e
+      raise OutputSchemaError, "output is not valid JSON: #{e.message}"
+    end
+
+    def extract_json(text)
+      if (fenced = text[/```(?:json)?\s*(\{.*?\}|\[.*?\])\s*```/m, 1])
+        return fenced
+      end
+
+      first = text.index(/[{\[]/)
+      last  = text.rindex(/[}\]]/)
+      return text if first.nil? || last.nil? || last < first
+
+      text[first..last]
+    end
+
+    def validate!(data, schema)
+      type = (schema[:type] || schema['type'])&.to_s
+      case type
+      when 'object' then validate_object!(data, schema)
+      when 'array'  then raise_unless(data.is_a?(Array), 'expected an array')
+      when 'string' then raise_unless(data.is_a?(String), 'expected a string')
+      when 'integer' then raise_unless(data.is_a?(Integer), 'expected an integer')
+      when 'number' then raise_unless(data.is_a?(Numeric), 'expected a number')
+      when 'boolean' then raise_unless([true, false].include?(data), 'expected a boolean')
+      end
+      data
+    end
+
+    def validate_object!(data, schema)
+      raise_unless(data.is_a?(Hash), 'expected a JSON object')
+
+      required = schema[:required] || schema['required'] || []
+      required.each do |key|
+        raise_unless(data.key?(key.to_s), "missing required property '#{key}'")
+      end
+
+      props = schema[:properties] || schema['properties'] || {}
+      props.each do |name, subschema|
+        value = data[name.to_s]
+        next if value.nil?
+
+        validate!(value, subschema)
+      end
+    end
+
+    def raise_unless(condition, message)
+      raise OutputSchemaError, message unless condition
+    end
+  end
+
+  class OutputSchemaError < Error; end
+end

data/lib/rcrewai/planning.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'output_schema'
+
+module RCrewAI
+  # Runs a single planning pass over a crew's tasks before execution. Asks an
+  # LLM to draft a short, concrete plan for each task and folds that plan into
+  # the task's description, so the executing agent starts with a game plan.
+  #
+  # Mirrors CrewAI's `planning=True`. Best-effort: if the planner errors or
+  # returns unparseable output, execution proceeds with the original tasks.
+  class Planning
+    def initialize(crew, llm: nil, logger: nil)
+      @crew = crew
+      @llm = llm || LLMClient.for_provider
+      @logger = logger
+    end
+
+    def plan!
+      return if @crew.tasks.empty?
+
+      plans = request_plans
+      return if plans.nil? || plans.empty?
+
+      @crew.tasks.each do |task|
+        step = plans[task.name] || plans[task.name.to_s]
+        task.enrich_description("Plan: #{step}") if step
+      end
+    rescue StandardError => e
+      @logger&.warn("Planning pass failed, continuing without a plan: #{e.message}")
+      nil
+    end
+
+    private
+
+    def request_plans
+      response = @llm.chat(messages: [
+                             { role: 'system', content: system_prompt },
+                             { role: 'user', content: user_prompt }
+                           ])
+      content = response.is_a?(Hash) ? response[:content].to_s : response.to_s
+      parse_plans(content)
+    end
+
+    def parse_plans(content)
+      OutputSchema.parse(content)
+    rescue OutputSchemaError
+      nil
+    end
+
+    def system_prompt
+      'You are a planning assistant. Given a list of tasks, produce a short, ' \
+        'concrete plan for each. Respond ONLY with a JSON object mapping each ' \
+        'task name to a one-sentence plan string.'
+    end
+
+    def user_prompt
+      lines = @crew.tasks.map do |t|
+        "- #{t.name}: #{t.description} (expected: #{t.expected_output || 'n/a'})"
+      end
+      "Tasks:\n#{lines.join("\n")}\n\nReturn JSON: { \"<task name>\": \"<plan>\", ... }"
+    end
+  end
+end

data/lib/rcrewai/rate_limiter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RCrewAI
+  # Thread-safe requests-per-minute throttle. Records call timestamps in a
+  # rolling 60-second window; `acquire` blocks (sleeps) until a slot is free.
+  #
+  # The clock and sleeper are injectable so tests can drive time deterministically
+  # without touching the wall clock. `max_rpm` of nil or 0 means unlimited.
+  class RateLimiter
+    WINDOW = 60.0
+
+    def initialize(max_rpm:, clock: nil, sleeper: nil)
+      @max_rpm = max_rpm
+      @clock = clock || -> { current_time }
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @calls = []
+      @mutex = Mutex.new
+    end
+
+    # Blocks until making a call would keep us within max_rpm, then records it.
+    def acquire
+      return record_unlimited if unlimited?
+
+      loop do
+        wait = @mutex.synchronize do
+          prune(@clock.call)
+          if @calls.length < @max_rpm
+            @calls << @clock.call
+            return
+          end
+          # Time until the oldest in-window call ages out.
+          (@calls.first + WINDOW) - @clock.call
+        end
+
+        @sleeper.call(wait) if wait.positive?
+      end
+    end
+
+    # Number of calls currently inside the window (useful for tests/metrics).
+    def recent_count
+      @mutex.synchronize do
+        prune(@clock.call)
+        @calls.length
+      end
+    end
+
+    private
+
+    def unlimited?
+      @max_rpm.nil? || @max_rpm.zero?
+    end
+
+    def record_unlimited
+      @mutex.synchronize { @calls << @clock.call }
+      nil
+    end
+
+    def prune(now)
+      cutoff = now - WINDOW
+      @calls.reject! { |t| t <= cutoff }
+    end
+
+    def current_time
+      # Fully-qualified: bare `Process` would resolve to RCrewAI::Process here.
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    # Wraps an LLM client so every #chat acquires a rate-limiter slot first.
+    # All other messages delegate to the wrapped client unchanged.
+    class ThrottledClient
+      def initialize(client, limiter)
+        @client = client
+        @limiter = limiter
+      end
+
+      def chat(**kwargs, &block)
+        @limiter.acquire
+        @client.chat(**kwargs, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private)
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        if @client.respond_to?(name)
+          @client.public_send(name, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

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, :attachments
     attr_accessor :result, :status, :start_time, :end_time, :execution_time
 
     def initialize(name:, description:, agent: nil, **options)
@@ -19,6 +21,17 @@ 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
+      @attachments = options[:attachments] || [] # Multimodal inputs (images)
+
+      # 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
@@ -62,7 +75,7 @@ module RCrewAI
             )
           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)
@@ -166,6 +179,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
@@ -190,6 +209,74 @@ 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'}"
@@ -365,4 +452,5 @@ module RCrewAI
 
   class TaskExecutionError < Error; end
   class TaskDependencyError < TaskExecutionError; end
+  class OutputProcessingError < TaskExecutionError; end
 end

data/lib/rcrewai/tool_runner.rb

@@ -27,7 +27,7 @@ module RCrewAI
         emit(Events::IterationStart, iteration: iter, iteration_index: iter)
 
         response = @llm.chat(
-          messages: msgs,
+          messages: fit_context(msgs),
           tools: @tools.map(&:json_schema),
           stream: ->(e) { @sink.call(retag(e, iter)) }
         )
@@ -80,6 +80,12 @@ module RCrewAI
 
     private
 
+    # Trims the message list to the model's context window when the agent
+    # supports it; a no-op otherwise.
+    def fit_context(messages)
+      @agent.respond_to?(:fit_context) ? @agent.fit_context(messages) : messages
+    end
+
     def tool_result_message(call_id, content)
       { role: 'tool', tool_call_id: call_id, content: content }
     end

data/lib/rcrewai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RCrewAI
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/rcrewai.rb

@@ -23,6 +23,10 @@ require_relative 'rcrewai/sse_parser'
 require_relative 'rcrewai/pricing'
 require_relative 'rcrewai/llm_client'
 require_relative 'rcrewai/memory'
+require_relative 'rcrewai/rate_limiter'
+require_relative 'rcrewai/context_window'
+require_relative 'rcrewai/multimodal'
+require_relative 'rcrewai/knowledge'
 require_relative 'rcrewai/human_input'
 require_relative 'rcrewai/tool_schema'
 require_relative 'rcrewai/provider_schema'
@@ -41,4 +45,5 @@ require_relative 'rcrewai/async_executor'
 require_relative 'rcrewai/agent'
 require_relative 'rcrewai/task'
 require_relative 'rcrewai/crew'
+require_relative 'rcrewai/flow'
 require_relative 'rcrewai/mcp'