This function sets up the necessary information for a Finn Agent run, including input data, forecast horizon, and other parameters. It checks for existing runs and allows for overwriting if specified.
set_agent_info(
project_info,
llm,
input_data,
forecast_horizon,
external_regressors = NULL,
hist_end_date = NULL,
hist_start_date = NULL,
back_test_scenarios = NULL,
back_test_spacing = NULL,
combo_cleanup_date = NULL,
allow_hierarchical_forecast = FALSE,
negative_forecast = FALSE,
run_global_models = NULL,
run_local_models = TRUE,
overwrite = FALSE,
custom_models = NULL
)A Finn project from set_project_info()
An ellmer Chat or chat_copilot() object used as the template
for isolated agent sessions.
A data frame or tibble containing the input data. Leading and trailing whitespace in character combo-variable values is removed before Finn creates internal series identifiers and writes input artifacts. Resuming a version uses previously uploaded inputs, not replacement values from this data frame. Create a new version to use revised data.
The number of periods to forecast
Optional character vector of candidate external regressors for built-in models. Custom models always use their declared drivers from eligible original input columns, independently of this list or the Agent's per-iteration choices.
Optional Date object indicating the end of the historical data
Optional Date object indicating the start of the historical data
Optional character vector of back test scenarios
Optional numeric value for back test spacing
Optional Date object for combo cleanup
Logical controlling the Agent optimization
scope. TRUE expands input data to all detected hierarchy levels before
optimization, runs inner iterations with forecast_approach = "bottoms_up",
and reconciles the final forecast. FALSE keeps the original bottom-level
series; global iterations may still compare the exact hierarchy detected by
EDA after reconciling that candidate back to the bottom level.
If TRUE, allow forecasts to dip below zero.
If TRUE, run multivariate models on the entire data set (across all time series) as a global model. Default of NULL runs global models for all date types except week and day.
If TRUE, run models by individual time series as local models. Default is TRUE.
Logical indicating whether to overwrite existing agent run info
Named approved custom-model envelopes from create_custom_model().
All supplied models are enrolled automatically alongside built-in candidates.
The returned object retains names only; approved objects are saved once in
an Agent-version bundle in prep_models.
A list containing the agent run information
Custom Agent runs add the raw C1 recipe and require CSV data, RDS objects,
supported local/mounted, Blob or M365 storage and no hierarchy. negative_forecast = FALSE floors
finished custom forecasts at zero, as for built-in models. The exact
approved pool is pinned before the parent run log. Existing-run setup requires
equivalent explicit enrollment; changed or omitted approval requires a new
run. Source is trusted R, not sandboxed. For compatible new-data updates,
create a new parent with overwrite = TRUE, the same explicit enrollment,
cadence, regressors and modes, then call update_forecast() with
explicit allow_iterate_forecast = FALSE. The positive whole-number forecast
horizon may change, subject to the approved rule's history and driver
requirements. Changed enrollment needs iteration.
New series are routed to defaults within the existing new-series limit.
The setup API has no
models_to_run argument: Finn includes every compatible enrolled custom
model from the first iteration onward, outside LLM control. Built-in
candidate choices and supported preprocessing remain independent of raw C1.
Custom driver values must be supplied through the forecast horizon; Finn
does not forecast missing future custom drivers. The same driver declarations
apply during saved-winner updates and default recovery. Changed source data
requires a new Agent version (overwrite = TRUE), not an in-place restart.
Global-only custom
runs need at least two series. Each selected custom model must support an
enabled mode and the project's cadence, horizon and required predictors.
The return keeps only custom-model names, not untrained models or approval
payloads. The Agent-version CSV always contains one custom_models names
field (NA without enrollment); the complete immutable bundle lives in
prep_models, under the existing project/run/version identity.
Saved approval is trusted-caller evidence, not
authenticated identity; forecasting never calls the authoring LLM again.
With overwrite = FALSE, an existing version retains its saved
forecast approach even if hierarchy detection changes after a package upgrade.
Logged user settings must still match. New versions use current detection;
one retained series or one combo column uses bottoms-up. Updating a new
version across an outer forecast-approach change requires fresh iteration.
if (FALSE) { # \dontrun{
# load example data
hist_data <- timetk::m4_monthly %>%
dplyr::filter(date >= "2013-01-01") %>%
dplyr::rename(Date = date) %>%
dplyr::mutate(id = as.character(id))
# set up Finn project
project <- set_project_info(
project_name = "Demo_Project",
combo_variables = c("id"),
target_variable = "value",
date_type = "month"
)
# set up LLM
llm <- ellmer::chat_azure_openai(model = "gpt-4o-mini")
# set up agent info
agent_info <- set_agent_info(
project_info = project,
llm = llm,
input_data = hist_data,
forecast_horizon = 6
)
} # }