> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Helpers

> Utility helpers exposed by the Loops SDK alongside the core clients.

The Loops SDK ships helper functions alongside the core clients, grouped by what they operate on. `baseten.loops.helpers` itself exports nothing; import each helper from its submodule, except `loops_log_kl_sample_train`, which is exported from the top-level package:

```python theme={"system"}
from baseten.loops import loops_log_kl_sample_train
from baseten.loops.helpers.datum import attach_reference_logprobs
```

<ParamField body="attach_reference_logprobs(data, reference)" type="list[Datum]">
  Return a copy of `data` with each [`Datum`](/reference/sdk/loops/types) carrying a new `ref_logprobs` field in `loss_fn_inputs`, scored by `reference`.

  * **`data`** (`list[Datum]`): the preference batch, with each datum holding the full prompt + response sequence in `model_input`. For DPO batches, these are interleaved chosen/rejected pairs.
  * **`reference`** ([`SamplingClient`](/reference/sdk/loops/sampling-client)): a version-pinned snapshot of the reference policy, typically returned by [`TrainingClient.save_weights_and_get_sampling_client`](/reference/sdk/loops/training-client) before any optimizer steps.

  Each datum's sequence is scored once via a single `compute_logprobs` call. Scoring is sequential.
</ParamField>

<ParamField body="loops_log_kl_sample_train(wandb_run, step, data, forward_backward_output=None, *, training_logprobs=None, prefix=&#x22;optim/train-sample-div/&#x22;, log_histogram=True, max_histogram_tokens=50000, log_worst_tokens=True, top_n=20, tokenizer=None)" type="dict[str, Any]">
  Compute sampler-vs-trainer logprob divergence diagnostics for an RL step and log them to Weights & Biases. Over the action tokens (`mask > 0`), it compares the sampler logprobs saved on each [`Datum`](/reference/sdk/loops/types) against the trainer logprobs from `forward_backward`, and logs KL estimators (`kl_sample_train_v1_loops`, `kl_sample_train_v2_loops`, `kl_sample_train_k3`), importance-ratio and effective-sample-size stats, a per-token-diff histogram, and a worst-divergent-tokens table under `optim/train-sample-div/`.

  * **`wandb_run`**: a W\&B run (anything with `.log(metrics, step=...)`), or `None` to skip logging; the metrics dict is returned either way.
  * **`data`** (`list[Datum]`): the batch passed to `forward_backward`, with sampler logprobs attached.
  * Pass either **`forward_backward_output`** (a [`ForwardBackwardOutput`](/reference/sdk/loops/types)) or **`training_logprobs`**; passing neither raises `ValueError`.

  For the scalar metrics without W\&B objects, call `loops_compute_kl_sample_train(data, training_logprobs)` from `baseten.loops.rl_metrics`.
</ParamField>