Write scorers and classifiers as custom code with full control over scoring logic, business rules, and pattern matching to evaluate AI outputs.
Custom code scorers and classifiers let you write evaluation logic with full control over the result. A scorer returns a numeric score, while a classifier returns a categorical label. They can use any packages you need and are best when you have specific rules, patterns, or calculations to implement.You can define custom code scorers in three places:
Inline in SDK code: Define scorers directly in your evaluation scripts for local development or application-specific logic.
Pushed via CLI: Define scorers in TypeScript or Python files and push them to Braintrust for team-wide sharing and automatic evaluation of production logs.
Created in UI: Build scorers in the Braintrust web interface using the built-in code editor.
Most teams prototype in the UI, then push production-ready scorers via the CLI. See Scorers overview for guidance.
Span-level scorers evaluate individual operations or outputs. Use them for measuring single LLM responses, checking specific tool calls, or validating individual outputs. Each matching span receives an independent score.Your scorer function receives these parameters:
input: The input to your task
output: The output from your task
expected: The expected output (optional)
metadata: Custom metadata from the test case
Return a number between 0 and 1, or an object with score and optional metadata.In Ruby, declare only the parameters you need as keyword arguments. The runner automatically filters out the rest: |output:, expected:|.
Scorers must be pushed from within their directory (e.g., bt functions push scorer.py); pushing with relative paths (e.g., bt functions push path/to/scorer.py) is unsupported and will cause import errors.
Scorers using local imports must be defined at the project root.
The maximum supported Python version for scorers created with the Braintrust CLI is 3.13.
Braintrust uses uv to cross-bundle dependencies to Linux. This works for binary dependencies except libraries requiring on-demand compilation.
TypeScript bundling
In TypeScript, Braintrust uses esbuild to bundle your code and dependencies. This works for most dependencies but does not support native (compiled) libraries like SQLite.If you have trouble bundling dependencies, file an issue in the braintrust-sdk repo.
Python external dependencies
Python scorers created via the CLI have these default packages:
autoevals
braintrust
openai
pydantic
requests
For additional packages, use the --requirements flag.For scorers with external dependencies:
scorer-with-deps.py
import braintrustfrom langdetect import detectfrom pydantic import BaseModelproject = braintrust.projects.create(name="my-project")class LanguageMatchParams(BaseModel): output: str expected: str@project.scorers.create( name="Language match", slug="language-match", description="Check if output and expected are same language", parameters=LanguageMatchParams, metadata={"__pass_threshold": 0.5},)def language_match_scorer(output: str, expected: str): return 1.0 if detect(output) == detect(expected) else 0.0
Trace-level scorers evaluate entire execution traces including all spans and conversation history. Use these for assessing multi-turn conversation quality, overall workflow completion, or when your scorer needs access to the full execution context. The scorer runs once per trace.Your handler function receives the trace parameter, which provides methods for accessing execution data:
Get spans: Returns spans matching the filter. Each span includes input, output, metadata, span_id, and span_attributes. Omit the filter to get all spans, or pass multiple types like ["llm", "tool"].
TypeScript: trace.getSpans({ spanType: ["llm"] })
Python: trace.get_spans(span_type=["llm"])
Java: trace.getSpans("llm")
Ruby: trace.spans(span_type: "llm")
C#: trace.GetSpansAsync("llm")
Get thread: Returns an array of conversation messages extracted from LLM spans.
TypeScript: trace.getThread()
Python: trace.get_thread()
Java: trace.getLLMConversationThread()
Ruby: trace.thread
C#: trace.GetThreadAsync()
input, output, expected, and metadata are automatically populated from the root span and passed to your scorer function.
Define minimum acceptable scores to automatically mark results as passing or failing. When configured, scores that meet or exceed the threshold are marked as passing (green highlighting with checkmark), while scores below are marked as failing (red highlighting).
Pass thresholds apply only to scorers that output numeric scores. Classifiers, which output labels, don’t use them.
SDK
UI
Add __pass_threshold to the scorer’s metadata (value between 0 and 1):
A single scorer can return an array of score objects to emit multiple named metrics from one call. This is useful when several quality dimensions can be computed together or share computation. Each item appears as its own score column in the Braintrust UI.Each item requires name and score. metadata is optional.
A classifier returns a categorical label instead of a numeric score. Define custom code classifiers inline in your eval code, as a function that evaluates a result and constructs one or more classifications.Each classification your function returns sets a name (the group it belongs to, such as intent), an id (the value you filter by, such as password_reset), an optional label for display (such as Password reset), and optional metadata. Unlike an LLM-as-a-judge classifier, custom code sets these fields independently and can return more than one classification at a time.
import { Eval } from "braintrust";const DATASET = [ { input: "Hello! Can you help me reset my password?", expected: "password_reset", },];async function task(input: string): Promise<string> { // Stand-in for your LLM call return `Thanks for reaching out. ${input}`;}function intentClassifier({ output }: { output: string }) { if (output.toLowerCase().includes("password")) { return { name: "intent", id: "password_reset", label: "Password reset", }; } return { name: "intent", id: "other", label: "Other", };}Eval("Support intent", { data: DATASET, task, classifiers: [intentClassifier],});
For the C# and Java examples, use the BRAINTRUST_DEFAULT_PROJECT_NAME environment variable to set a project name. Otherwise, the default project is default-dotnet-project (C#) or default-java-project (Java).
In a single evaluation, you can use scorers, classifiers, or both. Classifier failures do not stop the evaluation or affect other scorers and classifiers. Braintrust records classifier errors in the result metadata under classifier_errors.A classifier can also assign multiple labels at once: