Ruby SDK Reference

Gem: bitfab. Ruby ≥ 3.1. Uses a global singleton client pattern (Bitfab.configure / Bitfab.client).

Framework Integrations

No framework-native adapters are shipped for Ruby yet. Instrument Ruby code manually via Bitfab::Traceable / Bitfab.span. See the Ruby SDK guide. Framework coverage status: Frameworks overview.

Module Layout

Bitfab                   # top-level module & singleton facade
Bitfab::Client           # the underlying client class
Bitfab::BitfabFunction   # fluent wrapper bound to one trace_function_key
Bitfab::Traceable        # mixin for declarative span tracing
Bitfab::CurrentSpan      # span handle
Bitfab::CurrentTrace     # trace handle
Bitfab::NoOpCurrentSpan  # returned outside a span context
Bitfab::NoOpCurrentTrace # returned outside a span context
Bitfab::Replay           # replay orchestration (internal)
Bitfab::ReplayContext    # thread-local replay context (internal)
Bitfab::ReplayEnvironment # per-trace DB branch exposed during replay
Bitfab::SpanContext      # thread-local span stack (internal)
Bitfab::TraceState       # trace state storage (internal)
Bitfab::MOCK_STRATEGIES  # %w[none all marked]
Bitfab::BITFAB_PROGRESS_PREFIX # wire prefix used by report_replay_progress

Module-Level API

`Bitfab.configure(api_key:, service_url: nil, enabled: true)`

Creates the global client. Subsequent calls replace it.

Param	Type	Default
`api_key:`	`String`	required
`service_url:`	`String, nil`	`"https://bitfab.ai"`
`enabled:`	`Boolean`	`true`

Empty/whitespace api_key prints a warning and sets enabled = false.

`Bitfab.client`

Returns the configured Bitfab::Client. Raises RuntimeError("Bitfab not configured...") if configure has not been called.

`Bitfab.reset!`

Resets the global client to nil. Intended for tests.

`Bitfab.current_span`

Returns the active CurrentSpan, or Bitfab::NO_OP_SPAN outside a span context.

`Bitfab.current_trace`

Returns the active CurrentTrace, or Bitfab::NO_OP_TRACE outside a span context.

`Bitfab.report_replay_progress(progress)`

Ready-made on_progress-shaped callback. Pass it straight into replay as on_progress: Bitfab.method(:report_replay_progress). It writes the running totals to stderr (prefixed with Bitfab::BITFAB_PROGRESS_PREFIX), which the Bitfab plugin polls to report live progress while the replay runs in the background, while stdout remains available for direct-run ReplayResult JSON. It never raises.

`class Bitfab::Client`

`SPAN_TYPES`

Bitfab::Client::SPAN_TYPES  # => %w[llm agent function guardrail handoff custom]

`attr_reader :api_key, :service_url, :enabled`

`get_trace_span`

get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")

Fetches one persisted span without loading its trace. trace_id is the canonical Bitfab trace ID. Exactly one of the span’s Bitfab id or name is required. occurrence accepts "first", "last", or a zero-based integer and defaults to "last". Returns nil when no trace or span matches.

`initialize(api_key:, service_url: nil, enabled: true)`

Same semantics as Bitfab.configure.

`replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil, max_concurrency: 10, code_change_description: nil, code_change_files: nil, mock: "marked", experiment_group_id: nil, dataset_id: nil, grader_ids: nil, environment: nil, on_progress: nil)`

Param	Type	Description
`receiver`	`Object` or `Class`	Instance for instance methods; class for class methods
`method_name`	`Symbol`	Method to replay
`trace_function_key:`	`String`	Trace function key for this method. Must match the key the method is traced under (`bitfab_span` / `Bitfab::Traceable.wrap`); a contradicting key raises `ArgumentError`.
`limit:`	`Integer, nil`	Max recent traces to replay (default `5`; maximum 5,000). Ignored when `trace_ids:` or `dataset_id:` is passed
`trace_ids:`	`Array<String>, nil`	Optional explicit trace IDs (max 100; the ID count determines how many traces replay)
`name:`	`String, nil`	Optional display name for the resulting experiment/test run
`max_concurrency:`	`Integer, nil`	Max parallel threads (default `10`; `nil` = unlimited)
`code_change_description:`	`String, nil`	Optional rationale for the code change being tested (stored on the experiment)
`code_change_files:`	`Array<Hash>, nil`	Optional list of edited files, each `{ path:, before:, after: }`
`mock:`	`String`	Mock strategy for child spans: `"marked"` (default), `"none"`, or `"all"`. Raises `ArgumentError` on any other value.
`experiment_group_id:`	`String, nil`	Optional UUID that groups multiple replay runs into a single experiment batch
`dataset_id:`	`String, nil`	Optional UUID of the dataset this replay runs against; durably attributes the experiment to that dataset
`grader_ids:`	`Array<String>, nil`	Optional UUIDs of graders attached directly to this run (max 100), unioned with the dataset’s runnable graders when the experiment is graded. Each must be an active grader in the same organization and trace function, or the replay is rejected with a 400
`environment:`	`Bitfab::ReplayEnvironment, nil`	Optional. When passed, the server resolves a per-trace DB branch and exposes it inside the replayed method via `environment.database_url` (read `environment.active?` first; it is `false` when no branch was resolved)
`on_progress:`	`#call, nil`	Optional callback fired per item as it settles, with a running-totals hash `{ test_run_id:, completed:, total:, succeeded:, errored:, item: }`. `item[:trace_id]` is `nil` during the run (the server replay id isn’t known until completion), while `item[:original_trace_id]` is the original historical trace (`:source_trace_id` is a deprecated alias); the item also carries `input`, `result`, `original_output`, `error`, `duration_ms`, `tokens`, `model`, and `db_snapshot_ref`. Render live progress while replay runs; totals only split ran-ok vs errored (pass/fail isn’t known yet). A raising callback never crashes the run. The SDK provides a ready-made reporter, `Bitfab.report_replay_progress`, you can pass straight in (`on_progress: Bitfab.method(:report_replay_progress)`): it writes the running totals plus settled item payload to stderr, which the Bitfab plugin polls to report live progress and write per-item result files while the replay runs in the background, so scripts never hand-format the protocol.

Returns: Hash with keys :items, :test_run_id, :test_run_url. Each item has :input, :result, :original_output, :error, :duration_ms (Integer, nil), :tokens ({ input:, output:, cached:, total: } or nil), :model (String, nil), :trace_id (String, nil), :original_trace_id (String, nil), :original_span_id (String, nil), the deprecated aliases :source_trace_id and :source_span_id, and :db_snapshot_ref (Hash, nil, the source trace’s snapshot pin, if any). :duration_ms and :model come from the historical trace the item replays; :tokens is the replayed run’s token usage (compare it against the original trace’s recorded usage); :trace_id is the new replay trace’s server id, written in after the run completes (nil on older servers); :original_trace_id and :original_span_id identify the original trace and root span being replayed. Mock strategies:

"marked": only child spans declared with mock_on_replay: true return historical output. Falls through to real execution when no historical entry matches. Default.
"none": every child span runs real code.
"all": every child span returns its historical output; real code is not executed.

Repeated calls to the same trace_function_key are distinguished by call order (step:0, step:1, …). The per-key counter advances on every non-root child invocation (including unmarked ones), so a marked sibling following an unmarked sibling lines up with the right historical entry.

`get_function(trace_function_key)`

Returns a Bitfab::BitfabFunction bound to trace_function_key. Mirrors client.get_function in the Python SDK and client.getFunction in TypeScript.

`execute_span(...)` (internal)

Called by Traceable. Not intended for direct use.

`class Bitfab::BitfabFunction`

Fluent wrapper bound to a single trace_function_key, returned by Bitfab::Client#get_function.

`attr_reader :trace_function_key`

`wrap(klass, method_name, name: nil, type: "custom", mock_on_replay: false)`

Wraps method_name on klass with span tracing under the bound trace_function_key. Delegates to Bitfab::Traceable.wrap.

`module Bitfab::Traceable`

Mixin for declarative instance-method tracing.

`include Bitfab::Traceable`

Extends the including class with ClassMethods below.

Class Methods (after `include`)

`bitfab_function(key)`

Sets the default trace_function_key for all bitfab_span declarations in this class.

`bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false)`

Wraps method_name with span tracing.

Param	Type	Default
`method_name`	`Symbol`	required
`trace_function_key:`	`String, nil`	falls back to the class-level `bitfab_function` key
`name:`	`String, nil`	defaults to `method_name.to_s`
`type:`	`String`	`"custom"` (one of `SPAN_TYPES`)
`mock_on_replay:`	`Boolean`	`false`; when `true`, replay returns this span’s historical output under the default `"marked"` mock strategy

Supports three call styles:

Before def: registered via method_added hook, wrapped when method is defined
Inline: bitfab_span def foo ... end, type: "function" (Ruby’s def returns :foo)
After def: wraps immediately if the method already exists

Raises RuntimeError if no trace_function_key is provided and no class-level bitfab_function was set.

Module-Level Wrapping

`Bitfab::Traceable.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom", mock_on_replay: false)`

Wraps a method on a class you do not own. Uses Module#prepend.

Param	Type
`klass`	`Class` or `Module`
`method_name`	`Symbol`
`trace_function_key:`	`String`
`name:`	`String, nil`
`type:`	`String`
`mock_on_replay:`	`Boolean`

`class Bitfab::CurrentSpan`

def id        # => canonical Bitfab span ID
def trace_id  # => String
def add_context(context)  # Hash → appends one entry; ignores non-Hash; never raises
def set_prompt(prompt)    # String → overwrites; ignores non-String; never raises

`class Bitfab::CurrentTrace`

def set_session_id(session_id)  # String
def set_metadata(metadata)      # Hash → shallow-merge, later keys win
def add_context(context)        # Hash → appends entry
def drop                        # flags the trace to be dropped at completion

All methods swallow exceptions internally; they never raise. drop flags the trace to be dropped: once flagged, spans that complete afterward are not uploaded at all, and the flag rides out on the completion payload, so at completion the server scrubs any payloads that already raced out (the trace, its external trace, and sibling spans), deletes the archived S3 objects, and marks it dropped instead of completed, keeping only a skeleton audit row. Calling it outside a span (on NO_OP_TRACE) is a no-op.

`class Bitfab::NoOpCurrentSpan` / `NoOpCurrentTrace`

Singleton instances exposed as Bitfab::NO_OP_SPAN and Bitfab::NO_OP_TRACE. All methods are no-ops. id and trace_id return "".

Thread & Concurrency Model

Span stack is stored in Thread.current[:__bitfab_span_stack] (not propagated to child threads automatically)
Trace state is stored in a mutex-protected module-level hash (Bitfab::TraceState) keyed by trace_id
Span HTTP sends run in background threads; the client tracks pending threads per trace

Error Behavior Summary

Situation	Behavior
Empty `api_key`	Warning via `warn`, `enabled` forced to `false`
`bitfab_span` method raises	Span records `error` and `error_source: "code"`, exception re-raised
`add_context` / `set_prompt` with invalid input	Silently ignored. Never raises
Span transport failure	Swallowed. Host app never crashes
`Bitfab.client` before `configure`	`RuntimeError("Bitfab not configured...")`
`bitfab_span` without `trace_function_key`	`RuntimeError`
`replay` — `trace_function_key:` differs from the method’s declared key	`ArgumentError` (key mismatch)

​Framework Integrations

​Module Layout

​Module-Level API

​Bitfab.configure(api_key:, service_url: nil, enabled: true)

​Bitfab.client

​Bitfab.reset!

​Bitfab.current_span

​Bitfab.current_trace

​Bitfab.report_replay_progress(progress)

​class Bitfab::Client

​SPAN_TYPES

​attr_reader :api_key, :service_url, :enabled

​get_trace_span

​initialize(api_key:, service_url: nil, enabled: true)

​replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil, max_concurrency: 10, code_change_description: nil, code_change_files: nil, mock: "marked", experiment_group_id: nil, dataset_id: nil, grader_ids: nil, environment: nil, on_progress: nil)

​get_function(trace_function_key)

​execute_span(...) (internal)

​class Bitfab::BitfabFunction

​attr_reader :trace_function_key

​wrap(klass, method_name, name: nil, type: "custom", mock_on_replay: false)

​module Bitfab::Traceable

​include Bitfab::Traceable

​Class Methods (after include)

​bitfab_function(key)

​bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false)

​Module-Level Wrapping

​Bitfab::Traceable.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom", mock_on_replay: false)

​class Bitfab::CurrentSpan

​class Bitfab::CurrentTrace

​class Bitfab::NoOpCurrentSpan / NoOpCurrentTrace

​Thread & Concurrency Model

​Error Behavior Summary