bitfab 0.33.2 → 0.33.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3dd02ac43d3ed65f11a6dcf52aa0d0d3a331fa428fb568a74147f5007fc9e22
-  data.tar.gz: 94b0cc1645fc42ce929a4fd1363de7ededc908f20dd411d3e7f8fd68d3bed0f8
+  metadata.gz: 12cae09488f9200115e768e31661e55be850acc2dbcf2b53eece9c4ab4d59ca2
+  data.tar.gz: 3242cb27cbd71d15094bc4024cb914a494eefa2eeee317e1d45c8ba77c77f4a0
 SHA512:
-  metadata.gz: b3a07fecf4731278963e8db381a0bfc6b4677d17bd2464f36f1d5ccfd455a8d3f066273502674158c3ac3b99a180f3017b0c5185f8e6ff3795c87b7fd2c612cb
-  data.tar.gz: 38e33c8a2dc6ab7e2e6a4c416bea15828a81724eb8ffe4b0fb440088e3b05fea53abaded2fa46bf2e852f7fd307cd5216d149b296b321a5399861861b08bd8d1
+  metadata.gz: 11f4111de6c94527b2f4b14757b50ccaddea211d3366bf1a5241e8e7e0ffa065138a84fa7f6db84baaec926cfeb9754fe7024a090b297ecb35e7916a1fc517f1
+  data.tar.gz: 880b440e2610064045ff1e753d65167c46be2a7220897aa0631b739e24affec2e99cd05de12acf2d39f162474d8fbec6ff13b614f60c6390529395ad2478e4ab

data/lib/bitfab/client.rb

@@ -76,9 +76,14 @@ module Bitfab
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
-    #   code change being tested in this replay (stored on the experiment)
+    #   code change being tested in this replay (stored on the experiment).
+    #   When supplied without code_change_files, this text is preserved while
+    #   the SDK automatically captures the files.
+    #   Pass nil when the replay should have no description; use
+    #   code_change_files: nil to suppress automatic file capture.
     # @param code_change_files [Array<Hash>, nil] optional list of edited files,
-    #   each as { path:, before:, after: } (use "" for new/deleted files)
+    #   each as { path:, before:, after: } (use "" for new/deleted files).
+    #   Omit to capture automatically, or pass nil to suppress file capture.
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch
     # @param dataset_id [String, nil] optional UUID of the dataset this replay
@@ -118,7 +123,7 @@ module Bitfab
     #   A raising callback never crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
-      name: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, dataset_id: nil, grader_ids: nil, mock: "marked",
+      name: nil, code_change_description: Replay::CODE_CHANGE_UNSET, code_change_files: Replay::CODE_CHANGE_UNSET, experiment_group_id: nil, dataset_id: nil, grader_ids: nil, mock: "marked",
       adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
@@ -238,12 +243,23 @@ module Bitfab
     # 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:,
-      mock_on_replay: false)
+      capture_when: "always", mock_on_replay: false)
       # Decide at CALL time, not construction. The key may be set after the
       # client is built (env loaded later), so re-checking per call lets a
       # late-resolved key take effect.
       return yield unless tracing_enabled?
 
+      resolved_capture_when = capture_when.to_s
+      unless %w[always nested].include?(resolved_capture_when)
+        Bitfab.warn_once(
+          "invalid-capture-when:#{trace_function_key}",
+          "unknown capture_when value #{capture_when.inspect}; defaulting to \"always\". " \
+          "Valid values: \"always\", \"nested\"."
+        )
+        resolved_capture_when = "always"
+      end
+      return yield if resolved_capture_when == "nested" && SpanContext.current.nil?
+
       # Span setup runs before the user's block. Tracing is a side-channel, so
       # if anything here raises (id generation, trace-state bookkeeping, a
       # malformed replay mock tree) the user's method must still run. On failure
@@ -887,12 +903,15 @@ module Bitfab
     # @param method_name [Symbol] the method to wrap
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy
-    def wrap(klass, method_name, name: nil, type: "custom", mock_on_replay: false)
+    def wrap(klass, method_name, name: nil, type: "custom", capture_when: "always", mock_on_replay: false)
       Bitfab::Traceable.wrap(
         klass, method_name,
         trace_function_key: @trace_function_key,
-        name:, type:, mock_on_replay:,
+        name:, type:, capture_when:, mock_on_replay:,
         client: @client
       )
     end

data/lib/bitfab/replay.rb

@@ -81,6 +81,8 @@ module Bitfab
 
   # Replay historical traces through a traced method and create a test run.
   module Replay
+    CODE_CHANGE_UNSET = Object.new.freeze
+
     module_function
 
     # Replay historical traces through a method and create a test run.
@@ -99,9 +101,14 @@ module Bitfab
     # @param name [String, nil] optional display name for the resulting experiment/test run
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
-    #   code change being tested in this replay (stored on the experiment)
+    #   code change being tested in this replay (stored on the experiment).
+    #   When supplied without code_change_files, this text is preserved while
+    #   the SDK automatically captures the files.
+    #   Pass nil when the replay should have no description; use
+    #   code_change_files: nil to suppress automatic file capture.
     # @param code_change_files [Array<Hash>, nil] optional list of edited files,
-    #   each as { path:, before:, after: } (empty string for new/deleted files)
+    #   each as { path:, before:, after: } (empty string for new/deleted files).
+    #   Omit to capture automatically, or pass nil to suppress file capture.
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch
     # @param dataset_id [String, nil] optional UUID of the dataset this replay
@@ -140,7 +147,7 @@ module Bitfab
     #   crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil,
-      max_concurrency: 10, code_change_description: nil, code_change_files: nil, experiment_group_id: nil,
+      max_concurrency: 10, code_change_description: CODE_CHANGE_UNSET, code_change_files: CODE_CHANGE_UNSET, experiment_group_id: nil,
       dataset_id: nil, grader_ids: nil, mock: "marked",
       adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
@@ -187,18 +194,18 @@ module Bitfab
 
       include_db_branch_lease = !db_branch.nil?
 
-      # An explicit code change always wins; only when the caller passed neither
-      # field do we fall back to the payload the replay wrapper captured from git
-      # and handed over via BITFAB_CODE_CHANGE_PATH. This is what makes an
-      # experiment show its diff even when the run happened outside the
-      # assistant's make-change rails.
-      if code_change_description.nil? && code_change_files.nil?
+      # code_change_files controls capture: omitted auto-captures, an array
+      # wins, and explicit nil opts out. Preserve a caller-supplied description
+      # while filling only the omitted files.
+      if code_change_files.equal?(CODE_CHANGE_UNSET)
         captured = resolve_auto_code_change(name)
         unless captured.nil?
-          code_change_description = captured[0]
           code_change_files = captured[1]
+          code_change_description = captured[0] if code_change_description.equal?(CODE_CHANGE_UNSET)
         end
       end
+      code_change_description = nil if code_change_description.equal?(CODE_CHANGE_UNSET)
+      code_change_files = nil if code_change_files.equal?(CODE_CHANGE_UNSET)
 
       resolved_db_branch_settings = db_branch_settings(db_branch)
       replay_data = http_client.start_replay(

data/lib/bitfab/traceable.rb

@@ -38,6 +38,9 @@ module Bitfab
     # @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
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
     #   When true, `client.replay(...)` returns this span's
     #   historical output instead of executing the wrapped method.
@@ -48,7 +51,7 @@ module Bitfab
     #   preserve the bound client through the fluent wrapper, matching Python's
     #   `BitfabFunction.span()` and TypeScript's `BitfabFunction.withSpan()`.
     def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom",
-      mock_on_replay: false, client: nil)
+      capture_when: "always", mock_on_replay: false, client: nil)
       span_name = name || method_name.to_s
       method_name_str = method_name.to_s
       bound_client = client
@@ -63,6 +66,7 @@ module Bitfab
             function_name: method_name_str,
             args:,
             kwargs:,
+            capture_when:,
             mock_on_replay:) do
             super(*args, **kwargs, &block)
           end
@@ -132,10 +136,14 @@ module Bitfab
       # @param trace_function_key [String, nil] trace function key (overrides class-level bitfab_function)
       # @param name [String, nil] explicit span name (defaults to method name)
       # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+      # @param capture_when [String, Symbol] "always" to allow a root trace, or
+      #   "nested" to capture only when another Bitfab span is active. Unknown
+      #   values warn once and default to "always"
       # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
       #   When true, `client.replay(...)` returns this span's
       #   historical output instead of executing the wrapped method.
-      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false)
+      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
@@ -144,7 +152,9 @@ module Bitfab
 
         # If the method already exists (inline or after-method style), wrap it immediately
         if method_defined?(method_name) || private_method_defined?(method_name)
-          _bitfab_wrap_method(method_name, trace_function_key:, name:, type:, mock_on_replay:)
+          _bitfab_wrap_method(
+            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:
+          )
         else
           # Method doesn't exist yet (before-method style) - register for method_added hook
           @_bitfab_pending_spans ||= {}
@@ -152,6 +162,7 @@ module Bitfab
             trace_function_key:,
             name:,
             type:,
+            capture_when:,
             mock_on_replay:
           }
         end
@@ -167,7 +178,8 @@ module Bitfab
         _bitfab_wrap_method(method_name, **config)
       end
 
-      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom", mock_on_replay: false)
+      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         span_name = name || method_name.to_s
         method_name_str = method_name.to_s
 
@@ -185,6 +197,7 @@ module Bitfab
               function_name: method_name_str,
               args:,
               kwargs:,
+              capture_when:,
               mock_on_replay:) do
               super(*args, **kwargs, &block)
             end

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.33.2"
+  VERSION = "0.33.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.33.2
+  version: 0.33.4
 platform: ruby
 authors:
 - Harvest Team