bitfab 0.23.6 → 0.23.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc6488982aa89cb2226e627f80da9bd85a1575bac14728aa81d2d5974c920aae
-  data.tar.gz: 519b07afa8c9a7220d730b7bc72b5e8a3cddb037b3e2b70bd36b476c4d400d29
+  metadata.gz: 342b5de3b40edd60f060465123f21d1c5338063340b34ac7bb7067c7baedfe55
+  data.tar.gz: 2f73bec442f3570efe78253d28733942e00b46c03a26ce2731a72e778cd6d79f
 SHA512:
-  metadata.gz: 362409a4955d1eec6ac5b4c0309a87d65ce9722f517f4cc364931f89fb66adf1a5fe0b4ac1d5a847a7e9d7fc9559c4d2449de03b2c2d9900ded22e317db28518
-  data.tar.gz: 735836a1730cf48e2fb5370f755e667bf3912b96a21ca9b97375b7e4e1bfd43e34531e557c5d49f28482dbbe32c091ec5bb08cc86fc9656b4f44a6edd7880b0f
+  metadata.gz: c76023257bcdd959cb49d6881faf05e85013b2d30c02826fd57a2a2aa8a72d72d7f8f10716f9f4b2d850a84dfb4a6ef7151077b88f43e2e1e7bd5b4c81ed23ff
+  data.tar.gz: 37fb2e1215527c780253dd35e10e4ff01d735336d068d5d8ac16a75d4fcc17e1749f7718cf8ffc550e965a27a9f0ee8fb49b2b847724c10a1ae031f0f1470574

data/lib/bitfab/client.rb

@@ -13,6 +13,7 @@ require_relative "warn_once"
 module Bitfab
   class Client
     SPAN_TYPES = %w[llm agent function guardrail handoff custom].freeze
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
 
     # Sentinel returned by check_mock_replay when this span should run real
     # code (no mock active, wrong strategy, or no matching historical entry).
@@ -115,6 +116,26 @@ module Bitfab
       BitfabFunction.new(self, trace_function_key)
     end
 
+    # Fetch one persisted span without loading the full trace.
+    # Exactly one of id or name is required. Name lookups return the last
+    # matching span by default; occurrence also accepts "first" or a zero-based
+    # Integer index.
+    def get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")
+      validate_trace_id(trace_id)
+      raise ArgumentError, "Provide exactly one of id or name" if id.nil? == name.nil?
+      validate_span_id(id) unless id.nil?
+      if !name.nil? && (!name.is_a?(String) || name.empty?)
+        raise ArgumentError, "name must be a non-empty string"
+      end
+
+      valid_occurrence = %w[first last].include?(occurrence) || (occurrence.is_a?(Integer) && occurrence >= 0)
+      unless valid_occurrence
+        raise ArgumentError, 'occurrence must be "first", "last", or a non-negative integer'
+      end
+
+      @http_client.get_trace_span(trace_id, id:, name:, occurrence:)
+    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:,
@@ -343,6 +364,14 @@ module Bitfab
 
     private
 
+    def validate_trace_id(trace_id)
+      raise ArgumentError, "trace_id must be a valid Bitfab trace ID" unless trace_id.is_a?(String) && UUID_PATTERN.match?(trace_id)
+    end
+
+    def validate_span_id(id)
+      raise ArgumentError, "id must be a valid Bitfab span ID" unless id.is_a?(String) && UUID_PATTERN.match?(id)
+    end
+
     # Resolve the API key lazily, the first time a span actually needs it.
     #
     # The key is intentionally NOT read at construction: a client built when a
@@ -462,6 +491,7 @@ module Bitfab
       end
 
       payload = {
+        "id" => trace_id,
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "traceFunctionKey" => trace_function_key,
@@ -492,7 +522,7 @@ module Bitfab
 
     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:, test_run_id: nil, input_source_span_id: nil)
+      started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil, mocked: false)
       # If drop() was called on this trace, suppress the span PAYLOAD upload for
       # every span that completes after the flag was set. The trace completion
       # still rides out with dropped: true, so the server scrubs any sibling
@@ -540,6 +570,8 @@ module Bitfab
       raw_span["input_source_span_id"] = input_source_span_id if input_source_span_id
 
       payload = {
+        "id" => span_id,
+        "traceId" => trace_id,
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "sourceTraceId" => trace_id,
@@ -547,6 +579,10 @@ module Bitfab
         "rawSpan" => raw_span
       }
       payload["testRunId"] = test_run_id if test_run_id
+      # Flag spans served from the original trace's recorded output during a
+      # replay so the trace view can mark them (matches the Python and
+      # TypeScript SDKs).
+      payload["mocked"] = true if mocked
 
       # A value that could only be captured as a placeholder makes the span
       # non-replayable; record it on the payload's errors (matching the Python
@@ -644,7 +680,8 @@ module Bitfab
         started_at:,
         ended_at:,
         test_run_id:,
-        input_source_span_id:
+        input_source_span_id:,
+        mocked: true
       )
       # Mocked spans are always non-root (advance_mock_counter returns nil for
       # root spans, so check_mock_replay never short-circuits them), so the

data/lib/bitfab/http_client.rb

@@ -80,7 +80,7 @@ module Bitfab
       http.open_timeout = request_timeout
       http.read_timeout = request_timeout
 
-      req = Net::HTTP::Get.new(uri.path, headers)
+      req = Net::HTTP::Get.new(uri.request_uri, headers)
       response = http.request(req)
 
       unless response.is_a?(Net::HTTPSuccess)
@@ -140,6 +140,19 @@ module Bitfab
       get("/api/sdk/externalSpans/#{span_id}", timeout: 30)
     end
 
+    def get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")
+      query = if id
+        {id:}
+      else
+        {name:, occurrence: occurrence.to_s}
+      end
+      encoded_trace_id = URI.encode_www_form_component(trace_id)
+      get(
+        "/api/sdk/traces/#{encoded_trace_id}/span?#{URI.encode_www_form(query)}",
+        timeout: 30
+      )["span"]
+    end
+
     # Fetch the span tree rooted at an external span. Blocking GET request.
     # Used by replay when a mock strategy is active so child spans can be
     # matched against their historical outputs.

data/lib/bitfab/span_context.rb

@@ -7,6 +7,11 @@ module Bitfab
       @span_state = span_state
     end
 
+    # The Bitfab ID for the current span.
+    def id
+      @span_state[:span_id]
+    end
+
     # The trace ID for the current span.
     def trace_id
       @span_state[:trace_id]

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -18,6 +18,10 @@ module Bitfab
   # No-op span handle returned when outside a span context.
   # All methods do nothing, preventing crashes when called outside traced code.
   class NoOpCurrentSpan
+    def id
+      ""
+    end
+
     def trace_id
       ""
     end

metadata

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