Skip to main content
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

prettify_xact accepts either an int or a str.

​
Prettified to raw

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

​
Prettified to raw

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:
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:

​
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:
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.