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
)

Arguments

project_info

A Finn project from set_project_info()

llm

An ellmer Chat or chat_copilot() object used as the template for isolated agent sessions.

input_data

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. Values left blank are treated as missing and form the "NA" label in series names, like other missing combo values. Resuming a version uses previously uploaded inputs, not replacement values from this data frame. Create a new version to use revised data.

forecast_horizon

The number of periods to forecast

external_regressors

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.

hist_end_date

Optional Date object indicating the end of the historical data

hist_start_date

Optional Date object indicating the start of the historical data

back_test_scenarios

Optional character vector of back test scenarios

back_test_spacing

Optional numeric value for back test spacing

combo_cleanup_date

Optional Date object for combo cleanup

allow_hierarchical_forecast

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.

negative_forecast

If TRUE, allow forecasts to dip below zero.

run_global_models

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.

run_local_models

If TRUE, run models by individual time series as local models. Default is TRUE.

overwrite

Logical indicating whether to overwrite existing agent run info

custom_models

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.

Value

A list containing the agent run information

Details

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.

Examples

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
)
} # }