bt preprocessors - Braintrust

bt preprocessors manages preprocessors defined in local TypeScript or JavaScript files. A preprocessor turns a trace into the messages that prompt-based scorers receive for trace template variables such as {{preprocessed}}. Use the CLI to scaffold a starter file, run it against a real trace, and publish it to a project without using the preprocessor editor.

bt v0.26.0 or later is required. bt preprocessors push and bt preprocessors preview require Node.js. The braintrust/preprocessors helper is embedded in the CLI, so install the Braintrust TypeScript SDK v3.36.0 or later only if you want editor types and typechecking.

Subcommands

Subcommand	Description
`bt preprocessors push <PATH>`	Push local preprocessor definitions to Braintrust
`bt preprocessors bootstrap <NAME>`	Create a starter preprocessor file
`bt preprocessors preview <PATH>`	Run a local preprocessor on a trace and print the result
`bt preprocessors list`	List preprocessors in the current project. Running `bt preprocessors` with no subcommand does the same.
`bt preprocessors view [slug]`	View a preprocessor’s details
`bt preprocessors invoke [slug]`	Invoke a published preprocessor
`bt preprocessors delete [slug]`	Delete a preprocessor

list, view, invoke, and delete are aliases for bt functions scoped to preprocessors and accept the same flags.

Write a preprocessor

Export each definition with customPreprocessor() from braintrust/preprocessors. Named and default exports are supported, and a file can export more than one definition.

conversation.preprocessor.ts

import { customPreprocessor } from "braintrust/preprocessors";

export const conversation = customPreprocessor(
  { name: "Conversation", slug: "conversation" },
  (span) => {
    if (span.span_attributes?.type === "score") return null;
    return typeof span.output === "string" ? span.output : null;
  },
);

The handler runs once per span and receives the span’s id, root_span_id, input, output, error, metadata, and span_attributes. It must synchronously return a JSON-serializable value, or null to skip the span. Published handlers run in QuickJS. bt preprocessors push bundles local imports into inline code. Node.js APIs, network access, and unbundled imports are unavailable.

bt preprocessors push

Push one or more preprocessor definitions to Braintrust. bt scans the path for files matching *.preprocessor.ts, *.preprocessor.js, *-preprocessor.ts, or *-preprocessor.js, and pushes every definition each file exports.

bt preprocessors push ./braintrust-preprocessors --project my-project
bt preprocessors push ./braintrust-preprocessors/conversation.preprocessor.ts --if-exists replace

If a preprocessor with the same slug already exists, the command fails by default. Add --if-exists replace to update it. Flags

Flag	Env var	Default	Description
`<PATH>`	—	`.`	File or directory path(s) to scan for preprocessor definitions
`--file <PATH>`	`BRAINTRUST_PREPROCESSORS_PUSH_FILES`	—	Comma-separated file or directory paths (alternative to the positional argument)
`--if-exists <MODE>`	`BRAINTRUST_PREPROCESSORS_PUSH_IF_EXISTS`	`error`	Conflict behavior when a preprocessor with the same slug already exists: `error`, `replace`, or `ignore`
`--yes`, `-y`	`BRAINTRUST_PREPROCESSORS_PUSH_YES`	`false`	Skip the confirmation prompt

Each definition can set project to a project name, or to an object with the project’s id or name. Definitions without one use --project or your configured project.

bt preprocessors bootstrap

Create a starter preprocessor file in the braintrust-preprocessors/ directory (created if it does not exist). The starter returns each LLM span’s output as an assistant message.

bt preprocessors bootstrap 'Conversation'
bt preprocessors bootstrap 'Conversation' --file ./my-preprocessors/conversation.preprocessor.ts

Flags

Flag	Env var	Default	Description
`<NAME>`	—	—	Preprocessor name (required unless `--name` is used)
`--name <NAME>`	`BRAINTRUST_PREPROCESSORS_BOOTSTRAP_NAME`	—	Preprocessor name (alternative to the positional argument)
`--file <PATH>`	`BRAINTRUST_PREPROCESSORS_BOOTSTRAP_FILE`	`braintrust-preprocessors/<slug>.preprocessor.ts`	Output file or directory path. A file path must match the push file pattern
`--force`, `-f`	`BRAINTRUST_PREPROCESSORS_BOOTSTRAP_FORCE`	`false`	Overwrite an existing file

bt preprocessors preview

Run a local preprocessor on a trace in Braintrust’s QuickJS runtime and print the output. Preview doesn’t publish the preprocessor. Open a trace in Braintrust’s logs or an experiment and copy the URL from your browser’s address bar. Pass it to --url in quotes to preserve its query parameters:

bt preprocessors preview ./braintrust-preprocessors/conversation.preprocessor.ts --url "<BRAINTRUST_TRACE_URL>"

You can also select a project logs trace by root span ID. If the URL doesn’t include a project, or you use --trace-id, also pass --project or --project-id:

bt preprocessors preview ./conversation.preprocessor.ts --trace-id <ROOT_SPAN_ID> --project my-project

If the file exports more than one definition, select one with --export <NAME>, or --export default for the default export. Flags

Flag	Env var	Default	Description
`<PATH>`	—	—	Preprocessor file to preview (required unless `--file` is used)
`--file <PATH>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_FILE`	—	Preprocessor file (alternative to the positional argument)
`--export <NAME>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_EXPORT`	—	Export to preview when the file contains multiple preprocessors
`--url <URL>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_URL`	—	Braintrust app URL of the trace to preprocess
`--project-id <ID>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_PROJECT_ID`	—	Project ID of the trace to preprocess
`--trace-id <ID>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_TRACE_ID`	—	Root span ID of the trace (alias: `--root-span-id`)
`--lookup-window <DURATION>`	`BRAINTRUST_PREPROCESSORS_PREVIEW_LOOKUP_WINDOW`	`30d`	Lookback window when resolving a URL’s span ID (for example, `7d`, `90d`)

Use a preprocessor in a scorer

Pass --preprocessor to bt scorers create to build a prompt-based scorer’s trace template variables with a pushed preprocessor:

bt scorers create "Helpfulness" --model gpt-5.4-nano --messages @messages.json \
  --choice-scores '{"A":1,"B":0}' --preprocessor conversation

Example workflow

With bt v0.26.0 or later and Node.js installed, bootstrap, preview, and push a preprocessor. Copy a trace URL from your browser’s address bar for the preview step:

# 1. Create a starter file in braintrust-preprocessors/
bt preprocessors bootstrap 'Conversation'

# 2. Run it against a real trace
bt preprocessors preview ./braintrust-preprocessors/conversation.preprocessor.ts \
  --url "<BRAINTRUST_TRACE_URL>"

# 3. Push to Braintrust when you're satisfied
bt preprocessors push ./braintrust-preprocessors --project my-project

​Subcommands

​Write a preprocessor

​bt preprocessors push

​bt preprocessors bootstrap

​bt preprocessors preview

​Use a preprocessor in a scorer

​Example workflow

Subcommands

Write a preprocessor

bt preprocessors push

bt preprocessors bootstrap

bt preprocessors preview

Use a preprocessor in a scorer

Example workflow