TypeScript SDK

# npm
npm install @bitfab/sdk

# pnpm
pnpm add @bitfab/sdk

# yarn
yarn add @bitfab/sdk

import { Bitfab } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

new Bitfab({ apiKey: string })

// Omit apiKey entirely: the SDK reads BITFAB_API_KEY from the environment
new Bitfab({})

// Turn capture off (functions still execute, but no spans are sent)
new Bitfab({ apiKey: string, captureEnabled: false })

// Pass a function to defer resolution explicitly (resolved at first use):
new Bitfab({ apiKey: () => process.env.BITFAB_API_KEY })

// Throws on the first traced call if no key resolves, instead of disabling quietly
new Bitfab({ apiKey: process.env.BITFAB_API_KEY, strict: true })

pnpm add -D @bitfab/transform

node --import @bitfab/transform/register src/server.ts
node --import tsx --import @bitfab/transform/register src/server.ts

BITFAB_SDK_RESOLVE_FROM=./packages/actor/package.json node --import ./packages/actor/node_modules/@bitfab/transform/dist/register.js packages/actor/src/server.ts

import { Bitfab } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

class SupportAgent {
  @bitfab.trace("support-agent", {
    name: "support-agent-root",
    type: "agent",
    mockOnReplayDefault: true,
    maxDepth: 30,
    maxSpans: 500,
    exclude: ["debugPayload"],
  })
  async run(message: string) {
    const request = await this.prepare(message)
    return this.generate(request)
  }

  @bitfab.node({ mockOnReplay: false })
  private async prepare(message: string) {
    return { message: message.trim() }
  }

  @bitfab.node({ name: "Model call", type: "llm" })
  private async generate(request: { message: string }) {
    return callModel(request)
  }
}

export const runSupportAgent = bitfab.withTrace(
  "support-agent",
  {
    type: "agent",
    mockOnReplayDefault: true,
    maxDepth: 30,
    maxSpans: 500,
  },
  async function runSupportAgent(message: string) {
    const request = await prepare(message)
    return generate(request)
  },
)

const generate = bitfab.withNode(
  { name: "Model call", type: "llm" },
  async function generate(request: { message: string }) {
    return callModel(request)
  },
)

const buildTicketDetail = bitfab.withTrace("ticket-detail", (ticket: Ticket) =>
  enrichTicket(ticket),
)

const processTicket = bitfab.withTrace("ticket-workflow", (ticket: Ticket) =>
  buildTicketDetail(ticket),
)

await processTicket(ticket)
// Records two traces:
// ticket-workflow -> buildTicketDetail -> enrichTicket
// ticket-detail   -> enrichTicket

MixedTracingError: opt-in and opt-out tracing can't be mixed in one call stack: withSpan() (opt-in)
for "fetch-context" was entered inside a withTrace() call (opt-out). Inside a withTrace/trace subtree,
configure a discovered call with node()/withNode() instead, or trace this workflow with withSpan() only.

const orderService = bitfab.getFunction("order-processing")

async function loadOrder(orderId: string) {
  return db.orders.findById(orderId)
}
const tracedLoadOrder = orderService.withSpan({ mockOnReplay: true }, loadOrder)

async function classifyOrder(order: Order) {
  return generateObject({ model, schema, prompt: buildPrompt(order) })
}
const tracedClassifyOrder = orderService.withSpan({ type: "llm" }, classifyOrder)

async function validateOrder(classification: Classification) {
  return { valid: classification.confidence > 0.8 }
}
const tracedValidateOrder = orderService.withSpan(validateOrder)

async function processOrder(orderId: string) {
  const order = await tracedLoadOrder(orderId)
  const classification = await tracedClassifyOrder(order)
  return tracedValidateOrder(classification)
}
const tracedProcessOrder = orderService.withSpan({ type: "agent" }, processOrder)

processOrder
├── loadOrder
├── classifyOrder
└── validateOrder

// lib/bitfab.ts -- single source of truth
import { Bitfab } from "@bitfab/sdk"
const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
export const orderService = bitfab.getFunction("order-processing")

// services/validateOrder.ts
import { orderService } from "../lib/bitfab"

async function validateOrder(orderId: string) {
  return { valid: true }
}

export const tracedValidateOrder = orderService.withSpan(validateOrder)

// services/processOrder.ts
import { orderService } from "../lib/bitfab"
import { tracedValidateOrder } from "./validateOrder"

async function processOrder(orderId: string) {
  await tracedValidateOrder(orderId)
  return { orderId }
}

export const tracedProcessOrder = orderService.withSpan(processOrder)

// ✅ GOOD -- pass function directly, arguments are captured as span input
const result = await orderService.withSpan(
  { name: "ProcessOrder", type: "function" },
  processOrder,
)(orderId)

// ❌ BAD -- anonymous wrapper loses all input capture (span has no input)
const result = await orderService.withSpan(
  { name: "ProcessOrder", type: "function" },
  async () => processOrder(orderId),
)()

const standaloneTask = bitfab.withSpan("one-off-operation", () => {
  return "done"
})

const outer = bitfab.withSpan("outer", { type: "agent" }, async () => {
  await inner()  // Becomes a child of "outer"
})

const inner = bitfab.withSpan("inner", { type: "function" }, async () => {
  // ...
})

const helper = bitfab.withSpan(
  "workflow",
  { type: "function", captureWhen: "nested" },
  async (input: string) => transform(input),
)
const workflow = bitfab.withSpan("workflow", async (input: string) => {
  return helper(input)
})

await helper("standalone") // Runs normally without creating a trace
await workflow("nested")   // Captures helper as a child

const pipeline = bitfab.getFunction("document-pipeline")

class DocumentService {
  @pipeline.span({ type: "agent" })
  async process(text: string): Promise<string> {
    return this.#normalize(text)
  }

  @pipeline.span({ type: "function", captureWhen: "nested" })
  async #normalize(text: string): Promise<string> {
    return text.trim().toLowerCase()
  }
}

class DocumentClassifier {
  @bitfab.span("document-classification", { type: "llm" })
  static async classify(text: string): Promise<string> {
    return classifyDocument(text)
  }
}

type SpanType =
  | "llm"        // LLM calls
  | "agent"      // Agent workflows
  | "function"   // Function calls
  | "guardrail"  // Safety checks
  | "handoff"    // Human handoffs
  | "custom"     // Default

// Function name is automatically captured as span name
async function processOrder(orderId: string) {
  return { orderId }
}
const traced = bitfab.withSpan("order-processing", processOrder)
// Span name: "processOrder"

// Override with name option
const traced = bitfab.withSpan(
  "order-processing",
  { name: "OrderProcessor" },
  processOrder
)
// Span name: "OrderProcessor"

// Set span type
const checkSafety = bitfab.withSpan(
  "safety-check",
  { type: "guardrail" },
  async (content: string) => ({ safe: true })
)

// With getFunction()
const service = bitfab.getFunction("order-processing")
const traced = service.withSpan({ name: "CustomName", type: "function" }, processOrder)

import { openai } from "@ai-sdk/openai"
import { streamText, wrapLanguageModel } from "ai"
import { finalizers } from "@bitfab/sdk"

// Wrap the model too, or the root is the only span in the trace
const model = wrapLanguageModel({
  model: openai("gpt-4o"),
  middleware: bitfab.getVercelAiMiddleware("chat-turn"),
})

const runChatTurn = bitfab.withSpan(
  "chat-turn",
  { type: "agent", finalize: finalizers.aiSdk },
  () => streamText({ model, messages }),
)

// In your route handler:
const result = runChatTurn()                  // live StreamTextResult
return result.toUIMessageStreamResponse()     // stream to the user as usual
// The span records { text, usage, finishReason, toolCalls } in the background.

chat-turn
└── chat-turn (llm)

const runChatTurn = bitfab.withSpan(
  "chat-turn",
  {
    type: "agent",
    finalize: async (r) => ({ answer: await r.text, tokens: await r.totalUsage }),
  },
  () => streamText({ model, messages }),
)

import { finalizers } from "@bitfab/sdk"

let live: ReadableStream
const traced = bitfab.withSpan(
  "render",
  { finalize: (r) => finalizers.readableStream(r, (s) => { live = s }) },
  () => makeReadableStream(),
)
traced()
return new Response(live!)

const chatTurn = bitfab.getFunction("chat-turn")

const streamFromService = chatTurn.withSpan({ name: "stream-service" }, async function* () {
  yield "first"
  yield "second"
})

const handleChunk = chatTurn.withSpan({ name: "handle-chunk" }, async (chunk: string) => chunk)

const runController = chatTurn.withSpan({ name: "controller", type: "agent" }, async () => {
  for await (const chunk of streamFromService()) {
    await handleChunk(chunk)
  }
})

await runController()

import { getCurrentSpan } from "@bitfab/sdk"

async function processOrder(orderId: string) {
  const userId = await getCurrentUser()
  getCurrentSpan()?.addContext({ user_id: userId, order_id: orderId })
  return { orderId, status: "completed" }
}

const traced = bitfab.withSpan("order-processing", { type: "function" }, processOrder)

getCurrentSpan()?.addContext({ user_id: "u-123" })
getCurrentSpan()?.addContext({ request_id: "req-789" })
// Result: contexts: [{ user_id: "u-123" }, { request_id: "req-789" }]

import { getCurrentSpan } from "@bitfab/sdk"

const traced = bitfab.withSpan("my-function", async () => {
  const { id, traceId } = getCurrentSpan()
  console.log("Current span:", id, "trace:", traceId)
  return { id, traceId }
})

import { getCurrentSpan } from "@bitfab/sdk"

async function classifyText(text: string) {
  const prompt = `Classify the following text: ${text}`
  getCurrentSpan()?.setPrompt(prompt)
  const result = await llm.complete(prompt)
  return result
}

const traced = bitfab.withSpan("classification", { type: "llm" }, classifyText)

import { getCurrentTrace } from "@bitfab/sdk"

const traced = bitfab.withSpan("order-processing", { type: "function" }, async () => {
  const trace = getCurrentTrace()

  // Set session ID (stored as database column, filterable in dashboard)
  trace?.setSessionId("session-123")

  // Name the trace (its title in Bitfab, searchable and filterable)
  trace?.setName("Order 8f21")

  // Set trace metadata (stored in raw trace data)
  trace?.setMetadata({ region: "us-west-2", environment: "production" })

  // Add context entries (stored as key-value pairs, accumulates across calls)
  trace?.addContext({ workflow: "checkout-flow", batch_id: "batch-2024-01" })

  return { status: "completed" }
})

import { getCurrentTrace } from "@bitfab/sdk"

const traced = bitfab.withSpan("order-processing", { type: "function" }, async () => {
  if (isHealthCheck) {
    getCurrentTrace()?.drop()
  }

  return { status: "completed" }
})

const trace = client.getTrace(traceId)
await trace.addContext({ refund_status: "approved" })
await trace.setMetadata({ region: "us-west" })
await trace.setSessionId("session_xyz")

const span = await client.getTraceSpan(traceId, { name: "GenerateAnswer" })
const first = await client.getTraceSpan(traceId, {
  name: "GenerateAnswer",
  occurrence: "first",
})
const exact = await client.getTraceSpan(traceId, { id: spanId })

const risky = bitfab.withSpan("risky-service", () => {
  throw new Error("error")
})

try {
  risky()
} catch (e) {
  // Span records error and timing
}

import { flushTraces } from "@bitfab/sdk"

if (!(await flushTraces(30_000))) {
  throw new Error("Bitfab traces were not delivered before the deadline")
}

new Bitfab({
  apiKey: string,                    // Required
  serviceUrl?: string,               // Default: https://bitfab.ai
  timeout?: number,                  // Request timeout in ms (default: 120000)
  envVars?: { OPENAI_API_KEY: string },  // For native function execution
  enabled?: boolean,                 // Default: true
  simulationPlan?: boolean,          // Read and apply the sim plan (default: true)
  bamlClient?: unknown               // Generated BAML client (for wrapBAML)
})

const pipeline = bitfab.getFunction("my-function")

const updatedFn = pipeline.withSpan(
  { name: "UpdatedPipeline", type: "function" },
  async (input: string) => {
    // New implementation to test
    return { result: input.toUpperCase() }
  },
)

// Replay all traces (up to limit)
const result = await bitfab.replay("my-function", updatedFn, {
  name: "Uppercase candidate",
  limit: 10,
  maxConcurrency: 5,  // Default: 10
  attempts: 3,  // Default: 1
})

// Replay specific traces by ID
const result2 = await bitfab.replay("my-function", updatedFn, {
  traceIds: ["trace-id-1", "trace-id-2"],
})

// Result structure
console.log(result.testRunId)   // Test run identifier
console.log(result.testRunUrl)  // Dashboard URL
for (const item of result.items) {
  console.log(item.input)           // Original input
  console.log(item.result)          // New output
  console.log(item.originalOutput)  // Original output
  console.log(item.error)           // Error if any
  console.log(item.durationMs)         // How long THIS run took, in ms (or null)
  console.log(item.originalDurationMs) // The replayed trace's duration in ms (or null)
  console.log(item.tokens)          // { input, output, cached, total } or null
  console.log(item.model)           // Original model name, or null
  console.log(item.traceId)         // Server trace ID for the replayed execution
}

// scripts/replay.ts
import { graph } from "../src/agent"          // the compiled LangGraph graph
import { bitfab } from "../src/bitfabClient"  // same client as instrumentation

const handler = bitfab.getLangGraphCallbackHandler("my-agent")  // same key

const replayMyAgent = async (state: AgentState) =>
  graph.invoke(state, {
    callbacks: [handler],
    configurable: buildReplayConfig(),
  })

const result = await bitfab.replay("my-agent", replayMyAgent, { limit: 10 })

const articlePipeline = bitfab.getFunction("process-article")

const fetchArticle = articlePipeline.withSpan(
  { name: "fetch-article-from-db", mockOnReplay: true },
  async (id: string) => db.articles.findById(id),
)

const summarize = articlePipeline.withSpan(
  { name: "summarize-article" },
  async (article: Article) => summarizeWithNewPrompt(article),
)

const processArticle = articlePipeline.withSpan(
  { name: "process-article" },
  async (id: string) => summarize(await fetchArticle(id)),
)

// During replay, fetch-article-from-db returns its recorded output;
// summarize-article runs real so you can iterate on it.
const result = await bitfab.replay("process-article", processArticle, {
  limit: 10,
})

const result = await bitfab.replay("process-article", processArticle, {
  mock: "none", // run everything real...
  mockOverride: {
    // ...except this span, which gets the value you supply
    match: (node) => node.spanName === "fetch-article-from-db",
    value: { id: "fixed", title: "Fixed title" }, // a flat value
  },
})

value: async ({ inputs, getOriginalOutput }) => ({
  ...(await getOriginalOutput()),
  score: 1,
})

bitfab.registerMockOverride({
  match: (node) => node.type === "llm",
  value: { label: "refund" },
})
// or the ordered form: registerMockOverride(match, value)
bitfab.clearMockOverrides() // reset

bitfab.registerMockOverride("classify-intent", ({ inputs }) => ({
  label: String(inputs[0]),
}))

bitfab.registerMockOverride("shared-workflow", {
  match: (node) => node.spanName === "Classifier",
  value: { label: "refund" },
})

import { NO_MOCK_OVERRIDE } from "@bitfab/sdk"

bitfab.registerMockOverride(({ node, inputs }) => {
  if (node.traceFunctionKey === "classify-intent") {
    return { label: String(inputs[0]) }
  }
  return NO_MOCK_OVERRIDE
})

const result = await bitfab.replay("my-function", updatedFn, {
  // Recorded as (userId, limit); current signature is ({ userId, limit }).
  adaptInputs: (inputs, ctx) => {
    const [userId, limit] = inputs as [string, number]
    return [{ userId, limit }]
  },
})

// scripts/replay-adapters/extraction.ts
import type { AdaptInputsFn } from "@bitfab/sdk"

export const adaptInputs: AdaptInputsFn = (inputs, ctx) => {
  const [userId, limit] = inputs as [string, number]
  return [{ userId, limit }]
}

// scripts/replay.ts
import { adaptInputs } from "./replay-adapters/extraction"

await bitfab.replay("my-function", updatedFn, { limit, adaptInputs })

import { readFileSync } from "node:fs"

const before = readFileSync("src/foo.ts", "utf8")
// ...edit src/foo.ts...
const after = readFileSync("src/foo.ts", "utf8")

const result = await bitfab.replay("my-function", updatedFn, {
  name: "Retry fix candidate",
  codeChangeDescription: "fix off-by-one in retry logic",
  codeChangeFiles: [{ path: "src/foo.ts", before, after }],
})

const result = await bitfab.replay("my-function", updatedFn, { limit })

// Human-readable summary goes to stderr, so stdout stays pure JSON.
console.error(`Test run: ${result.testRunUrl}`)
console.error(`Items:    ${result.items.length}`)

// Full structured dump to stdout, ready for JSON.parse. The SDK serializer
// retains useful fields from traceError and replayError exception objects.
console.log(serializeReplayResult(result))

import "dotenv/config"
import { defineReplayRegistry } from "@bitfab/sdk"
import { bitfab } from "../lib/bitfab"
import { createSearchMock } from "./replayMocks"
import { extractMemories } from "../services/extraction"
import { searchDocuments } from "../services/search"

export default defineReplayRegistry({
  extraction: { client: bitfab, fn: extractMemories },
  search: {
    client: bitfab,
    fn: searchDocuments,
    // Plain handler functions need the key explicitly. A withSpan-wrapped
    // function carries its key, so `traceFunctionKey` can be omitted.
    traceFunctionKey: "my-search-pipeline",
    options: { mock: "marked" },
    optionsFactory: ({ params }) => ({
      mockOverride: createSearchMock(params.scenario),
    }),
  },
})

import { Bitfab } from "@bitfab/sdk"
import { runTicket } from "../services/agent"

const bitfab = new Bitfab({ captureEnabled: false })

const traceId = await bitfab.seedTrace("agent-turn", runTicket, {
  args: ["T-1"],
  metadata: { caseUid: "c-1", suite: "smoke" },
  name: "T-1",
})

const traceId = bitfab.seedTrace("support-agent", {
  input: [{ ticketId: "T-1", body: "Where is my refund?" }],
  expected: { intent: "refund_status" },
  fn: handleTicket,
  name: "T-1",
})

const { traceId, previousRunTraceId } = await bitfab.reseedTrace(
  "agent-turn",
  runTicket,
  { traceId: "3f2a..." },
)

bitfab-seed --registry scripts/replay.registry.ts extraction --from-trace 3f2a...

# Write each case directly, no execution.
bitfab-replay --registry scripts/replayRegistry.ts extraction --seed cases.jsonl

# Run each case once through the registered function and record it.
bitfab-replay --registry scripts/replayRegistry.ts extraction --seed cases.jsonl --run

const { dataset, created } = await bitfab.datasets.save({
  traceFunctionKey: "checkout-agent",
  name: "Refund failures",
  description: "Checkout runs where the refund was declined",
})

const added = await bitfab.datasets.addTraces(dataset.id, [traceId])
if (added.skippedTraceIds.length > 0) {
  console.warn("not in this trace function:", added.skippedTraceIds)
}

const { traceIds } = await bitfab.datasets.listTraces(dataset.id)
await bitfab.datasets.addGraders(dataset.id, [graderId])
const { run } = await bitfab.datasets.rerunGraders(dataset.id)
console.log(run.status, run.result)

const { assertions } = await bitfab.traces.getAssertions(item.originalTraceId)

await bitfab.labels.saveAll(
  assertions.map((assertion) => ({
    originalTraceId: item.originalTraceId,
    attempt: item.attempt,
    assertionId: assertion.id,
    label: judge(assertion, output),
    annotation: explain(assertion, output),
  })),
  testRunId,
)

const [labels] = await bitfab.labels.getAll([item.traceId])
for (const verdict of labels.assertions) {
  console.log(verdict.assertion, verdict.label, verdict.annotation)
}

const graded = await bitfab.graders.getLabels({ traceIds: [item.traceId] })