relm runs local models in stock R. Use ordinary R data structures, read the installed help, and keep observations separate from scientific conclusions. Start at llms.txt. The API surface is derived from source; it lists every export and registered S3 method. The compatibility policy defines what is stable.
Inspect the environment first
packageVersion("relm")
find.package("relm")
getNamespaceExports("relm")
args(relm::llm_generate)
help("llm_trace", package = "relm")Restart R after an upgrade. Main, a tagged release, r-universe binaries and a CRAN submission can contain different bytes despite similar version labels. Record the installed version, source commit when available, model SHA-256, engine revision, backend, R/platform, seed and actual input/settings alongside results.
Do not install packages, fetch models, start a service or write persistent output merely because an example mentions it. Obtain the user’s authorization for the needed side effect. No API key or model server is required for local inference. Supply a verified local model; never invent a model digest or engine revision.
One independent example for every export
Each script
defines run_example() without executing it on source. Each
script has all its own setup; no prior example or workspace objects are
needed. Use a fresh environment to avoid name collisions:
example <- new.env()
source(system.file("examples", "agents", "llm_direction.R", package = "relm"),
local = example)
direction <- example$run_example() # synthetic, model-free API demonstrationThese files arrive with the WP16 documentation build. With an older installation, source the corresponding repository file explicitly instead. Check the function signatures; do not assume installing an older release includes these scripts.
| Export | Example input / result |
|---|---|
llm |
Verified local GGUF → inspect and close a CPU handle |
llm_tokens |
Local model → encode/decode a short UTF-8 string |
llm_generate |
Local model → at most eight generated tokens and recorded seed |
llm_logits |
Local model → five next-token rows; truncated probabilities |
llm_embed |
Local model → two rows of embeddings |
llm_trace |
Local model → last-position layer-2 residual matrix |
llm_steer |
Local model → a new additive residual handle, then close |
llm_ablate |
Local model → a new residual ablation handle, then close |
llm_apply_direction |
Verified model/build → four fresh captures, recorded direction, zero-coefficient application |
llm_cancel |
Local model + later/promises → observe one live state and cancel cooperatively |
llm_download |
Explicit permission/cache directory → pinned download or verified cache reuse |
activations |
Formula marker and its documented outside-formula refusal |
llm_probe |
Synthetic grouped data + glmnet → development selection and separate held-out evaluation |
llm_direction |
Synthetic paired matrices → recorded unit direction |
llm_compare |
Synthetic aligned states → coordinate differences |
llm_timeline |
Synthetic state records → bounded applied-steering audit |
Native examples accept model_path and an independently
known expected_sha256. Use a supported text model with at
least two layers (the pinned Qwen2.5 0.5B is the documented small-model
route). llm_apply_direction also requires the actual
engine_revision from the build record. None of these
scripts downloads a model. Only the downloader’s explicit
allow_download = TRUE enables that side effect. Its
registry alias verifies a pinned checksum; a bare URL alone is not
verified against a trusted expected checksum.
For another model, use the model-choice guide. Change the supplied path and independent digest, then check the capabilities needed by the example. Spark can generate text but cannot supply the traces used by the direction example; a matching vector length is not permission to reuse another model’s direction.
example <- new.env()
source(system.file("examples", "agents", "llm_generate.R", package = "relm"),
local = example)
# Set these from your own verified model record, not from an agent's guess:
answer <- example$run_example(model_path, expected_sha256)CI executes the five model-free examples and eleven public usage/refusal checks, parses every script and checks inventory coverage. It does not download a large model or represent missing model execution as success. A separately recorded local run checks the ten native paths with fresh bounded inputs. This distinction also applies to optional, guarded model chunks in the six vignettes.
Choose the observation and manage ownership
-
llm_trace()observes a prompt forward pass;on_stateobserves generation. Derived/intervened handles refuse ordinary trace/embed; use live observation where supported. Do not relabel an original-model trace as an edited one. - Start with one layer,
positions = "last", one component and a bounded token count.spill = FALSErefuses a capture over budget. A spilled trace is a zero-row proxy: useas.matrix(trace, layer = ...), notnrow()as its data size. - Keep handles in their owning process and close them with
function-scoped
on.exit(close(m)). Derived handles share weights, not cross-process ownership. Only one native operation is active per process; async requires an event loop. - Async returns a promise. Retain it and handle rejection as well as
fulfillment; pump
laterin a script. Cancellation is cooperative, not a hard stop or a partial-success result. Callbacks run on R’s thread; preserve callback errors. -
llm_compare()needs the complete preceding sampled history. Divergent prefixes withhold numerical differences. Top-k tables cannot establish a full distribution KL. Returning a coefficient to zero does not erase earlier KV. - Direction construction, coefficient selection and final evaluation need disjoint declared data. Synthetic examples and consumed holdouts establish no new efficacy claim. Probe association is not causal use; JSON shape is not truth.
Handle errors and preserve results
result <- tryCatch(relm::llm("missing-model.gguf"),
relm_error_model_load = function(e) list(class = class(e), message = conditionMessage(e)))Use the installed help’s specific condition class and structured fields. Report unsupported capabilities, timeouts and failed checks. Do not retry a refused model blindly, swallow warnings, weaken filters/tolerances or turn a skip into a pass. Preserve raw output before correcting a collector. Treat RDS and native model/projector inputs as trusted-input boundaries; checksums do not make hostile RDS safe. Persistent exports belong to an explicit caller-chosen directory.
For full workflows see research guidance, the complete walkthrough, supported scope and installation.