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"

  # Style 1: Before-def (recommended): declare bitfab_span above the method
  bitfab_span :process_order, type: "function"
  def process_order(order_id)
    { order_id: order_id }
  end

  # Style 2: Inline: wrap the def directly
  bitfab_span def validate_order(order_id)
    { valid: true }
  end, type: "guardrail"

  # Style 3: After-def: declare bitfab_span after the method definition
  def enrich_order(order_id)
    { enriched: true }
  end
  bitfab_span :enrich_order, type: "function"
end

# 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)
    { 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

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")

    # 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

Bitfab.flush_traces(timeout: 30)  # Default: 30s

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[: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 child span returns its historical output, real code never runs
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(
  processor, :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[:trace_function_key] == "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

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.
puts JSON.pretty_generate(result)

#!/usr/bin/env ruby
# Replay production traces through instrumented functions.
#
# Uses Bitfab.client.replay to fetch real traces and re-run them
# through the current code, creating a test run for side-by-side comparison.
#
# Usage:
#   ruby scripts/replay.rb <pipeline>
#   ruby scripts/replay.rb <pipeline> --limit 20
#   ruby scripts/replay.rb <pipeline> --trace-ids id1,id2

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

FUNCTIONS = {
  "extraction" => "my-extraction-pipeline",
  "search" => "my-search-pipeline",
}.freeze

pipeline = ARGV[0]

unless pipeline && FUNCTIONS.key?(pipeline)
  warn "Usage: ruby scripts/replay.rb <#{FUNCTIONS.keys.join('|')}> [--limit N] [--trace-ids id1,id2]"
  exit 1
end

limit = 10
trace_ids = nil

ARGV[1..].each_with_index do |arg, i|
  case arg
  when "--limit"
    limit = ARGV[i + 2].to_i
  when "--trace-ids"
    trace_ids = ARGV[i + 2].split(",").map(&:strip)
  end
end

# Each pipeline gets its own replay method. If a signature drifts after traces
# were captured, add an input adapter (see the "Adapting inputs" section):
# write scripts/replay_adapters/<name>.rb defining an adapter lambda, require it,
# and pass it here, e.g.
#   require_relative "replay_adapters/extraction"  # defines EXTRACTION_ADAPTER
#   adapt_inputs: EXTRACTION_ADAPTER

# limit is ignored when trace_ids is passed -- an explicit ID list already
# determines how many traces replay.

def replay_extraction(limit:, trace_ids:)
  service = ExtractionPipeline.new
  opts = trace_ids ? {trace_ids:} : {limit:}
  Bitfab.client.replay(
    service, :extract_memories,
    trace_function_key: FUNCTIONS["extraction"],
    # Live progress the Bitfab plugin polls while replay runs in the background.
    on_progress: Bitfab.method(:report_replay_progress),
    **opts
  )
end

def replay_search(limit:, trace_ids:)
  service = SearchPipeline.new
  opts = trace_ids ? {trace_ids:} : {limit:}
  Bitfab.client.replay(
    service, :search_documents,
    trace_function_key: FUNCTIONS["search"],
    on_progress: Bitfab.method(:report_replay_progress),
    **opts
  )
end

REPLAY_FNS = {
  "extraction" => method(:replay_extraction),
  "search" => method(:replay_search),
}.freeze

function_key = FUNCTIONS[pipeline]
# Human-readable output goes to stderr; stdout carries only the ReplayResult JSON.
$stderr.puts "[replay] Replaying #{trace_ids&.length || limit} traces from \"#{function_key}\"...\n"

result = REPLAY_FNS[pipeline].call(limit:, trace_ids:)
$stderr.puts "Test run: #{result[:test_run_url]}\n"

changed = same = errors = 0
result[:items].each do |item|
  raw_input = item[:input] || []
  label = (raw_input.first || "unknown").to_s[0, 80]

  if item[:error]
    $stderr.puts "  ✗ \"#{label}\""
    $stderr.puts "    Error: #{item[:error]}"
    errors += 1
  else
    orig = item[:original_output]
    new_val = item[:result]
    orig_str = orig.is_a?(String) ? orig : orig.to_json
    new_str = new_val.is_a?(String) ? new_val : new_val.to_json
    is_same = orig_str == new_str
    marker = is_same ? "=" : "Δ"

    $stderr.puts "  #{marker} \"#{label}\""
    $stderr.puts "    Original: #{orig_str}"
    $stderr.puts "    New:      #{new_str}"

    is_same ? same += 1 : changed += 1
  end
end

$stderr.puts "\n─── Summary ───"
$stderr.puts "  Pipeline: #{pipeline}"
$stderr.puts "  Replayed: #{result[:items].length}"
$stderr.puts "  Same:     #{same}"
$stderr.puts "  Changed:  #{changed}"
$stderr.puts "  Errors:   #{errors}" if errors > 0
$stderr.puts "\n  #{result[:test_run_url]}"

# Full ReplayResult as JSON to stdout (the Replay Output Contract).
puts JSON.pretty_generate(result)