Set up Finn Agent Run Information — set_agent

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
)

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. 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 external regressors
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

Value

A list containing the agent run information

Details

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