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

// Leave it out and BITFAB_CAPTURE_ENABLED=0 or 1 decides
new Bitfab({ apiKey: string })

// 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 })

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

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

import { Bitfab } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
const supportAgent = bitfab.getFunction("support-agent")

class SupportAgent {
  @supportAgent.trace({
    name: "support-agent-root",
    type: "agent",
    mockOnReplayDefault: true,
    maxDepth: 30,
    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)
  }
}

const supportAgent = bitfab.getFunction("support-agent")

export const runSupportAgent = supportAgent.withTrace(
  {
    type: "agent",
    mockOnReplayDefault: true,
    maxDepth: 30,
  },
  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 supportAgent = bitfab.getFunction("support-agent")

export const runSupportAgent = bitfab.withTrace(
  "support-agent",
  { type: "agent" },
  async function runSupportAgent(message: string) {
    return generate(await prepare(message))
  },
)

const ticketDetail = bitfab.getFunction("ticket-detail")
const ticketWorkflow = bitfab.getFunction("ticket-workflow")

const buildTicketDetail = ticketDetail.withTrace((ticket: Ticket) =>
  enrichTicket(ticket),
)

const processTicket = ticketWorkflow.withTrace((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 oneOffOperation = bitfab.getFunction("one-off-operation")

const standaloneTask = oneOffOperation.withSpan(() => {
  return "done"
})

const outerFn = bitfab.getFunction("outer")
const innerFn = bitfab.getFunction("inner")

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

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

const workflowFn = bitfab.getFunction("workflow")

const helper = workflowFn.withSpan(
  { type: "function", captureWhen: "nested" },
  async (input: string) => transform(input),
)
const workflow = workflowFn.withSpan(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()
  }
}

const documentClassification = bitfab.getFunction("document-classification")

class DocumentClassifier {
  @documentClassification.span({ 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

const service = bitfab.getFunction("order-processing")
const safetyCheck = bitfab.getFunction("safety-check")

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

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

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

// Name and type together
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"

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

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

const runChatTurn = chatTurn.withSpan(
  { 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 chatTurn = bitfab.getFunction("chat-turn")

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

import { finalizers } from "@bitfab/sdk"

const renderFn = bitfab.getFunction("render")

let live: ReadableStream
const traced = renderFn.withSpan(
  { 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"

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

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

const traced = orderProcessing.withSpan({ 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 myFunction = bitfab.getFunction("my-function")

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

import { getCurrentSpan } from "@bitfab/sdk"

const classificationFn = bitfab.getFunction("classification")

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 = classificationFn.withSpan({ type: "llm" }, classifyText)

import { getCurrentTrace } from "@bitfab/sdk"

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

const traced = orderProcessing.withSpan({ 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 (indexed for exact-match search)
  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" }
})

const page = await client.traces.search({
  traceFunctionKey: "order-processing",
  callerMetadata: { ticket_id: "ABC-123", tenant: "tanagram" },
  limit: 50,
})

const exact = await client.traces.search({ name: "Order ABC-123" })
const partial = await client.traces.search({ nameContains: "order", limit: 50 })

for (const experimentId of [baselineExperimentId, candidateExperimentId]) {
  const { traces } = await client.traces.search({ experimentId, limit: 500 })
  const totalMs = traces.reduce((sum, t) => sum + (t.durationMs ?? 0), 0)
  const totalTokens = traces.reduce((sum, t) => sum + (t.tokens?.total ?? 0), 0)
  console.log(experimentId, traces.length, totalMs, totalTokens)
}

import { getCurrentTrace } from "@bitfab/sdk"

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

const traced = orderProcessing.withSpan({ 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 firstModelCall = await client.getTraceSpan(traceId, {
  type: "llm",
  occurrence: "first",
})
const exact = await client.getTraceSpan(traceId, { id: spanId })

const page = await client.spans.list(traceId, { fields: ["input"] })
for (const span of page.spans) {
  console.log(span.name, span.type, span.input)
}
if (page.hasMore) {
  const next = await client.spans.list(traceId, {
    fields: ["input"],
    cursor: page.nextCursor,
  })
}

const span = await client.getSpan(spanId)

const riskyService = bitfab.getFunction("risky-service")

const risky = riskyService.withSpan(() => {
  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.experimentId)   // Experiment identifier
console.log(result.experimentUrl)  // 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/replayRegistry.ts
import { defineReplayRegistry } from "@bitfab/sdk"
import { graph } from "../src/agent"
import { bitfab } from "../src/bitfabClient"

const myAgent = bitfab.getFunction("my-agent")

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

export default defineReplayRegistry({
  agent: { client: bitfab, fn: replayMyAgent, traceFunctionKey: "my-agent" },
})

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/replayRegistry.ts
import { defineReplayRegistry } from "@bitfab/sdk"
import { bitfab, updatedFn } from "../src/workflow"
import { adaptInputs } from "./replay-adapters/extraction"

export default defineReplayRegistry({
  workflow: { client: bitfab, fn: updatedFn, options: { 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, {
  resume: "3f0c9c1e-5d2a-4b7e-9a61-2c8f0e4d7b13",
})

for (const item of result.items) {
  if (item.carriedOver) continue // finished in the earlier run
  console.log(item.result)
}

await bitfab.replay("my-function", updatedFn, {
  onInterrupt: ({ experimentId, signal }) => {
    console.error(`Experiment ${experimentId} interrupted by ${signal}`)
    process.exit(signal === "SIGINT" ? 130 : 143)
  },
})

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

// Human-readable summary goes to stderr, so stdout stays pure JSON.
console.error(`Experiment: ${result.experimentUrl}`)
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 withTrace- or
    // withSpan-wrapped function carries its key, so `traceFunctionKey` can be omitted.
    traceFunctionKey: "my-search-pipeline",
    options: { mock: "marked" },
    optionsFactory: ({ params }) => ({
      mockOverride: createSearchMock(params.scenario),
    }),
  },
})

// packages/agent/src/supportAgent.ts
const supportAgent = bitfab.getFunction("support-agent")

export function createSupportAgent(config: AgentConfig) {
  const ticketGateway = new TicketGatewayClient(config.ticketGatewayUrl)

  const lookupTicket = supportAgent.withSpan(
    { name: "lookup-ticket", type: "tool", mockOnReplay: true },
    async (ticketId: string) => ticketGateway.lookup(ticketId),
  )

  const answerQuestion = supportAgent.withSpan(
    { name: "answer-question", type: "agent" },
    async (question: string) => {
      const ticket = await lookupTicket(parseTicketId(question))
      return { reply: `Ticket ${ticket.id} is ${ticket.status}.` }
    },
  )

  return { answerQuestion }
}

// packages/agent/scripts/replayRegistry.ts
import "dotenv/config"
import { defineReplayRegistry } from "@bitfab/sdk"
import { bitfab } from "../src/bitfab"
import { createSupportAgent, loadAgentConfig } from "../src/supportAgent"

const { answerQuestion } = createSupportAgent(loadAgentConfig())

export default defineReplayRegistry({
  supportAgent: { client: bitfab, fn: answerQuestion, options: { mock: "marked" } },
})

cd packages/agent
pnpm exec bitfab-replay --registry scripts/replayRegistry.ts supportAgent --dry-run
pnpm exec bitfab-replay --registry scripts/replayRegistry.ts supportAgent --limit 1

// packages/app/scripts/replayRegistry.ts
import { bitfab, type RunOptions } from "@acme/agent-core"
import { defineReplayRegistry } from "@bitfab/sdk"
import { buildAgentTools, createAgentRunner } from "../src/runAgent"

const runner = createAgentRunner()

export default defineReplayRegistry({
  agentRun: {
    client: bitfab,
    fn: runner.run.bind(runner),
    options: {
      mock: "marked",
      adaptInputs: ([prompt, recordedOptions]) => [
        prompt,
        { ...(recordedOptions as RunOptions), tools: buildAgentTools() },
      ],
    },
  },
})

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",
})
await bitfab.datasets.update(dataset.id, { name: "Declined refunds", description: "" })

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.verdicts.saveAll(
  assertions
    .filter((assertion) => assertion.approvalState === "approved")
    .map((assertion) => {
      const assessment = {
        assertion: assertion.assertion,
        passCriteria: assertion.passCriteria,
        failCriteria: assertion.failCriteria,
        targetOnEvaluatedTrace: assertion.targetOnEvaluatedTrace,
      }
      return {
        originalTraceId: item.originalTraceId,
        attempt: item.attempt,
        assertionId: assertion.id,
        verdict: judge(assessment, output) ? "pass" : "fail",
        annotation: explain(assessment, output),
      } as const
    }),
  experimentId,
)

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

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