simforge 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a5e6deba272d1145d6403c0101d8f32a694f236ac4a976d02eb11b79b17c25
-  data.tar.gz: 89481b2c5f3e7a00946aba1e438c21df60b9c8138a04720b1a22701a35095c73
+  metadata.gz: 2a76d9b40226f43c8a4109f0169d6d8c13858fbbe3a3c6856ff218fed8295d1a
+  data.tar.gz: 6ac64f460143f24a0e6eed048396ffd509a61106e741bdc821bc187982786ac1
 SHA512:
-  metadata.gz: 2626a260759ff51764a1b6497b29ac1493acbc86ea9a0e347a39bd5b02987c5bc4012d7b5e7839887f634da72643370c75b6835a92da59c6b7768ae525fae6e2
-  data.tar.gz: 45b37048fc7d7338135f5b2d9cd8d6a4a111034587d055aeb9b58e9cd44ac562a1e00e19b9833293f68afc81ff5b47e184e31e410e5c7a795739ef2bdea17e5f
+  metadata.gz: d466e47c84372946639d021ebdf20ffca1e330f7625f2d2d90e004a2d1c0d4bc4622cccc3e846d1b24918c28062de32e6a60107f2a0fe67bd085649d9e190027
+  data.tar.gz: cc2d549e359de49705dc92c0c33be38167041663385d12b4a75d12db02679d3d2271d940c6c0631770cea0da9070d656ab60f49e18f90b48cbcc311e9dc9e270

data/README.md

@@ -18,7 +18,7 @@ gem install simforge
 
 ## Requirements
 
-- Ruby >= 3.1
+- Ruby >= 3.4
 - No external runtime dependencies (uses stdlib only)
 
 ## Quick Start

data/lib/simforge/client.rb

@@ -5,6 +5,7 @@ require "time"
 
 require_relative "constants"
 require_relative "http_client"
+require_relative "replay"
 require_relative "span_context"
 require_relative "serialize"
 
@@ -27,6 +28,19 @@ module Simforge
       @pending_span_mutex = Mutex.new
     end
 
+    # Replay historical traces through a method and create a test run.
+    #
+    # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
+    # @param method_name [Symbol] the method to replay
+    # @param trace_function_key [String] the trace function key for this method
+    # @param limit [Integer] maximum number of traces to replay (default: 5)
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @return [Hash] with :items, :test_run_id, :test_run_url
+    def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
+      Replay.run(self, receiver, method_name, trace_function_key:, limit:, trace_ids:, max_concurrency:)
+    end
+
     # Execute a block inside a span context, sending trace data on completion.
     # Called by Traceable — not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:)
@@ -69,6 +83,10 @@ module Simforge
         begin
           ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
+          replay_ctx = ReplayContext.current
+          resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+          resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
+
           span_thread = send_span(
             trace_function_key:,
             trace_id:,
@@ -84,7 +102,9 @@ module Simforge
             result:,
             error:,
             started_at:,
-            ended_at:
+            ended_at:,
+            test_run_id: resolved_test_run_id,
+            input_source_span_id: resolved_input_source_span_id
           )
 
           if is_root_span
@@ -158,7 +178,7 @@ module Simforge
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
-      started_at:, ended_at:)
+      started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil)
       # Human-readable JSON (input/output fields)
       human_inputs = Serialize.serialize_inputs(args, kwargs)
       human_output = Serialize.serialize_value(result)
@@ -189,14 +209,18 @@ module Simforge
         "span_data" => span_data
       }
       raw_span["parent_id"] = parent_span_id if parent_span_id
+      raw_span["input_source_span_id"] = input_source_span_id if input_source_span_id
 
-      @http_client.send_external_span(
+      payload = {
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "sourceTraceId" => trace_id,
         "traceFunctionKey" => trace_function_key,
         "rawSpan" => raw_span
-      ) # Returns the background thread
+      }
+      payload["testRunId"] = test_run_id if test_run_id
+
+      @http_client.send_external_span(payload) # Returns the background thread
     end
   end
 end

data/lib/simforge/constants.rb

@@ -2,4 +2,5 @@
 
 module Simforge
   DEFAULT_SERVICE_URL = "https://simforge.goharvest.ai"
+  REPLAY_CONTEXT_KEY = :__simforge_replay_context
 end

data/lib/simforge/http_client.rb

@@ -67,6 +67,57 @@ module Simforge
       end
     end
 
+    # Make a GET request to the Simforge API.
+    # Returns parsed JSON response hash.
+    def get(endpoint, timeout: nil)
+      uri = URI("#{@service_url}#{endpoint}")
+      request_timeout = timeout || @timeout
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = request_timeout
+      http.read_timeout = request_timeout
+
+      req = Net::HTTP::Get.new(uri.path, headers)
+      response = http.request(req)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Net::HTTPError.new("HTTP #{response.code}: #{response.body}", response)
+      end
+
+      result = JSON.parse(response.body)
+
+      if result["error"]
+        msg = result["error"]
+        msg = "#{msg} Configure it at: #{@service_url}#{result["url"]}" if result["url"]
+        raise StandardError, msg
+      end
+
+      result
+    end
+
+    # Start a replay session by fetching historical traces.
+    # Blocking call. Returns hash with testRunId, testRunUrl, and items array.
+    def start_replay(trace_function_key, limit, trace_ids: nil)
+      payload = {
+        "traceFunctionKey" => trace_function_key,
+        "limit" => limit
+      }
+      payload["traceIds"] = trace_ids if trace_ids
+
+      request("/api/sdk/replay/start", payload, timeout: 30)
+    end
+
+    # Fetch an external span by ID. Blocking GET request.
+    def get_external_span(span_id)
+      get("/api/sdk/externalSpans/#{span_id}", timeout: 30)
+    end
+
+    # Mark a replay test run as completed. Blocking call.
+    def complete_replay(test_run_id)
+      request("/api/sdk/replay/complete", {"testRunId" => test_run_id}, timeout: 30)
+    end
+
     # Send an external trace (fire-and-forget in background thread).
     def send_external_trace(payload)
       merged = payload.merge("sdkVersion" => VERSION)

data/lib/simforge/replay.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "serialize"
+
+module Simforge
+  # Thread-local replay context management.
+  module ReplayContext
+    module_function
+
+    def current
+      Thread.current[REPLAY_CONTEXT_KEY]
+    end
+
+    # Execute a block with replay context set on the current thread.
+    # The context is automatically cleared when the block completes.
+    def with_context(test_run_id:, input_source_span_id: nil)
+      previous = Thread.current[REPLAY_CONTEXT_KEY]
+      Thread.current[REPLAY_CONTEXT_KEY] = {
+        test_run_id:,
+        input_source_span_id:
+      }
+      yield
+    ensure
+      Thread.current[REPLAY_CONTEXT_KEY] = previous
+    end
+  end
+
+  # Replay historical traces through a traced method and create a test run.
+  module Replay
+    module_function
+
+    # Replay historical traces through a method and create a test run.
+    #
+    # Fetches the last N traces for the given trace function key, re-runs each
+    # through the provided receiver and method, and returns comparison data.
+    #
+    # @param client [Simforge::Client] the Simforge client instance
+    # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
+    # @param method_name [Symbol] the method to replay
+    # @param trace_function_key [String] the trace function key for this method
+    # @param limit [Integer] maximum number of traces to replay (default: 5)
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @return [Hash] with :items, :test_run_id, :test_run_url
+    def run(client, receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
+      http_client = client.instance_variable_get(:@http_client)
+
+      replay_data = http_client.start_replay(trace_function_key, limit, trace_ids:)
+      test_run_id = replay_data["testRunId"]
+      test_run_url = replay_data["testRunUrl"]
+      server_items = replay_data["items"] || []
+
+      result_items = if server_items.any?
+        process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency)
+      else
+        []
+      end
+
+      Simforge.flush_traces
+
+      begin
+        http_client.complete_replay(test_run_id)
+      rescue => e
+        warn "Simforge: Failed to complete replay: #{e.message}"
+      end
+
+      {
+        items: result_items,
+        test_run_id:,
+        test_run_url: "#{client.service_url}#{test_run_url}"
+      }
+    end
+
+    # Process all replay items, optionally in parallel using threads.
+    def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency)
+      concurrency = max_concurrency || server_items.length
+
+      if concurrency <= 1
+        server_items.map { |item| process_single_item(http_client, item, receiver, method_name, test_run_id) }
+      else
+        results_mutex = Mutex.new
+        results = []
+        work_queue = server_items.each_with_index.to_a
+        work_mutex = Mutex.new
+
+        workers = [concurrency, server_items.length].min.times.map do
+          Thread.new do
+            loop do
+              item, idx = work_mutex.synchronize { work_queue.shift }
+              break unless item
+
+              result = process_single_item(http_client, item, receiver, method_name, test_run_id)
+              results_mutex.synchronize { results[idx] = result }
+            end
+          end
+        end
+
+        workers.each(&:join)
+        results.compact
+      end
+    end
+
+    # Fetch span data and execute a single replay item.
+    def process_single_item(http_client, server_item, receiver, method_name, test_run_id)
+      span = http_client.get_external_span(server_item["externalSpanId"])
+      item_data = extract_span_data(span)
+      execute_item(item_data, receiver, method_name, test_run_id, span["id"])
+    end
+
+    # Extract input/output data from an external span's rawData.
+    def extract_span_data(span)
+      raw_data = span["rawData"] || {}
+      span_data = raw_data["span_data"] || {}
+
+      {
+        "input" => span_data["input"],
+        "output" => span_data["output"],
+        "inputSerialized" => span_data["input_serialized"],
+        "outputSerialized" => span_data["output_serialized"]
+      }
+    end
+
+    # Execute a single replay item: deserialize inputs, call method with replay context.
+    def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil)
+      args, kwargs = Serialize.deserialize_inputs(item)
+
+      fn_result = nil
+      fn_error = nil
+
+      ReplayContext.with_context(test_run_id:, input_source_span_id:) do
+        fn_result = if kwargs.empty?
+          receiver.send(method_name, *args)
+        else
+          receiver.send(method_name, *args, **kwargs)
+        end
+      rescue => e
+        fn_error = e.message
+      end
+
+      {
+        input: args,
+        result: fn_result,
+        original_output: item["output"],
+        error: fn_error
+      }
+    end
+  end
+end

data/lib/simforge/serialize.rb

@@ -65,5 +65,39 @@ module Simforge
     def unmarshal_value(encoded)
       Marshal.load(Base64.strict_decode64(encoded)) # rubocop:disable Security/MarshalLoad
     end
+
+    # Deserialize replay inputs from a span's data into [args, kwargs].
+    #
+    # Prefers Marshal-serialized `inputSerialized` for type preservation,
+    # falls back to the raw `input` field.
+    #
+    # @param item [Hash] with "inputSerialized" and/or "input" keys
+    # @return [Array(Array, Hash)] positional args and keyword args
+    def deserialize_inputs(item)
+      input_serialized = item["inputSerialized"]
+      raw_input = item["input"]
+
+      if input_serialized.is_a?(String) && !input_serialized.empty?
+        begin
+          deserialized = unmarshal_value(input_serialized)
+          if deserialized.is_a?(Hash) && (deserialized.key?(:args) || deserialized.key?(:kwargs))
+            return [deserialized[:args] || [], deserialized[:kwargs] || {}]
+          end
+          return deserialized.nil? ? [[], {}] : [[deserialized], {}]
+        rescue
+          # Fall through to raw_input
+        end
+      end
+
+      if raw_input.is_a?(Array)
+        [raw_input, {}]
+      elsif raw_input.is_a?(Hash)
+        [[], raw_input.transform_keys(&:to_sym)]
+      elsif raw_input.nil?
+        [[], {}]
+      else
+        [[raw_input], {}]
+      end
+    end
   end
 end

data/lib/simforge/span_context.rb

@@ -97,7 +97,7 @@ module Simforge
   # Thread-local span stack for tracking nested spans.
   # Each entry is a Hash with :trace_id and :span_id keys.
   module SpanContext
-    STACK_KEY = :simforge_span_stack
+    STACK_KEY = :__simforge_span_stack
 
     module_function
 

data/lib/simforge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Simforge
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/simforge.rb

@@ -5,6 +5,7 @@ require_relative "simforge/constants"
 require_relative "simforge/serialize"
 require_relative "simforge/span_context"
 require_relative "simforge/http_client"
+require_relative "simforge/replay"
 require_relative "simforge/client"
 require_relative "simforge/traceable"
 

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: simforge
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Harvest Team
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +120,7 @@ files:
 - lib/simforge/client.rb
 - lib/simforge/constants.rb
 - lib/simforge/http_client.rb
+- lib/simforge/replay.rb
 - lib/simforge/serialize.rb
 - lib/simforge/span_context.rb
 - lib/simforge/traceable.rb
@@ -118,7 +132,6 @@ metadata:
   homepage_uri: https://simforge.goharvest.ai
   source_code_uri: https://simforge.goharvest.ai
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -126,15 +139,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Simforge Ruby SDK for function tracing and span management
 test_files: []