> ## 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.

# How prompt version IDs work in Braintrust SDKs

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = "Understanding prompt version ID formats and converting between internal transaction IDs and UI-friendly hex strings"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

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

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { prettifyXact } from "braintrust/util";

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

#### Prettified to raw

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
prompt = load_prompt("My Project", "summarizer", version="1000197079360977868")
prompt = load_prompt("My Project", "summarizer", version="38762d010770566c")
```

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://github.com/braintrustdata/braintrust-sdk-python/blob/main/py/src/braintrust/xact_ids.py): `sdk-python/py/src/braintrust/xact_ids.py`
* [TypeScript](https://github.com/braintrustdata/braintrust-sdk-javascript/blob/main/js/util/xact-ids.ts): `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.