Skip to contents

Runs a forward pass over each prompt's tokens (no sampling) and captures the internal activations selected by the filters, returning a long-format relm_trace data.frame with one row per (prompt, token position, layer, component, neuron).

Usage

llm_trace(
  m,
  prompts,
  layers = NULL,
  positions = "last",
  components = "residual",
  spill = TRUE,
  spill_dir = NULL
)

# S3 method for class 'relm_trace'
print(x, ...)

# S3 method for class 'relm_trace'
summary(object, ...)

# S3 method for class 'summary.relm_trace'
print(x, ...)

Arguments

m

An llm handle from llm().

prompts

A character vector of one or more non-empty prompts; NA and empty strings ("") are rejected. names(prompts) are retained on the prompts attribute.

layers

NULL (default: every block) or a vector of 1-based block indices to capture (each in 1:m$layers).

positions

Which token positions to capture: "last" (default, the last token of each prompt), "all", or a vector of 1-based positions.

components

A subset of c("residual", "attn_out", "mlp_out") (default "residual"): the residual stream, the attention sub-layer output (after the output projection; TransformerLens hook_attn_out), and/or the MLP sub-layer output. Tracing is supported on the llama, qwen2, gemma3, qwen3, qwen35, and gemma4 architectures; any other raises relm_error_trace. "residual" is available on all of them. "mlp_out" is available on all except gemma4 (whose mixture-of-experts layers name their FFN output differently, so capturing it would silently miss layers). "attn_out" is currently observable only on llama-family models; on the others (which name only the pre-projection attention tensor, a different quantity) requesting it raises relm_error_trace listing the available components rather than silently substituting a different tensor.

spill

Single logical (default TRUE). When a capture exceeds the memory budget, TRUE streams it to a disk file (a lazily-loaded spilled trace) and FALSE raises relm_error_oom instead. A within-budget capture is always held in memory regardless of this flag.

spill_dir

NULL (default: a managed per-session directory under the user cache, cleaned up when the session ends) or a single directory path in which to write spill files (left in place for you to manage).

x

A relm_trace (for print/as.matrix) or its summary.

...

Ignored.

object

A relm_trace.

Value

A relm_trace: a data.frame (class c("relm_trace", "data.frame")) with the seven columns above, carrying model, spilled, spill_files, and prompts attributes. When spilled is TRUE the rows live in spill_files (read on demand by as.matrix.relm_trace()) rather than in the frame. See as.matrix.relm_trace() to extract one (layer, component) slice as a numeric matrix.

print returns its argument invisibly.

summary returns a data.frame (class summary.relm_trace) with one row per captured (layer, component) group: its n and mean |value|. For a spilled trace, mean_abs is NA (reporting it would force a data load); use as.matrix.relm_trace() to read a slice.

Details

llm_trace() is the anatomy lab's core tool: it observes the residual stream and the attention/MLP sub-layer outputs as the model processes text, so those activations can be analysed with ordinary R (PCA, per-layer probes, and so on). Prompt tracing runs on a dedicated transient context. Live generation uses a separate dormant dispatcher on the generation context; selected live taps activate only when llm_generate(on_state = ...) is requested.

The captured columns are exactly (in order): prompt_id (1-based index into prompts), token_pos (1-based position within that prompt), token (the token piece), layer (1-based transformer block), component ("residual", "attn_out", or "mlp_out"), neuron (1-based index within the component vector), and value (the activation).

Memory (the 16 GB rule). A full trace can be large, so the defaults capture little (positions = "last", components = "residual"); widen them deliberately. Before running, the size of the data.frame you would receive is estimated from the filters (the materialized-object cost, D-017). If it fits the budget (min(2 GB, 20% of RAM), overridable with options(relm.trace_budget = <bytes>)) it is held in memory. If it exceeds the budget and spill = TRUE (the default), the capture is streamed to an Arrow-IPC file under the session cache and the result is a spilled relm_trace that loads lazily: print()/summary() never read the file, and as.matrix.relm_trace() reads only the requested (layer, component) slice. If it exceeds the budget and spill = FALSE, the call raises relm_error_oom before any allocation, its estimate_bytes field stating the estimate. Spill files are removed when the R session ends.

The model must carry a tokenizer; a no_vocab model raises relm_error_tokenize. As with the other text entry points, the runnable example is guarded by the RELM_TEST_MODEL_QWEN environment variable.

Tracing an intervened handle (from llm_steer()/llm_ablate()) raises relm_error_trace: interventions currently apply to generation and logits only, and the trace context does not inherit them, so tracing would capture the base (un-intervened) forward pass while labeling it intervened. Trace the original handle.

Examples

if (FALSE) { # nzchar(Sys.getenv("RELM_TEST_MODEL_QWEN"))
m <- llm(Sys.getenv("RELM_TEST_MODEL_QWEN"))
tr <- llm_trace(m, c("The cat sat.", "Quarks bind."), layers = 1:4)
tr
summary(tr)
x <- as.matrix(tr, layer = 1, component = "residual")
dim(x)
close(m)
}