% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rem.R
\name{run_llm_rem}
\alias{run_llm_rem}
\title{Generate an LLM event sequence and fit a REM}
\usage{
run_llm_rem(
  edgelist,
  formula,
  query_fn,
  n_events = NULL,
  n = NULL,
  n_nonevents = 200L,
  base_riskset = NULL,
  cl = NULL,
  seed = 8214L,
  checkpoint_path = NULL,
  use_empirical_history = FALSE,
  rate_limit_secs = 0.3,
  fit = TRUE,
  method = c("cox", "clogit", "temporal"),
  covariates = NULL
)
}
\arguments{
\item{edgelist}{Prepared edgelist (output of \code{\link[=prepare_edgelist]{prepare_edgelist()}}).}

\item{formula}{Survival formula passed to \code{\link[=fit_rem]{fit_rem()}}.}

\item{query_fn}{A closure produced by \code{\link[=make_query_roleplay_sender]{make_query_roleplay_sender()}},
\code{\link[=make_query_predict]{make_query_predict()}}, or \code{\link[=make_query_roleplay_random]{make_query_roleplay_random()}}, or any function
with the signature:
\code{f(past_events, empirical_event, all_nodes) -> c(sender, receiver)}.}

\item{n_events}{Number of events to generate. \code{NULL} uses the full edgelist.}

\item{n}{Number of nodes. Inferred if \code{NULL}.}

\item{n_nonevents}{Sampled risk-set size passed to \code{\link[=fit_rem]{fit_rem()}}.}

\item{base_riskset}{Precomputed base risk set.}

\item{cl}{Optional PSOCK cluster for parallelised risk-set computation.}

\item{seed}{RNG seed for random fallbacks and random-node sampling.}

\item{checkpoint_path}{File path for incremental saves every 10 events.
\code{NULL} disables checkpointing.}

\item{use_empirical_history}{If \code{FALSE} (default), the LLM is shown its own
previously generated events as history, so any divergence from reality
compounds over time. If \code{TRUE}, the LLM is shown the empirical event
history at each step, isolating the effect of the generation strategy from
the effect of accumulated sequence drift.}

\item{rate_limit_secs}{Seconds to pause between LLM calls.}

\item{fit}{If \code{TRUE} (default), fits a REM on the generated sequence before
returning. Set to \code{FALSE} to skip model fitting and return only the
sequence and raw responses — useful when running many sequences and
deferring all model fitting to a separate step.}

\item{method}{Passed to \code{\link[=fit_rem]{fit_rem()}}: \code{"cox"} (default), \code{"clogit"}, or
\code{"temporal"}.}

\item{covariates}{Optional exogenous covariate list passed to \code{\link[=fit_rem]{fit_rem()}}.}
}
\value{
A named list with elements:
\itemize{
\item \code{sequence}: generated event sequence as a data frame.
\item \code{responses}: raw LLM response text and parsed sender/receiver per event.
\item \code{rem}: fitted model (only present when \code{fit = TRUE}).
}
}
\description{
At each time step \emph{t} (starting from 2), \code{query_fn} is called with the
growing LLM-generated history, the empirical event at \emph{t}, and the full
node set. The returned sender/receiver pair is appended to the sequence.
The sequence is seeded with the first empirical event so the LLM starts
with at least one data point. After generation, risk-set statistics are
built and a REM is fitted.
}
\examples{
\dontrun{
data(edgelist)
el  <- prepare_edgelist(edgelist)
cfg <- rem_cfg(
  provider    = llm_provider_openai(),
  context     = "These are militarized conflict events between countries.",
  action_verb = "attacked",
  actor_noun  = "Country"
)
res <- run_llm_rem(
  el[1:50, ],
  survival::Surv(time1, occurred) ~ Repetition + RecRecencyLog +
    survival::strata(time2),
  query_fn    = make_query_roleplay_sender(cfg),
  n_nonevents = 50L, method = "clogit"
)
print(res$rem)
}
}
