bitfab 0.74.3 → 0.75.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e04db08d34f7d195036216aa6f41ee940f81af773924508c2a12da97fbbd1e4a
-  data.tar.gz: 8fd59297c7eeb7e2d053ca2e4722d5b6aea43ae5c96f691a2addf81f0f9452ea
+  metadata.gz: fad2341a7e82e22c18faf4809a1807407660eed238b04886b2687e4dc15989b2
+  data.tar.gz: 7a46b9c4935290898decf6f835257d5b8551281eb1ddebb1680128fcd5ac8c74
 SHA512:
-  metadata.gz: aa1099e23b6af4619238c7b6b94f13e9ad15ead7aa6dcaa7fb5a993b634dd00ab6468c5924bcc717da520fa9f0e96d3d5e82a7ab32656e96885626b07e38c3e2
-  data.tar.gz: a99c779521142a681697cdadd6b031b1f2f181e851c919ec2f8e571dd3eb447eeccb6063380c5ee8ccfc706e420ef1e2fe23bc0fdd2eb5802e5930838372a075
+  metadata.gz: 82ef99ecba72308fc1e865257f260756cab829bae0167404f50f8317dd0d921446b02f4379f5c254e98f8deb3fb68104afa73075c4081cc9d5a7b7345243611f
+  data.tar.gz: 696fb090a73f51ab3bb9ca07277e89a0529dd3031a8c96bfa581f7c54235ba3205f804df4790e5d83163d635dfa5228f9d0be05e4e37d4c1805fb7271a920732

data/lib/bitfab/client.rb

@@ -722,7 +722,8 @@ module Bitfab
             explicit_span_receiver:,
             explicit_span_method_name: explicit_span_method_name&.to_sym,
             surface:, recording_override:, content_withheld:,
-            sends_on_completion: sends_on_completion
+            sends_on_completion: sends_on_completion,
+            trace_function_key:
           ) do
             invoke = -> { around_body ? around_body.call { yield } : yield }
             result = if explicit_span_receiver
@@ -769,7 +770,8 @@ module Bitfab
           surface:,
           around_body:,
           explicit_span_receiver:,
-          explicit_span_method_name:
+          explicit_span_method_name:,
+          trace_function_key:
         )
       end
 
@@ -812,7 +814,7 @@ module Bitfab
     end
 
     def root_trace_function_key(trace_id, trace_function_key)
-      TraceState.get(trace_id)&.dig(:trace_function_key) || trace_function_key
+      TraceState.trace_function_key(trace_id) || trace_function_key
     end
 
     def wait_for_simulation_plan
@@ -902,8 +904,10 @@ module Bitfab
     # span output. The span is sent exactly once: when iteration finishes,
     # raises, or the wrapper is `.close`d.
     def wrap_enumerator(source, trace_id:, span_id:, complete:, explicit_span_receiver: nil,
-      explicit_span_method_name: nil, surface: nil, around_body: nil)
+      explicit_span_method_name: nil, surface: nil, around_body: nil, trace_function_key: nil)
       span_entry = {trace_id:, span_id:, surface:}
+      SpanContext.record_trace_function_keys(span_entry, trace_function_key)
+      trace_function_keys = span_entry[:trace_function_keys]
       if explicit_span_receiver
         span_entry[:explicit_span_receiver] = explicit_span_receiver
         span_entry[:explicit_span_method_name] = explicit_span_method_name&.to_sym
@@ -916,7 +920,7 @@ module Bitfab
         # the right parent. The fiber bridge carries the same parent into
         # Enumerator.new / enum_for source fibers on this thread.
         ReplayContext.with_span(trace_id:, span_id:) do
-          SpanContext.with_fiber_bridge(trace_id:, span_id:, surface:) do
+          SpanContext.with_fiber_bridge(trace_id:, span_id:, surface:, trace_function_key:, trace_function_keys:) do
             SpanContext.stack.push(span_entry)
             begin
               iterate = lambda do

data/lib/bitfab/span_context.rb

@@ -19,6 +19,16 @@ module Bitfab
       @span_state[:trace_id]
     end
 
+    # The keys of every trace function running at this point, outermost first,
+    # each listed once. A trace function called inside another one comes after
+    # it, so a cost recorded here can be counted toward each of them. Empty
+    # outside a trace.
+    def trace_function_keys
+      span_keys = @span_state[:trace_function_keys] || []
+      root_keys = Subtree.active_sessions.reverse.map(&:trace_function_key).uniq
+      (root_keys - span_keys) + span_keys
+    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.
@@ -53,6 +63,15 @@ module Bitfab
       @trace_id = trace_id
     end
 
+    # The key of the trace function the current trace is stored under (the one
+    # that started it). A bitfab_span or get_function call inside another trace
+    # function joins that trace, so it reports the outer key. A bitfab_trace
+    # root inside another root starts its own trace, so it reports its own key.
+    # Empty string outside a trace.
+    def trace_function_key
+      TraceState.trace_function_key(@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.
@@ -121,7 +140,8 @@ module Bitfab
   end
 
   # Thread-local span stack for tracking nested spans.
-  # Each entry is a Hash with :trace_id and :span_id keys.
+  # Each entry is a Hash with :trace_id and :span_id keys, plus the span's own
+  # :trace_function_key and the :trace_function_keys running at it.
   module SpanContext
     STACK_KEY = :__bitfab_span_stack
     FIBER_BRIDGE_STACK_KEY = :__bitfab_span_fiber_bridge_stack
@@ -139,8 +159,9 @@ module Bitfab
     # Enumerator.new and enum_for run their source body in another Fiber on
     # the same thread. Bridge only the active Enumerator parent across that
     # boundary; ordinary fiber-local span stacks remain isolated.
-    def with_fiber_bridge(trace_id:, span_id:, surface: nil)
+    def with_fiber_bridge(trace_id:, span_id:, surface: nil, trace_function_key: nil, trace_function_keys: nil)
       entry = {trace_id:, span_id:}
+      record_trace_function_keys(entry, trace_function_key, trace_function_keys)
       entry[:surface] = surface if surface
       fiber_bridge_stack.push(entry)
       yield
@@ -150,8 +171,9 @@ module Bitfab
 
     # Execute a block with a new span pushed onto the stack.
     # The span is automatically popped when the block completes.
-    def with_span(trace_id:, span_id:, explicit_span_receiver: nil, explicit_span_method_name: nil, surface: nil, recording_override: nil, content_withheld: nil, sends_on_completion: nil)
+    def with_span(trace_id:, span_id:, explicit_span_receiver: nil, explicit_span_method_name: nil, surface: nil, recording_override: nil, content_withheld: nil, sends_on_completion: nil, trace_function_key: nil)
       entry = {trace_id:, span_id:}
+      record_trace_function_keys(entry, trace_function_key)
       entry[:sends_on_completion] = sends_on_completion if sends_on_completion
       entry[:surface] = surface if surface
       entry[:recording_override] = recording_override if recording_override
@@ -166,6 +188,22 @@ module Bitfab
       stack.pop
     end
 
+    # The trace function keys running at this point with the given key added
+    # at the end, each listed once. A nil key returns the running keys as is.
+    def trace_function_keys_with(trace_function_key)
+      running = current&.dig(:trace_function_keys) || []
+      trace_function_key ? running | [trace_function_key] : running
+    end
+
+    # Store a span's own trace function key and the keys running at that span
+    # on its stack entry, computing the running keys from the current span
+    # when they are not given. Nothing is stored when no key is running.
+    def record_trace_function_keys(entry, trace_function_key, trace_function_keys = nil)
+      entry[:trace_function_key] = trace_function_key if trace_function_key
+      keys = trace_function_keys || trace_function_keys_with(trace_function_key)
+      entry[:trace_function_keys] = keys unless keys.empty?
+    end
+
     def fiber_bridge_stack
       current_thread = Thread.current
       current_thread.thread_variable_get(FIBER_BRIDGE_STACK_KEY) || begin
@@ -208,6 +246,10 @@ module Bitfab
       end
     end
 
+    def trace_function_key(trace_id)
+      get(trace_id)&.dig(:trace_function_key)
+    end
+
     def delete(trace_id)
       @states_mutex.synchronize { @states.delete(trace_id) }
     end

data/lib/bitfab/verdicts.rb

@@ -194,12 +194,27 @@ module Bitfab
       end
     end
 
-    # Reads one trace's verdicts, or nil when the trace has none.
+    # Reads one trace's verdicts, or nil when the trace has none. See {#get_all} for the shape of each
+    # "evidence" item.
     def get(trace_id)
       get_all([trace_id]).first
     end
 
-    # Reads the verdicts of several traces.
+    # Reads the verdicts of several traces. Each trace and each entry of its "assertions" carries
+    # "evidence": nil, or an array of hashes, one per span cited, each with "spanId" and "text".
+    #
+    # Evidence written by Bitfab's assertion judge also carries "field", "ranges", and "spanChanged",
+    # which point at the exact passages the judge read. "field" is the span field the judge read
+    # ("summary", "input", "output", "reasoning", "content", "metadata", "errors", "contexts", or
+    # "llm_usage"). "ranges" are [start, end) character ranges into that field's text as the judge saw
+    # it: a string field as is, any other value as JSON indented by two spaces. Indexes are JavaScript
+    # string indexes (UTF-16 code units), not Ruby character indexes, so text outside the Basic
+    # Multilingual Plane counts two per character. Use them to highlight only when "spanChanged" is false.
+    #
+    # "spanChanged" is true when the span no longer matches what was judged: "text" is then only a short
+    # preview saved with the verdict, and "ranges" must not be used to highlight anything. When it is
+    # false, "text" is the full text of "ranges" read from the span, joined by a newline, an ellipsis,
+    # and a newline. Unknown keys are passed through as the server sent them.
     def get_all(trace_ids)
       return [] if trace_ids.empty?
 

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -49,6 +49,10 @@ module Bitfab
       ""
     end
 
+    def trace_function_keys
+      []
+    end
+
     def add_context(_context)
       # No-op
     end
@@ -61,6 +65,10 @@ module Bitfab
   # No-op trace handle returned when outside a span context.
   # All methods do nothing, preventing crashes when called outside traced code.
   class NoOpCurrentTrace
+    def trace_function_key
+      ""
+    end
+
     def set_session_id(_session_id)
       # No-op
     end

metadata

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