simforge 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eaad388f5419c3933530ac93808928f219682b1e32d35fff040f691cbd4f410
-  data.tar.gz: a7922a5c2a3f063b5f6c13f43e5f6defed320c82d9b8d887a3cc12293ab03808
+  metadata.gz: 2a76d9b40226f43c8a4109f0169d6d8c13858fbbe3a3c6856ff218fed8295d1a
+  data.tar.gz: 6ac64f460143f24a0e6eed048396ffd509a61106e741bdc821bc187982786ac1
 SHA512:
-  metadata.gz: 32b1df24c8a1dd4aa8acb6b5ca6828736c1a3b5586982a169865acaaa753075b4e06009f6c2d0d6843e9ec29539cba0a28c4e0df83eaaeef65f31b98e1449637
-  data.tar.gz: 2abbabfde142faa7c8ca0adc6e7433787f16b6b60aaafd28d26bd23c0fc890be852bdae342312540fc97e081bea05d163af66ae1b043f393c05c1f63ddd94d44
+  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"
 
@@ -23,6 +24,21 @@ module Simforge
         @enabled = false
       end
       @http_client = HttpClient.new(api_key:, service_url: @service_url)
+      @pending_span_threads = {}
+      @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.
@@ -42,9 +58,14 @@ module Simforge
         TraceState.create(trace_id)
       end
 
+      if is_root_span
+        @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
+      end
+
       result = nil
       error = nil
       span_contexts = nil
+      span_prompt = nil
 
       begin
         SpanContext.with_span(trace_id:, span_id:) do
@@ -52,6 +73,7 @@ module Simforge
         ensure
           # Capture contexts before the span context is popped
           span_contexts = SpanContext.current&.dig(:contexts)
+          span_prompt = SpanContext.current&.dig(:prompt)
         end
       rescue => e
         error = e.message
@@ -61,7 +83,11 @@ module Simforge
         begin
           ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
-          send_span(
+          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:,
             span_id:,
@@ -70,22 +96,32 @@ module Simforge
             span_type:,
             function_name:,
             contexts: span_contexts,
+            prompt: span_prompt,
             args:,
             kwargs:,
             result:,
             error:,
             started_at:,
-            ended_at:
+            ended_at:,
+            test_run_id: resolved_test_run_id,
+            input_source_span_id: resolved_input_source_span_id
           )
 
-          # For root spans, also send trace completion
           if is_root_span
+            pending = @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) || [] }
+            pending << span_thread if span_thread
+            pending.each { |t| t.join(5) }
+
             send_trace_completion(
               trace_function_key:,
               trace_id:,
               started_at:,
               ended_at:
             )
+          else
+            @pending_span_mutex.synchronize do
+              @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
+            end
           end
         rescue Exception # rubocop:disable Lint/RescueException
           # Silently ignore — user's result/exception takes priority
@@ -141,8 +177,8 @@ module Simforge
     end
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
-      span_name:, span_type:, function_name:, contexts:, args:, kwargs:, result:, error:,
-      started_at:, ended_at:)
+      span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
+      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)
@@ -163,6 +199,7 @@ module Simforge
       span_data["output_serialized"] = marshalled_output if marshalled_output
       span_data["error"] = error if error
       span_data["contexts"] = contexts if contexts&.any?
+      span_data["prompt"] = prompt if prompt
 
       raw_span = {
         "id" => span_id,
@@ -172,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
-      )
+      }
+      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

@@ -57,7 +57,8 @@ module Simforge
       raise last_error
     end
 
-    # Send an external span (fire-and-forget in background thread).
+    # Send an external span in a background thread.
+    # Returns the thread for callers that need to await completion.
     def send_external_span(payload)
       merged = payload.merge("sdkVersion" => VERSION)
 
@@ -66,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)
@@ -92,16 +144,22 @@ module Simforge
 
   class << self
     # Run a block in a background thread with tracking.
+    # Returns the thread for callers that need to join on it.
     def _run_in_background(&block)
       thread = Thread.new do
         block.call
-      rescue
-        # Silently ignore failures in background spans
+      rescue => e
+        begin
+          warn "Simforge: Failed to send request: #{e.message}"
+        rescue
+          # Never crash the host app
+        end
       ensure
         @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
       end
 
       @pending_threads_mutex.synchronize { @pending_threads << thread }
+      thread
     end
 
     # Wait for all pending background threads to complete.

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

@@ -25,6 +25,19 @@ module Simforge
     rescue
       # Silently ignore - never crash the host app
     end
+
+    # Set the prompt for this span.
+    # The prompt is stored in span_data.prompt. Calling multiple times
+    # overwrites the previous value.
+    #
+    # @param prompt [String] the prompt string to store
+    def set_prompt(prompt)
+      return unless prompt.is_a?(String)
+
+      @span_state[:prompt] = prompt
+    rescue
+      # Silently ignore - never crash the host app
+    end
   end
 
   # Handle to the current active trace, allowing trace-level context to be set.
@@ -84,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.6.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"
 
@@ -19,6 +20,10 @@ module Simforge
     def add_context(_context)
       # No-op
     end
+
+    def set_prompt(_prompt)
+      # No-op
+    end
   end
 
   # No-op trace handle returned when outside a span context.

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: simforge
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Harvest Team
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-13 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: []