rcrewai 0.7.0 → 0.8.0

data/lib/rcrewai/checkpoint.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'securerandom'
+require 'time'
+
+module RCrewAI
+  # Durable execution state for a crew run.
+  #
+  # A checkpoint records, per task, whether it completed and what it produced.
+  # Resuming a run replays those results instead of re-executing the tasks --
+  # the expensive part of a crew run is the LLM calls, so skipping a completed
+  # task is the whole point.
+  #
+  # Granularity is task-level: a checkpoint is written after each task settles,
+  # so a crash loses at most the task in flight. Stores are pluggable; anything
+  # responding to #save(id, record), #load(id), #list and #delete works.
+  module Checkpoint
+    class CheckpointError < RCrewAI::Error; end
+
+    # Volatile; for tests and single-process runs.
+    class MemoryStore
+      def initialize
+        @data = {}
+      end
+
+      def save(id, record)
+        @data[id] = deep_dup(record)
+      end
+
+      def load(id)
+        record = @data[id]
+        record && deep_dup(record)
+      end
+
+      def list
+        @data.keys
+      end
+
+      def delete(id)
+        @data.delete(id)
+        nil
+      end
+
+      private
+
+      # Records are plain JSON-shaped data, so a round-trip is a sufficient
+      # deep copy and keeps a caller's later mutation from reaching the store.
+      def deep_dup(record)
+        JSON.parse(JSON.generate(record))
+      end
+    end
+
+    # One JSON file per run under a directory.
+    class FileStore
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def save(id, record)
+        File.write(path_for(id), JSON.pretty_generate(record))
+      end
+
+      def load(id)
+        path = path_for(id)
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      def list
+        Dir.glob(File.join(@dir, '*.json')).map { |p| File.basename(p, '.json') }
+      end
+
+      def delete(id)
+        path = path_for(id)
+        File.delete(path) if File.exist?(path)
+        nil
+      end
+
+      private
+
+      # Run ids reach here from callers and from stored records, so a path
+      # separator or traversal segment must not be able to steer the write
+      # outside the checkpoint directory.
+      def path_for(id)
+        s = id.to_s
+        raise CheckpointError, "invalid run id: #{id.inspect}" if s.empty? ||
+                                                                  s.include?('/') ||
+                                                                  s.include?('\\') ||
+                                                                  s == '.' || s == '..'
+
+        File.join(@dir, "#{s}.json")
+      end
+    end
+
+    module_function
+
+    def new_run_id
+      SecureRandom.uuid
+    end
+
+    # Builds the record persisted for a run.
+    def record_for(run_id:, crew_name:, tasks:, parent_run_id: nil)
+      {
+        'run_id' => run_id,
+        'parent_run_id' => parent_run_id,
+        'crew' => crew_name,
+        'updated_at' => Time.now.utc.iso8601,
+        'tasks' => tasks
+      }
+    end
+
+    # Serializes one task's settled state.
+    def task_entry(task, status)
+      {
+        'status' => status.to_s,
+        'result' => task.result,
+        'execution_time' => task.execution_time
+      }
+    end
+
+    # Walks parent_run_id links from +run_id+ back to the root, returning the
+    # chain oldest-first. Stops on a missing record rather than raising, so a
+    # pruned ancestor truncates the chain instead of breaking it.
+    def lineage(store, run_id)
+      chain = []
+      seen = {}
+      current = run_id
+
+      while current && !seen[current]
+        seen[current] = true
+        record = store.load(current)
+        break unless record
+
+        chain.unshift(current)
+        current = record['parent_run_id']
+      end
+
+      chain
+    end
+  end
+end

data/lib/rcrewai/cli.rb

@@ -8,9 +8,13 @@ module RCrewAI
       Crew.create(crew_name)
     end
 
+    # Thor reserves #run, so the command is defined under another name and
+    # mapped back. Without this the whole class raises on load, which is why
+    # cli.rb went unrequired -- and why bin/rcrewai never worked.
     desc 'run', 'Run the AI crew'
     option :crew, type: :string, required: true, desc: 'Name of the crew to run'
-    def run
+    map 'run' => :run_crew
+    def run_crew
       crew_name = options[:crew]
       puts "Running crew: #{crew_name}"
       crew = Crew.load(crew_name)
@@ -31,9 +35,16 @@ module RCrewAI
     desc 'task SUBCOMMAND ...ARGS', 'Manage tasks'
     subcommand 'task', Task::CLI
 
+    desc 'checkpoint SUBCOMMAND ...ARGS', 'Inspect run checkpoints'
+    subcommand 'checkpoint', Checkpoint::CLI
+
     desc 'version', 'Show version'
     def version
       puts "rcrewai version #{RCrewAI::VERSION}"
     end
+
+    def self.exit_on_failure?
+      true
+    end
   end
 end

data/lib/rcrewai/configuration.rb

@@ -6,6 +6,7 @@ module RCrewAI
                   :openai_api_key, :anthropic_api_key, :google_api_key, :azure_api_key,
                   :openai_model, :anthropic_model, :google_model, :azure_model,
                   :base_url, :api_version, :deployment_name,
+                  :aws_region, :snowflake_account,
                   :pricing, :ollama_native_tools, :log_level
 
     def initialize
@@ -21,6 +22,9 @@ module RCrewAI
       @google_model = 'gemini-pro'
       @azure_model = 'gpt-4'
 
+      @aws_region = nil
+      @snowflake_account = nil
+
       @pricing = nil
       @ollama_native_tools = nil
       @log_level = :info
@@ -101,6 +105,9 @@ module RCrewAI
       @google_api_key = ENV['GOOGLE_API_KEY'] || ENV['GEMINI_API_KEY']
       @azure_api_key = ENV['AZURE_OPENAI_API_KEY']
 
+      @aws_region ||= ENV.fetch('AWS_REGION', nil) || ENV.fetch('AWS_DEFAULT_REGION', nil)
+      @snowflake_account ||= ENV.fetch('SNOWFLAKE_ACCOUNT', nil)
+
       @api_key = ENV['LLM_API_KEY'] if @api_key.nil?
       @base_url = ENV['LLM_BASE_URL'] if @base_url.nil?
       @api_version = ENV['AZURE_API_VERSION'] if @api_version.nil?

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,11 +63,15 @@ 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)
 
@@ -72,6 +80,49 @@ module RCrewAI
 
       result = async ? execute_async(**async_options) : execute_sync
       run_after_hooks(result)
+    ensure
+      # Drop per-task references to the caller's sink so request-scoped
+      # collectors do not stay reachable after the run. The crew's own
+      # +stream_sink+ reader is left intact: Process reads it.
+      @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.
@@ -167,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