Ruby SDK

# Bundler
bundle add bitfab

# Gem
gem install bitfab

require "bitfab"

Bitfab.configure(api_key: ENV.fetch("BITFAB_API_KEY"))

Bitfab.configure(api_key: "...")

# Omit api_key entirely: the SDK reads ENV["BITFAB_API_KEY"]
Bitfab.configure

# Disable tracing (methods still execute, but no spans are sent)
Bitfab.configure(api_key: "...", enabled: false)

# Pass a Proc to defer resolution explicitly (resolved at first use):
Bitfab.configure(api_key: -> { ENV["BITFAB_API_KEY"] })

# Raises on the first traced call if no key resolves, instead of disabling quietly
Bitfab.configure(api_key: ENV["BITFAB_API_KEY"], strict: true)

class OrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  # The root calls the traced methods, so they record as its children
  bitfab_span :process_order, type: "agent"
  def process_order(order_id)
    order = load_order(order_id)
    classification = classify_order(order)
    validate_order(classification)
  end

  # Style 1: Before-def (recommended): declare bitfab_span above the method
  bitfab_span :load_order, mock_on_replay: true
  def load_order(order_id)
    Order.find(order_id)
  end

  # Style 2: Inline: wrap the def directly
  bitfab_span def classify_order(order)
    client.responses.parse(model: MODEL, input: build_prompt(order))
  end, type: "llm"

  # Style 3: After-def: declare bitfab_span after the method definition
  def validate_order(classification)
    { valid: classification.confidence > 0.8 }
  end
  bitfab_span :validate_order, type: "guardrail"
end

process_order
├── load_order
├── classify_order
└── validate_order

# config/initializers/bitfab.rb (single source of truth)
require "bitfab"
Bitfab.configure(api_key: ENV.fetch("BITFAB_API_KEY"))

# app/services/process_order_service.rb
class ProcessOrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  bitfab_span :process_order, type: "function"
  def process_order(order_id)
    ValidateOrderService.new.validate_order(order_id)
    { order_id: }
  end
end

# app/services/validate_order_service.rb
class ValidateOrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  bitfab_span :validate_order, type: "guardrail"
  def validate_order(order_id)
    { valid: true }
  end
end

class StandaloneService
  include Bitfab::Traceable

  bitfab_span :standalone_task, trace_function_key: "one-off-operation"
  def standalone_task
    "done"
  end
end

class Pipeline
  include Bitfab::Traceable
  bitfab_function "pipeline"

  bitfab_span :outer, type: "agent"
  def outer
    inner  # Becomes a child of "outer"
  end

  bitfab_span :inner, type: "function"
  def inner
    # ...
  end
end

class Pipeline
  include Bitfab::Traceable
  bitfab_function "pipeline"

  bitfab_span :helper, type: "function", capture_when: "nested"
  def helper
    # ...
  end
end

Pipeline.new.helper # Runs normally without creating a trace when no parent is active

SPAN_TYPES = %w[
  llm        # LLM calls
  agent      # Agent workflows
  function   # Function calls
  guardrail  # Safety checks
  handoff    # Human handoffs
  custom     # Default
]

class SafetyService
  include Bitfab::Traceable
  bitfab_function "safety-service"

  # Method name is automatically captured as span name
  bitfab_span :check_safety, type: "guardrail"
  def check_safety(content)
    { safe: !content.include?("unsafe") }
  end

  # Override with name option
  bitfab_span :validate_input, name: "InputValidator", type: "guardrail"
  def validate_input(input)
    { valid: !input.empty? }
  end
end

class OrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  bitfab_span :process_order, type: "function"
  def process_order(order_id)
    user_id = current_user_id
    Bitfab.current_span.add_context("user_id" => user_id, "order_id" => order_id)
    { order_id: order_id, status: "completed" }
  end
end

Bitfab.current_span.add_context("user_id" => "u-123")
Bitfab.current_span.add_context("request_id" => "req-789")
# Result: contexts: [{ "user_id" => "u-123" }, { "request_id" => "req-789" }]

span_id = Bitfab.current_span.id
trace_id = Bitfab.current_span.trace_id

class ClassificationService
  include Bitfab::Traceable
  bitfab_function "classification"

  bitfab_span :classify_text, type: "llm"
  def classify_text(text)
    prompt = "Classify the following text: #{text}"
    Bitfab.current_span.set_prompt(prompt)
    llm.complete(prompt)
  end
end

class OrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  bitfab_span :process_order, type: "function"
  def process_order(order_id)
    trace = Bitfab.current_trace

    # Set session ID (stored as database column, filterable in dashboard)
    trace.set_session_id("session-123")

    # Name the trace (its title in Bitfab, searchable and filterable)
    trace.set_name("Order #{order_id}")

    # Set trace metadata (stored in raw trace data)
    trace.set_metadata("region" => "us-west-2", "environment" => "production")

    # Add context entries (stored as key-value pairs, accumulates across calls)
    trace.add_context("workflow" => "checkout-flow", "batch_id" => "batch-2024-01")

    { order_id: order_id, status: "completed" }
  end
end

span = Bitfab.client.get_trace_span(trace_id, name: "GenerateAnswer")
first = Bitfab.client.get_trace_span(trace_id, name: "GenerateAnswer", occurrence: "first")
exact = Bitfab.client.get_trace_span(trace_id, id: span_id)

class OrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  bitfab_span :process_order, type: "function"
  def process_order(order_id)
    Bitfab.current_trace.drop if health_check?(order_id)

    { order_id: order_id, status: "completed" }
  end
end

class RiskyService
  include Bitfab::Traceable
  bitfab_function "risky-service"

  bitfab_span :risky
  def risky
    raise "error"
  end
end

begin
  RiskyService.new.risky
rescue => e
  # Span records error and timing
end

raise "Bitfab traces were not delivered before the deadline" unless Bitfab.flush_traces(timeout: 30)

client = Bitfab::Client.new(api_key: ENV.fetch("BITFAB_API_KEY"))
begin
  # ... traced work ...
ensure
  client.close(timeout: 30)
end

require "openai"

Bitfab::Traceable.wrap(
  OpenAI::Client, :chat,
  trace_function_key: "openai",
  name: "Chat",
  type: "llm"
)

# Now all calls to client.chat are traced
client = OpenAI::Client.new(access_token: ENV["OPENAI_API_KEY"])
client.chat(parameters: { model: "gpt-4", messages: [...] })

client = Bitfab.client

# Pass an instance for instance methods
service = OrderService.new(api_key: "...", db: db)
result = client.replay(
  service, :process_order,
  trace_function_key: "order-processing",
  limit: 5
)

# Or pass a Class for class methods
result = client.replay(
  OrderService, :process_order,
  trace_function_key: "order-processing",
  limit: 5
)

puts "Test Run URL: #{result[:test_run_url]}"
puts "Test Run ID:  #{result[:test_run_id]}"

result[:items].each do |item|
  puts "Input: #{item[:input]}, Result: #{item[:result]}, Error: #{item[:error]}"
  puts "Duration (ms): #{item[:original_duration_ms]}"
  puts "Tokens: #{item[:tokens]}"    # { input:, output:, cached:, total: } or nil
  puts "Model: #{item[:model]}"
  puts "Trace ID: #{item[:trace_id]}" # Server trace ID for the replayed execution
end

service = OrderService.new(api_key: "...")
result = client.replay(
  service, :process_order,
  trace_function_key: "order-processing",
  trace_ids: ["trace-id-1", "trace-id-2"]
)

before = File.read("lib/order_service.rb")
# ...edit lib/order_service.rb...
after = File.read("lib/order_service.rb")

result = client.replay(
  service, :process_order,
  trace_function_key: "order-processing",
  code_change_description: "fix off-by-one in retry logic",
  code_change_files: [
    {path: "lib/order_service.rb", before:, after:}
  ]
)

# "marked" (default): only spans declared with mock_on_replay: true return historical output
client.replay(service, :process_order, trace_function_key: "order-processing")

# "none": every child span runs real code
client.replay(service, :process_order, trace_function_key: "order-processing", mock: "none")

# "all": every matched recorded child returns its historical output; only the root runs real code
client.replay(service, :process_order, trace_function_key: "order-processing", mock: "all")

class OrderService
  include Bitfab::Traceable
  bitfab_function "order-processing"

  # Paid LLM call: skip during replay by default
  bitfab_span :classify_intent, type: "llm", mock_on_replay: true
  def classify_intent(prompt); end

  # Cheap, deterministic: keep running real
  bitfab_span :persist, type: "function"
  def persist(order); end

  bitfab_span :process_order, type: "agent"
  def process_order(order)
    classify_intent(order.description)
    persist(order)
  end
end

result = client.replay(
  service, :process_order,
  trace_function_key: "order-processing",
  mock: "none", # run everything real...
  mock_override: {
    # ...except this span, which gets the value you supply
    match: ->(node) { node[:span_name] == "classify_intent" },
    value: { label: "refund" } # flat value
  }
)

value: ->(ctx) { ctx[:get_original_output].call.merge(score: 1) }

client.register_mock_override(
  match: ->(node) { node[:type] == "llm" },
  value: { label: "refund" }
)
# Positional form (equivalent): client.register_mock_override(match, value)
client.clear_mock_overrides

client.register_mock_override(
  "classify-intent",
  ->(ctx) { {label: ctx[:inputs].first.to_s} }
)

client.register_mock_override(
  "shared-workflow",
  {match: ->(node) { node[:span_name] == "Classifier" }, value: {label: "refund"}}
)

client.register_mock_override(lambda do |ctx|
  if ctx[:node][:trace_function_key] == "classify-intent"
    {label: ctx[:inputs].first.to_s}
  else
    Bitfab::NO_MOCK_OVERRIDE
  end
end)

fn = Bitfab.client.get_function("openai")

fn.wrap(OpenAI::Client, :chat, name: "Chat", type: "llm")
fn.wrap(OpenAI::Client, :embeddings, name: "Embed", type: "llm")

# Recorded as positional (user_id, limit); current signature takes a hash.
adapt = ->(args, _kwargs, _ctx) { [[{user_id: args[0], limit: args[1]}], {}] }

result = client.replay(
  service, :process_order,
  trace_function_key: "order-processing",
  adapt_inputs: adapt
)

# scripts/replay_adapters/extraction.rb
EXTRACTION_ADAPTER = ->(args, _kwargs, _ctx) do
  user_id, limit = args
  [[{user_id:, limit:}], {}]
end

# scripts/replay.rb
require_relative "replay_adapters/extraction"

client.replay(service, :extract_memories, trace_function_key: "my-function", adapt_inputs: EXTRACTION_ADAPTER)

result = Bitfab.client.replay(service, :process_order, trace_function_key: "order-processing", limit:)

# Human-readable summary goes to stderr, so stdout stays pure JSON.
warn "Test run: #{result[:test_run_url]}"
warn "Items:    #{result[:items].length}"

# Full structured dump to stdout, ready for JSON.parse. The SDK serializer
# retains useful fields from trace_error and replay_error exception objects.
puts Bitfab.serialize_replay_result(result)

require "dotenv/load"
require_relative "../config/initializers/bitfab"
require_relative "replay_mocks"
require_relative "../services/extraction_pipeline"
require_relative "../services/search_pipeline"

REGISTRY = Bitfab::ReplayRegistry.new
REGISTRY.register("extraction", ExtractionPipeline.new, :extract_memories)
REGISTRY.register(
  "search",
  SearchPipeline.new,
  :search_documents,
  # Plain handler methods need the key explicitly. A bitfab_span method carries
  # its key, so trace_function_key: can be omitted.
  trace_function_key: "my-search-pipeline",
  mock: "marked",
  options_factory: lambda { |ctx|
    {mock_override: ReplayMocks.search_mock(ctx.params["scenario"])}
  }
)

client = Bitfab.client
saved = client.datasets.save(
  trace_function_key: "checkout-agent",
  name: "Refund failures",
  description: "Checkout runs where the refund was declined"
)
dataset_id = saved["dataset"]["id"]

added = client.datasets.add_traces(dataset_id, [trace_id])
warn "not in this trace function: #{added["skippedTraceIds"]}" if added["skippedTraceIds"].any?

trace_ids = client.datasets.list_traces(dataset_id)["traceIds"]
client.datasets.add_graders(dataset_id, [grader_id])
run = client.datasets.rerun_graders(dataset_id)["run"]
puts run["status"], run["result"]