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).
Arguments
- m
An
llmhandle fromllm().- prompts
A character vector of one or more non-empty prompts;
NAand empty strings ("") are rejected.names(prompts)are retained on thepromptsattribute.- layers
NULL(default: every block) or a vector of 1-based block indices to capture (each in1: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; TransformerLenshook_attn_out), and/or the MLP sub-layer output. Tracing is supported on thellama,qwen2,gemma3,qwen3,qwen35, andgemma4architectures; any other raisesrelm_error_trace."residual"is available on all of them."mlp_out"is available on all exceptgemma4(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 raisesrelm_error_tracelisting the available components rather than silently substituting a different tensor.- spill
Single logical (default
TRUE). When a capture exceeds the memory budget,TRUEstreams it to a disk file (a lazily-loaded spilled trace) andFALSEraisesrelm_error_oominstead. 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(forprint/as.matrix) or itssummary.- ...
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.