simforge 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9f2c1b27222c1a19c1ee819c021349f8f7cd479432e38a8b8ed5d218b13b026
-  data.tar.gz: '059c030ed76519b30a5fd187392af8af0d29ba6a0704132359792ef4381fed9c'
+  metadata.gz: 0eaad388f5419c3933530ac93808928f219682b1e32d35fff040f691cbd4f410
+  data.tar.gz: a7922a5c2a3f063b5f6c13f43e5f6defed320c82d9b8d887a3cc12293ab03808
 SHA512:
-  metadata.gz: 7057e4d20182d99a6c71b0a5fe4f52f7d661230a111967a805421f5459463371ecc8849a7bbfcb7f313e16a3bf9623b50002393eeed91ef7e311cbfe43fd6e3a
-  data.tar.gz: a76648e123b02fc6a00124910c42624c9da7819df4b8437d8fb1b8aed64498d72871749da56e20a8ba94bc86d2ba0dd013da70ca843900138e33b65ac5e00e12
+  metadata.gz: 32b1df24c8a1dd4aa8acb6b5ca6828736c1a3b5586982a169865acaaa753075b4e06009f6c2d0d6843e9ec29539cba0a28c4e0df83eaaeef65f31b98e1449637
+  data.tar.gz: 2abbabfde142faa7c8ca0adc6e7433787f16b6b60aaafd28d26bd23c0fc890be852bdae342312540fc97e081bea05d163af66ae1b043f393c05c1f63ddd94d44

data/README.md

@@ -244,7 +244,7 @@ end
 # Runtime metadata (inside a span)
 simforge_span :process_order, type: "function"
 def process_order(order_id)
-  Simforge.current_span.set_metadata(
+  Simforge.current_span.add_metadata(
     "user_id" => current_user.id,
     "request_id" => request.id
   )

data/lib/simforge/client.rb

@@ -27,25 +27,31 @@ module Simforge
 
     # 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:, metadata: nil)
+    def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:)
       return yield unless @enabled
 
       parent = SpanContext.current
       trace_id = parent ? parent[:trace_id] : SecureRandom.uuid
       span_id = SecureRandom.uuid
       parent_span_id = parent&.dig(:span_id)
+      is_root_span = parent_span_id.nil?
       started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
+      # Register trace state for root spans
+      if is_root_span && !TraceState.get(trace_id)
+        TraceState.create(trace_id)
+      end
+
       result = nil
       error = nil
-      runtime_metadata = nil
+      span_contexts = nil
 
       begin
         SpanContext.with_span(trace_id:, span_id:) do
           result = yield
         ensure
-          # Capture runtime metadata before the span context is popped
-          runtime_metadata = SpanContext.current&.dig(:metadata)
+          # Capture contexts before the span context is popped
+          span_contexts = SpanContext.current&.dig(:contexts)
         end
       rescue => e
         error = e.message
@@ -55,13 +61,6 @@ module Simforge
         begin
           ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
-          # Merge runtime metadata with definition-time metadata (runtime wins)
-          merged_metadata = if runtime_metadata
-            (metadata || {}).merge(runtime_metadata)
-          else
-            metadata
-          end
-
           send_span(
             trace_function_key:,
             trace_id:,
@@ -70,7 +69,7 @@ module Simforge
             span_name:,
             span_type:,
             function_name:,
-            metadata: merged_metadata,
+            contexts: span_contexts,
             args:,
             kwargs:,
             result:,
@@ -78,6 +77,16 @@ module Simforge
             started_at:,
             ended_at:
           )
+
+          # For root spans, also send trace completion
+          if is_root_span
+            send_trace_completion(
+              trace_function_key:,
+              trace_id:,
+              started_at:,
+              ended_at:
+            )
+          end
         rescue Exception # rubocop:disable Lint/RescueException
           # Silently ignore — user's result/exception takes priority
           # Catches Exception (not just StandardError) to handle SystemStackError
@@ -96,8 +105,43 @@ module Simforge
       raise ArgumentError, "Invalid span type '#{type}'. Must be one of: #{SPAN_TYPES.join(", ")}"
     end
 
+    def send_trace_completion(trace_function_key:, trace_id:, started_at:, ended_at:)
+      trace_state = TraceState.get(trace_id)
+      trace_started_at = trace_state&.dig(:started_at) || started_at
+
+      raw_trace = {
+        "id" => trace_id,
+        "started_at" => trace_started_at,
+        "ended_at" => ended_at
+      }
+
+      if trace_state&.dig(:metadata)
+        raw_trace["metadata"] = trace_state[:metadata]
+      end
+      if trace_state&.dig(:contexts)
+        raw_trace["contexts"] = trace_state[:contexts]
+      end
+
+      payload = {
+        "type" => "sdk-function",
+        "source" => "ruby-sdk-function",
+        "traceFunctionKey" => trace_function_key,
+        "externalTrace" => raw_trace,
+        "completed" => true
+      }
+
+      if trace_state&.dig(:session_id)
+        payload["sessionId"] = trace_state[:session_id]
+      end
+
+      @http_client.send_external_trace(payload)
+
+      # Clean up trace state
+      TraceState.delete(trace_id)
+    end
+
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
-      span_name:, span_type:, function_name:, metadata:, args:, kwargs:, result:, error:,
+      span_name:, span_type:, function_name:, contexts:, args:, kwargs:, result:, error:,
       started_at:, ended_at:)
       # Human-readable JSON (input/output fields)
       human_inputs = Serialize.serialize_inputs(args, kwargs)
@@ -118,7 +162,7 @@ module Simforge
       span_data["input_serialized"] = marshalled_input if marshalled_input
       span_data["output_serialized"] = marshalled_output if marshalled_output
       span_data["error"] = error if error
-      span_data["metadata"] = metadata if metadata
+      span_data["contexts"] = contexts if contexts&.any?
 
       raw_span = {
         "id" => span_id,

data/lib/simforge/http_client.rb

@@ -66,6 +66,15 @@ module Simforge
       end
     end
 
+    # Send an external trace (fire-and-forget in background thread).
+    def send_external_trace(payload)
+      merged = payload.merge("sdkVersion" => VERSION)
+
+      Simforge._run_in_background do
+        request("/api/sdk/externalTraces", merged, timeout: 10)
+      end
+    end
+
     private
 
     def headers

data/lib/simforge/span_context.rb

@@ -1,19 +1,83 @@
 # frozen_string_literal: true
 
 module Simforge
-  # Handle to the current active span, allowing runtime metadata to be set.
+  # Handle to the current active span, allowing context to be added.
   class CurrentSpan
-    def initialize(context)
-      @context = context
+    def initialize(span_state)
+      @span_state = span_state
     end
 
-    # Set custom metadata on this span. Merges with any existing metadata
-    # (both definition-time and previous runtime calls), with later values
-    # taking precedence on conflict.
+    # The trace ID for the current span.
+    def trace_id
+      @span_state[:trace_id]
+    end
+
+    # Add a context entry to this span.
+    # The entire hash is pushed as a single entry in the contexts array.
+    # Context entries are accumulated - multiple calls add to the list.
+    #
+    # @param context [Hash] key-value pairs to add as a single context entry
+    def add_context(context)
+      return unless context.is_a?(Hash)
+
+      @span_state[:contexts] ||= []
+      @span_state[:contexts] << context
+    rescue
+      # Silently ignore - never crash the host app
+    end
+  end
+
+  # Handle to the current active trace, allowing trace-level context to be set.
+  class CurrentTrace
+    def initialize(trace_id)
+      @trace_id = trace_id
+    end
+
+    # Set the session ID for this trace.
+    # Session ID is used to group traces from the same user session.
+    # This is stored as a database column.
+    #
+    # @param session_id [String] the session ID to set
+    def set_session_id(session_id)
+      trace_state = get_or_create_trace_state
+      trace_state[:session_id] = session_id
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    # Set metadata for this trace.
+    # Metadata is stored in the raw trace data. Subsequent calls merge with
+    # existing metadata, with later values taking precedence.
+    #
+    # @param metadata [Hash] key-value pairs to store as trace metadata
     def set_metadata(metadata)
       return unless metadata.is_a?(Hash)
 
-      @context[:metadata] = (@context[:metadata] || {}).merge(metadata)
+      trace_state = get_or_create_trace_state
+      trace_state[:metadata] = (trace_state[:metadata] || {}).merge(metadata)
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    # Add a context entry to this trace.
+    # The entire hash is pushed as a single entry in the contexts array.
+    # Context entries are accumulated - multiple calls add to the list.
+    #
+    # @param context [Hash] key-value pairs to add as a single context entry
+    def add_context(context)
+      return unless context.is_a?(Hash)
+
+      trace_state = get_or_create_trace_state
+      trace_state[:contexts] ||= []
+      trace_state[:contexts] << context
+    rescue
+      # Silently ignore - never crash the host app
+    end
+
+    private
+
+    def get_or_create_trace_state
+      TraceState.get(@trace_id) || TraceState.create(@trace_id)
     end
   end
 
@@ -42,4 +106,33 @@ module Simforge
       stack.pop
     end
   end
+
+  # Global storage for trace states (trace_id -> state hash)
+  module TraceState
+    @states_mutex = Mutex.new
+    @states = {}
+
+    module_function
+
+    def get(trace_id)
+      @states_mutex.synchronize { @states[trace_id] }
+    end
+
+    def create(trace_id)
+      @states_mutex.synchronize do
+        @states[trace_id] ||= {
+          trace_id:,
+          started_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+        }
+      end
+    end
+
+    def delete(trace_id)
+      @states_mutex.synchronize { @states.delete(trace_id) }
+    end
+
+    def clear_all
+      @states_mutex.synchronize { @states.clear }
+    end
+  end
 end

data/lib/simforge/traceable.rb

@@ -38,10 +38,9 @@ module Simforge
     # @param trace_function_key [String] the trace function key
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
-    def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom", metadata: nil)
+    def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom")
       span_name = name || method_name.to_s
       method_name_str = method_name.to_s
-      span_metadata = metadata
 
       wrapper = Module.new do
         define_method(method_name) do |*args, **kwargs, &block|
@@ -50,7 +49,6 @@ module Simforge
             span_name:,
             span_type: type,
             function_name: method_name_str,
-            metadata: span_metadata,
             args:,
             kwargs:) do
             super(*args, **kwargs, &block)
@@ -87,7 +85,7 @@ module Simforge
       # @param trace_function_key [String, nil] trace function key (overrides class-level simforge_function)
       # @param name [String, nil] explicit span name (defaults to method name)
       # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
-      def simforge_span(method_name, trace_function_key: nil, name: nil, type: "custom", metadata: nil)
+      def simforge_span(method_name, trace_function_key: nil, name: nil, type: "custom")
         trace_function_key ||= @simforge_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `simforge_span` " \
@@ -96,15 +94,14 @@ module Simforge
 
         # If the method already exists (inline or after-method style), wrap it immediately
         if method_defined?(method_name) || private_method_defined?(method_name)
-          _simforge_wrap_method(method_name, trace_function_key:, name:, type:, metadata:)
+          _simforge_wrap_method(method_name, trace_function_key:, name:, type:)
         else
           # Method doesn't exist yet (before-method style) — register for method_added hook
           @_simforge_pending_spans ||= {}
           @_simforge_pending_spans[method_name] = {
             trace_function_key:,
             name:,
-            type:,
-            metadata:
+            type:
           }
         end
       end
@@ -119,10 +116,9 @@ module Simforge
         _simforge_wrap_method(method_name, **config)
       end
 
-      def _simforge_wrap_method(method_name, trace_function_key:, name: nil, type: "custom", metadata: nil)
+      def _simforge_wrap_method(method_name, trace_function_key:, name: nil, type: "custom")
         span_name = name || method_name.to_s
         method_name_str = method_name.to_s
-        span_metadata = metadata
 
         wrapper = Module.new do
           define_method(method_name) do |*args, **kwargs, &block|
@@ -131,7 +127,6 @@ module Simforge
               span_name:,
               span_type: type,
               function_name: method_name_str,
-              metadata: span_metadata,
               args:,
               kwargs:) do
               super(*args, **kwargs, &block)

data/lib/simforge/version.rb

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

data/lib/simforge.rb

@@ -9,6 +9,37 @@ require_relative "simforge/client"
 require_relative "simforge/traceable"
 
 module Simforge
+  # No-op span handle returned when outside a span context.
+  # All methods do nothing, preventing crashes when called outside traced code.
+  class NoOpCurrentSpan
+    def trace_id
+      ""
+    end
+
+    def add_context(_context)
+      # No-op
+    end
+  end
+
+  # No-op trace handle returned when outside a span context.
+  # All methods do nothing, preventing crashes when called outside traced code.
+  class NoOpCurrentTrace
+    def set_session_id(_session_id)
+      # No-op
+    end
+
+    def set_metadata(_metadata)
+      # No-op
+    end
+
+    def add_context(_context)
+      # No-op
+    end
+  end
+
+  NO_OP_SPAN = NoOpCurrentSpan.new.freeze
+  NO_OP_TRACE = NoOpCurrentTrace.new.freeze
+
   class << self
     # Configure the global Simforge client.
     #
@@ -37,12 +68,25 @@ module Simforge
     # Call this from inside a traced method to get a span handle that allows
     # setting metadata at runtime.
     #
-    # @return [CurrentSpan, nil] the current span, or nil if outside a span context
+    # @return [CurrentSpan, NoOpCurrentSpan] the current span, or a no-op if outside a span context
     def current_span
       entry = SpanContext.current
-      return nil unless entry
+      return NO_OP_SPAN unless entry
 
       CurrentSpan.new(entry)
     end
+
+    # Get a handle to the current active trace.
+    #
+    # Call this from inside a traced method to get a trace handle that allows
+    # setting trace-level context at runtime.
+    #
+    # @return [CurrentTrace, NoOpCurrentTrace] the current trace, or a no-op if outside a span context
+    def current_trace
+      entry = SpanContext.current
+      return NO_OP_TRACE unless entry
+
+      CurrentTrace.new(entry[:trace_id])
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simforge
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Harvest Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 2026-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake