rcrewai 0.7.1 → 0.8.0

data/lib/rcrewai/crew.rb

@@ -28,10 +28,14 @@ module RCrewAI
       @after_kickoff_hooks = []
       @last_inputs = {}
       @process_instance = nil
+      @checkpoint_store = options[:checkpoint]
+      @run_id = nil
+      @parent_run_id = nil
+      @completed_from_checkpoint = {}
       validate_process_type!
     end
 
-    attr_reader :knowledge, :stream_sink, :last_inputs, :consensus_agents
+    attr_reader :knowledge, :stream_sink, :last_inputs, :consensus_agents, :run_id
 
     def planning?
       @planning
@@ -59,13 +63,16 @@ module RCrewAI
       @tasks << task
     end
 
-    def execute(async: false, stream: nil, inputs: {}, **async_options, &block)
+    def execute(async: false, stream: nil, inputs: {}, checkpoint: nil, **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)
       @tasks.each { |t| t.stream_sink = @stream_sink }
 
+      @checkpoint_store = checkpoint if checkpoint
+      open_checkpoint_run if @checkpoint_store
+
       run_before_hooks(inputs)
 
       distribute_knowledge if @knowledge
@@ -80,6 +87,44 @@ module RCrewAI
       @tasks.each { |t| t.stream_sink = nil }
     end
 
+    # Resumes a checkpointed run: tasks that already completed replay their
+    # stored results, and only the rest execute. The resumed run gets its own
+    # run id linked to +run_id+ via parent_run_id, so the original record stays
+    # intact and the chain stays walkable.
+    def resume(run_id, checkpoint: nil, **options)
+      store = checkpoint || @checkpoint_store
+      raise Checkpoint::CheckpointError, 'no checkpoint store configured' unless store
+
+      record = store.load(run_id)
+      raise Checkpoint::CheckpointError, "no checkpoint for run id #{run_id}" unless record
+
+      @checkpoint_store = store
+      @parent_run_id = run_id
+      @completed_from_checkpoint = completed_entries(record)
+      apply_checkpoint(@completed_from_checkpoint)
+
+      execute(**options)
+    end
+
+    # Tasks whose results came from a checkpoint rather than this run.
+    def restored_task_names
+      @completed_from_checkpoint.keys
+    end
+
+    # Records one task's settled state and flushes the run record. Called by
+    # Process as each task finishes, so a crash loses at most the task in
+    # flight rather than the whole run.
+    def checkpoint_task(task, status)
+      return unless @checkpoint_store
+
+      @checkpoint_tasks[task.name] = Checkpoint.task_entry(task, status)
+      write_checkpoint
+    end
+
+    def checkpointing?
+      !@checkpoint_store.nil?
+    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:)
@@ -173,6 +218,41 @@ module RCrewAI
 
     private
 
+    def open_checkpoint_run
+      @run_id = Checkpoint.new_run_id
+      @checkpoint_tasks = {}
+      # Carry restored entries into the new record so it describes the whole
+      # run, not just the tasks this process happened to execute.
+      @completed_from_checkpoint.each { |name, entry| @checkpoint_tasks[name] = entry }
+      write_checkpoint
+    end
+
+    def write_checkpoint
+      @checkpoint_store.save(
+        @run_id,
+        Checkpoint.record_for(run_id: @run_id, crew_name: @name,
+                              tasks: @checkpoint_tasks, parent_run_id: @parent_run_id)
+      )
+    end
+
+    def completed_entries(record)
+      (record['tasks'] || {}).select { |_name, entry| entry['status'] == 'completed' }
+    end
+
+    # Replays stored results onto the matching tasks so downstream tasks can
+    # still read their context. A checkpointed name with no matching task is
+    # ignored: the crew may legitimately have been rebuilt differently.
+    def apply_checkpoint(entries)
+      @tasks.each do |task|
+        entry = entries[task.name]
+        next unless entry
+
+        task.result = entry['result']
+        task.status = :completed
+        task.execution_time = entry['execution_time']
+      end
+    end
+
     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.

data/lib/rcrewai/events.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module RCrewAI
   module Events
-    BASE_ATTRS = %i[type timestamp agent iteration].freeze
+    # Every event carries its own :id and, when emitted inside a
+    # +with_parent+ scope, the :parent_id of the enclosing span. Together these
+    # turn a flat event stream into a tree that a subscriber can reassemble --
+    # which is what tracing exporters need.
+    BASE_ATTRS = %i[type timestamp agent iteration id parent_id].freeze
 
     Event           = Struct.new(*BASE_ATTRS, keyword_init: true)
     TextDelta       = Struct.new(*BASE_ATTRS, :text,                                  keyword_init: true)
@@ -16,15 +22,75 @@ module RCrewAI
     IterationEnd    = Struct.new(*BASE_ATTRS, :finish_reason,                         keyword_init: true)
     Error           = Struct.new(*BASE_ATTRS, :error,                                 keyword_init: true)
 
+    # Auto-assign an :id to any event that did not supply one. Struct's
+    # keyword_init initializer is wrapped rather than replaced so every event
+    # type gets this without restating the attribute list.
+    [Event, TextDelta, TextDone, ToolCallStart, ToolCallResult, ToolCallError,
+     Thinking, Usage, IterationStart, IterationEnd, Error].each do |klass|
+      klass.prepend(Module.new do
+        def initialize(**kwargs)
+          kwargs[:id] ||= SecureRandom.uuid
+          super(**kwargs)
+        end
+      end)
+    end
+
+    PARENT_KEY = :rcrewai_event_parent
+
+    # Runs the block with +id+ as the parent span for any event emitted through
+    # +emit+ on this thread. Scopes nest and are restored on exit, including
+    # when the block raises. Thread-local: a child thread starts with no parent
+    # rather than inheriting one, since it is a separate branch of work.
+    def self.with_parent(id)
+      previous = Thread.current[PARENT_KEY]
+      Thread.current[PARENT_KEY] = id
+      yield
+    ensure
+      Thread.current[PARENT_KEY] = previous
+    end
+
+    def self.current_parent
+      Thread.current[PARENT_KEY]
+    end
+
+    # Stamps the enclosing parent span onto the event (unless it already names
+    # one) and hands it to the sink.
+    def self.emit(sink, event)
+      return event if sink.nil?
+
+      event.parent_id ||= current_parent
+      sink.call(event)
+      event
+    end
+
+    # Wraps one or more sinks in a single callable.
+    #
+    # Delivery is serialized: sinks are invoked under a mutex, so a sink shared
+    # by concurrently executing agents is never entered from two threads at
+    # once and does not need locking of its own. The lock is reentrant, so a
+    # sink that emits back through the same fan-out does not deadlock.
+    #
+    # A sink that raises is reported and skipped -- one bad subscriber must not
+    # take down the run or starve the others.
     def self.fan_out(sinks)
       sinks = Array(sinks).compact
+      mutex = Mutex.new
       lambda do |event|
-        sinks.each do |s|
-          s.call(event)
-        rescue StandardError => e
-          Kernel.warn "[rcrewai] event sink raised: #{e.class}: #{e.message}"
+        if mutex.owned?
+          deliver(sinks, event)
+        else
+          mutex.synchronize { deliver(sinks, event) }
         end
       end
     end
+
+    def self.deliver(sinks, event)
+      sinks.each do |s|
+        s.call(event)
+      rescue StandardError => e
+        Kernel.warn "[rcrewai] event sink raised: #{e.class}: #{e.message}"
+      end
+    end
+    private_class_method :deliver
   end
 end

data/lib/rcrewai/legacy_react_runner.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'securerandom'
 require_relative 'events'
 
 module RCrewAI
@@ -19,6 +20,12 @@ module RCrewAI
     end
 
     def run(messages:)
+      Events.with_parent(@run_span_id ||= SecureRandom.uuid) { run_loop(messages: messages) }
+    end
+
+    private
+
+    def run_loop(messages:)
       msgs = messages.dup
       history = []
       iter = 0
@@ -58,8 +65,6 @@ module RCrewAI
                finish_reason: :max_iterations, usage: total_usage)
     end
 
-    private
-
     # Trims the message list to the model's context window when the agent
     # supports it; a no-op otherwise.
     def fit_context(messages)
@@ -144,13 +149,13 @@ module RCrewAI
       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.respond_to?(:name) ? @agent.name : nil,
-                   iteration: iteration,
-                   **attrs
-                 ))
+      Events.emit(@sink, klass.new(
+                           type: type_sym,
+                           timestamp: Time.now,
+                           agent: @agent.respond_to?(:name) ? @agent.name : nil,
+                           iteration: iteration,
+                           **attrs
+                         ))
     end
 
     def accumulate_usage(total, partial)

data/lib/rcrewai/llm_client.rb

@@ -6,26 +6,31 @@ require_relative 'llm_clients/anthropic'
 require_relative 'llm_clients/google'
 require_relative 'llm_clients/azure'
 require_relative 'llm_clients/ollama'
+require_relative 'llm_clients/openai_compatible'
+require_relative 'llm_clients/bedrock'
+require_relative 'llm_clients/snowflake_cortex'
+require_relative 'llm_clients/openai_responses'
 
 module RCrewAI
   class LLMClient
-    def self.for_provider(provider = nil, config = RCrewAI.configuration)
+    PROVIDERS = {
+      openai: LLMClients::OpenAI,
+      anthropic: LLMClients::Anthropic,
+      google: LLMClients::Google,
+      azure: LLMClients::Azure,
+      ollama: LLMClients::Ollama,
+      openai_compatible: LLMClients::OpenAICompatible,
+      bedrock: LLMClients::Bedrock,
+      snowflake: LLMClients::SnowflakeCortex,
+      openai_responses: LLMClients::OpenAIResponses
+    }.freeze
+
+    def self.for_provider(provider = nil, config = RCrewAI.configuration, **hooks)
       provider ||= config.llm_provider
+      klass = PROVIDERS[provider.to_sym]
+      raise ConfigurationError, "Unsupported provider: #{provider}" unless klass
 
-      case provider.to_sym
-      when :openai
-        LLMClients::OpenAI.new(config)
-      when :anthropic
-        LLMClients::Anthropic.new(config)
-      when :google
-        LLMClients::Google.new(config)
-      when :azure
-        LLMClients::Azure.new(config)
-      when :ollama
-        LLMClients::Ollama.new(config)
-      else
-        raise ConfigurationError, "Unsupported provider: #{provider}"
-      end
+      klass.new(config, **hooks)
     end
 
     # Resolves a per-agent / per-pass LLM spec into a client.

data/lib/rcrewai/llm_clients/anthropic.rb

@@ -21,8 +21,8 @@ module RCrewAI
         'max_tokens' => :length
       }.freeze
 
-      def initialize(config = RCrewAI.configuration)
-        super
+      def initialize(config = RCrewAI.configuration, **hooks)
+        super(config, **hooks)
         @base_url = BASE_URL
       end
 
@@ -74,19 +74,27 @@ module RCrewAI
         ]
       end
 
+      def provider_name
+        :anthropic
+      end
+
       private
 
       def plain_chat(payload)
         url = "#{@base_url}/messages"
+        payload = apply_before_request(payload)
+        started_at = Time.now
         log_request(:post, url, payload)
         response = http_client.post(url, payload, build_headers.merge(auth_header))
         log_response(response)
         body = handle_response(response)
-        normalize_non_streaming(body)
+        apply_after_response(normalize_non_streaming(body), started_at)
       end
 
       def stream_chat(payload, sink) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
         url = "#{@base_url}/messages"
+        payload = apply_before_request(payload)
+        started_at = Time.now
         log_request(:post, url, payload)
 
         assembled_text = +''
@@ -150,7 +158,7 @@ module RCrewAI
                     ))
         end
 
-        {
+        result = {
           content: assembled_text.empty? ? nil : assembled_text,
           tool_calls: tool_calls,
           usage: usage,
@@ -158,6 +166,7 @@ module RCrewAI
           model: config.model,
           provider: :anthropic
         }
+        apply_after_response(result, started_at)
       end
 
       def streaming_post(url, payload, &on_chunk)

data/lib/rcrewai/llm_clients/azure.rb

@@ -8,8 +8,8 @@ module RCrewAI
     # path with an api-version query param, and authenticates with an api-key
     # header instead of Authorization: Bearer.
     class Azure < OpenAI
-      def initialize(config = RCrewAI.configuration)
-        super
+      def initialize(config = RCrewAI.configuration, **hooks)
+        super(config, **hooks)
         @api_version = config.api_version || '2024-02-01'
         @deployment_name = config.deployment_name || config.model
         @base_url = build_endpoint_url

data/lib/rcrewai/llm_clients/base.rb

@@ -9,13 +9,31 @@ module RCrewAI
     class Base
       attr_reader :config, :logger
 
-      def initialize(config = RCrewAI.configuration)
+      def initialize(config = RCrewAI.configuration, before_request: nil, after_response: nil)
         @config = config
         @logger = Logger.new($stdout)
         @logger.level = Logger::INFO
+        @before_request_hooks = Array(before_request)
+        @after_response_hooks = Array(after_response)
         validate_config!
       end
 
+      # Registers a hook run just before the request payload is sent.
+      # Receives (payload, context) where context carries :provider and :model.
+      # Returning a payload replaces it; returning nil keeps the original.
+      def before_request(callable = nil, &block)
+        @before_request_hooks << (callable || block)
+        self
+      end
+
+      # Registers a hook run just after a response is normalized.
+      # Receives (result, context) where context adds :duration_ms.
+      # Returning a result replaces it; returning nil keeps the original.
+      def after_response(callable = nil, &block)
+        @after_response_hooks << (callable || block)
+        self
+      end
+
       def chat(messages:, tools: nil, tool_choice: :auto, stream: nil, **options)
         raise NotImplementedError, 'Subclasses must implement #chat method'
       end
@@ -30,6 +48,42 @@ module RCrewAI
 
       protected
 
+      # Threads the payload through every before_request hook. A hook that
+      # raises is reported and skipped -- observability must never break a call.
+      def apply_before_request(payload)
+        return payload if @before_request_hooks.empty?
+
+        ctx = hook_context
+        @before_request_hooks.reduce(payload) do |acc, hook|
+          hook.call(acc, ctx) || acc
+        rescue StandardError => e
+          Kernel.warn "[rcrewai] before_request hook raised: #{e.class}: #{e.message}"
+          acc
+        end
+      end
+
+      # Threads the normalized result through every after_response hook.
+      def apply_after_response(result, started_at)
+        return result if @after_response_hooks.empty?
+
+        ctx = hook_context.merge(duration_ms: ((Time.now - started_at) * 1000).round(3))
+        @after_response_hooks.reduce(result) do |acc, hook|
+          hook.call(acc, ctx) || acc
+        rescue StandardError => e
+          Kernel.warn "[rcrewai] after_response hook raised: #{e.class}: #{e.message}"
+          acc
+        end
+      end
+
+      def hook_context
+        { provider: provider_name, model: config.model }
+      end
+
+      # Providers override this; Base has no wire identity of its own.
+      def provider_name
+        nil
+      end
+
       def validate_config!
         raise ConfigurationError, 'API key is required' unless config.api_key
         raise ConfigurationError, 'Model is required' unless config.model

data/lib/rcrewai/llm_clients/bedrock.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'faraday'
+require 'json'
+require_relative 'base'
+require_relative '../events'
+require_relative '../pricing'
+
+module RCrewAI
+  module LLMClients
+    # AWS Bedrock via the Converse API (v4). Converse gives every Bedrock model
+    # one request/response shape regardless of the underlying vendor, so this
+    # client speaks Converse rather than each model's native format.
+    #
+    # Authentication: the configured api_key is sent as a bearer token, which
+    # covers Bedrock API keys and any gateway fronting Bedrock. Full SigV4
+    # request signing is not implemented -- it needs the aws-sigv4 gem, and
+    # adding a hard AWS dependency for one provider is not worth it. Users
+    # needing SigV4 can sign via a before_request hook.
+    class Bedrock < Base
+      STOP_REASONS = {
+        'end_turn' => :stop,
+        'stop_sequence' => :stop,
+        'max_tokens' => :length,
+        'tool_use' => :tool_calls,
+        'content_filtered' => :content_filter
+      }.freeze
+
+      def initialize(config = RCrewAI.configuration, **hooks)
+        super
+        @region = config.aws_region
+      end
+
+      def provider_name
+        :bedrock
+      end
+
+      def chat(messages:, tools: nil, tool_choice: :auto, stream: nil, **options) # rubocop:disable Lint/UnusedMethodArgument
+        system_text = extract_system(messages)
+        payload = {
+          messages: format_messages(messages),
+          inferenceConfig: {
+            temperature: options[:temperature] || config.temperature,
+            maxTokens: options[:max_tokens] || config.max_tokens
+          }.compact
+        }
+        payload[:system] = [{ text: system_text }] if system_text
+        payload[:toolConfig] = { tools: format_tools(tools) } if tools && !tools.empty?
+
+        plain_chat(payload)
+      end
+
+      # Converse exposes tool use uniformly, but streaming uses a separate
+      # endpoint and event-stream framing that this client does not implement.
+      def supports_native_tools?(model: config.model) # rubocop:disable Lint/UnusedMethodArgument
+        true
+      end
+
+      private
+
+      def plain_chat(payload)
+        url = converse_url
+        payload = apply_before_request(payload)
+        started_at = Time.now
+        log_request(:post, url, payload)
+        response = http_client.post(url, payload, build_headers.merge(auth_header))
+        log_response(response)
+        body = handle_response(response)
+        apply_after_response(normalize(body), started_at)
+      end
+
+      def converse_url
+        "https://bedrock-runtime.#{@region}.amazonaws.com/model/#{CGI.escape(config.model)}/converse"
+      end
+
+      # Converse carries the system prompt at the top level, not in messages.
+      def extract_system(messages)
+        systems = messages.select { |m| m.is_a?(Hash) && m[:role].to_s == 'system' }
+        return nil if systems.empty?
+
+        systems.map { |m| m[:content] }.join("\n\n")
+      end
+
+      # Every message content is a list of typed blocks.
+      def format_messages(messages)
+        messages.reject { |m| m.is_a?(Hash) && m[:role].to_s == 'system' }.map do |m|
+          { role: m[:role].to_s, content: [{ text: m[:content].to_s }] }
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          { toolSpec: { name: t[:name], description: t[:description],
+                        inputSchema: { json: t[:parameters] } } }
+        end
+      end
+
+      def normalize(body)
+        blocks = body.dig('output', 'message', 'content') || []
+        text = blocks.filter_map { |b| b['text'] }.join
+        tool_calls = blocks.filter_map do |b|
+          use = b['toolUse']
+          next unless use
+
+          { id: use['toolUseId'], name: use['name'], arguments: use['input'] || {} }
+        end
+
+        {
+          content: text.empty? ? nil : text,
+          tool_calls: tool_calls,
+          usage: {
+            prompt_tokens: body.dig('usage', 'inputTokens'),
+            completion_tokens: body.dig('usage', 'outputTokens'),
+            total_tokens: body.dig('usage', 'totalTokens')
+          },
+          finish_reason: STOP_REASONS.fetch(body['stopReason'], :stop),
+          model: config.model,
+          provider: provider_name
+        }
+      end
+
+      def auth_header
+        { 'Authorization' => "Bearer #{config.api_key}" }
+      end
+
+      def validate_config!
+        raise ConfigurationError, 'Bedrock API key is required' unless config.api_key
+        raise ConfigurationError, 'An AWS region is required for Bedrock' unless config.aws_region
+        raise ConfigurationError, 'Model is required' unless config.model
+      end
+    end
+  end
+end

data/lib/rcrewai/llm_clients/google.rb

@@ -20,8 +20,8 @@ module RCrewAI
         'RECITATION' => :stop
       }.freeze
 
-      def initialize(config = RCrewAI.configuration)
-        super
+      def initialize(config = RCrewAI.configuration, **hooks)
+        super(config, **hooks)
         @base_url = BASE_URL
       end
 
@@ -62,17 +62,25 @@ module RCrewAI
         %w[gemini-pro gemini-1.5-pro gemini-1.5-flash gemini-pro-vision]
       end
 
+      def provider_name
+        :google
+      end
+
       private
 
       def plain_chat(url, payload)
+        payload = apply_before_request(payload)
+        started_at = Time.now
         log_request(:post, url, payload)
         response = http_client.post(url, payload, build_headers)
         log_response(response)
         body = handle_response(response)
-        normalize_non_streaming(body)
+        apply_after_response(normalize_non_streaming(body), started_at)
       end
 
       def stream_chat(url, payload, sink)
+        payload = apply_before_request(payload)
+        started_at = Time.now
         log_request(:post, url, payload)
 
         assembled_text = +''
@@ -123,7 +131,7 @@ module RCrewAI
 
         finish_reason = :tool_calls if tool_calls.any?
 
-        {
+        result = {
           content: assembled_text.empty? ? nil : assembled_text,
           tool_calls: tool_calls,
           usage: usage || {},
@@ -131,6 +139,7 @@ module RCrewAI
           model: config.model,
           provider: :google
         }
+        apply_after_response(result, started_at)
       end
 
       def streaming_post(url, payload, &on_chunk)