Skip to main content

Documentation Index

Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Applies to:
  • Plan -
  • Deployment -

​
Summary

Goal: Understand how Braintrust represents prompt version IDs and convert between the raw transaction ID format returned by SDKs and the prettified hex format displayed in the UI. Features: Transaction ID prettification utilities in the Python and JavaScript SDKs for cross-referencing prompt versions between code and UI.

​
How version IDs work

Braintrust uses two formats for the same prompt version ID:
  • Raw format: A large decimal integer string, such as "1000197079360977868", returned by prompt.version in SDKs.
  • Prettified format: A 16-character lowercase hex string, such as "38762d010770566c", used in the Braintrust UI.
Both formats identify the same prompt version. The prettified format is a reversible presentation of Braintrust transaction IDs, designed to be shorter and easier to compare in the UI.

​
Convert between formats

​
Python SDK

​
Raw to prettified

from braintrust.xact_ids import prettify_xact

raw_version = prompt.version
pretty_version = prettify_xact(raw_version)
prettify_xact accepts either an int or a str.

​
Prettified to raw

from braintrust.xact_ids import load_pretty_xact

ui_version = "38762d010770566c"
raw_version = load_pretty_xact(ui_version)
load_pretty_xact returns a str. If the input is not exactly 16 characters, it returns the input unchanged.

​
TypeScript SDK

These functions are exported from braintrust/util.

​
Raw to prettified

import { prettifyXact } from "braintrust/util";

const rawVersion = prompt.version;
const prettyVersion = prettifyXact(rawVersion);

​
Prettified to raw

import { loadPrettyXact } from "braintrust/util";

const uiVersion = "38762d010770566c";
const rawVersion = loadPrettyXact(uiVersion);
Both functions take and return strings. The SDK’s TransactionId type is a string alias. loadPrettyXact returns its input unchanged if it is not exactly 16 characters.

​
Load a specific prompt version

Both formats can be used with load_prompt and loadPrompt: 
prompt = load_prompt("My Project", "summarizer", version="1000197079360977868")
prompt = load_prompt("My Project", "summarizer", version="38762d010770566c")

const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "summarizer",
  version: "38762d010770566c", // or "1000197079360977868"
});
The SDKs pass the version value through to the API. On the backend, Braintrust treats 16-character version strings as prettified transaction IDs and decodes them before lookup. This normalization is length-based. A non-hex 16-character string will fail during decoding.

​
Cross-reference with the UI

When logging or displaying a prompt version for a human to find in the Braintrust UI, log the prettified version: 
from braintrust.xact_ids import prettify_xact

prompt = load_prompt("My Project", "summarizer")
ui_version = prettify_xact(prompt.version)
print(f"Prompt version in UI: {ui_version}")

​
How the encoding works

The encoding uses modular multiplication over 64-bit integers:
  1. Interpret the raw transaction ID as an unsigned integer.
  2. Multiply it by a fixed coprime modulo 2^64:
    • COPRIME = 205891132094649
    • COPRIME_INVERSE = 1522336535492693385
    • MOD = 2^64
  3. Format the result as a zero-padded 16-character lowercase hexadecimal string.
To decode, Braintrust parses the 16-character hex string, multiplies by COPRIME_INVERSE modulo 2^64, and restores the fixed top bits used by Braintrust transaction IDs: 
TOP_BITS = 0x0DE1 << 48
This is reversible for Braintrust transaction IDs, which carry those fixed top bits. It should not be described as a general-purpose bijection for arbitrary 64-bit integers.

​
Reference implementations

  • Python: sdk-python/py/src/braintrust/xact_ids.py
  • TypeScript: sdk/js/util/xact-ids.ts

​
Notes

  • In JavaScript and TypeScript, prettifyXact and loadPrettyXact are exported from braintrust/util.
  • In Python, the helpers live in braintrust.xact_ids and are not re-exported from the top-level braintrust package.
  • load_prompt and loadPrompt can accept either the raw decimal version or the 16-character prettified version because the backend normalizes prettified values before lookup.