R/agent_iterate_forecast.R
iterate_forecast.RdThis function orchestrates the forecast iteration process for a Finn agent, including exploratory data analysis,
iterate_forecast(
agent_info,
max_iter = 3,
weighted_mape_goal = 0.03,
parallel_processing = NULL,
inner_parallel = FALSE,
num_cores = NULL,
seed = 123
)Agent info from set_agent_info()
Maximum number of iterations for forecast optimization. This is a total per search (the global search and each time series' local search) for the Agent version, not a number of extra iterations: calling again on the same Agent run with a higher value runs only the remaining iterations, and a lower value runs nothing new.
Weighted MAPE goal the agent is trying to achieve for each time series. Series that already meet it are not searched again, and a search can stop early once it is reached. On the same Agent run, a stricter goal reopens time series whose best model is global and that miss the new goal.
Default of NULL runs no parallel processing and
forecasts each individual time series one after another. 'local_machine'
leverages all cores on current machine Finn is running on. 'spark'
runs time series in parallel on a spark cluster in Azure Databricks or
Azure Synapse. Ellmer-backed workflows require ellmer 0.4.0 or later on
the main process and every worker. Copilot-backed workflows require
the CLI, processx, and authentication on each worker; see chat_copilot().
Run components of forecast process inside a specific time series in parallel. Can only be used if parallel_processing is set to NULL or 'spark'.
Number of cores to run when parallel processing is set up. Used when running parallel computations on local machine or within Azure. Default of NULL uses total amount of cores on machine minus one. Can't be greater than number of cores on machine minus 1.
Set seed for random number generator. Numeric value.
Future quality is evaluated when final_models() selects the winner
within each iteration, including usable least-issues fallbacks with warnings.
Parallel fallback warnings are relayed to the caller without saved fields.
Iteration ranking starts from the earliest minimum
WMAPE and may prefer a later eligible iteration within 10 percent relative
WMAPE when its average model WMAPE is strictly lower. Local mean, median, and
standard deviation summarize individual-model backtests, excluding simple
averages. This retains evidence that a setting improves other models even if
the current best model does not improve. Global summary fields retain their
original meaning: run WMAPE for mean and median, and zero standard deviation.
Agent comparisons and stopping use WMAPE rounded to four decimal places.
Search-context selection does not overwrite a better saved local forecast.
Global promotion applies to one complete iteration, and all saved global
winners must reference that same iteration. Individual models and averages
may differ within it. Mixed global iteration metadata is rejected before
publication or update; interrupted writes are not treated as successful.
Normal accuracy-goal stopping requires a complete eligible result and finite WMAPE, not another
soft-quality check. A winner with soft concerns may therefore beat an earlier
winner on accuracy. Loaded backtests, run history, and best-run metrics are reused without
re-evaluating past future paths. Rejected evaluations still consume iteration
budget without repeating the same fit as an infrastructure retry. If no
eligible result exists, the workflow fails or an enabled local phase handles
unresolved global series. Rankings are kept in memory, not new files.
Hierarchical accuracy uses reconciled backtests; later comparisons and
reconciliation do not require retained source-node quality rankings. Final
reconciliation publishes the selected mixture without future-quality scoring,
whole-set fallback, or extra refitting.
Custom pools enrolled by set_agent_info() constrain every proposal to
approved models and original-scale R1 settings, plus the raw C1 recipe. Missing proposal fields
do not acquire built-in defaults. Local/mounted CSV data, RDS objects and
sequential, local-machine or Spark execution are required; inner_parallel
applies to custom models as it does to built-in models. Global-only
pools require at least two series. Saved parent and
child identities are verified before completed results can be reused.
Ordinary EDA still runs; model source and approval payloads are not sent to
forecast reasoning. The Agent can choose a subset but cannot rewrite source,
calibrate fixed parameters or add models. Generic summaries preserve exact
custom identity without executing source. Compatible new-data replay uses
update_forecast() with explicit allow_iterate_forecast = FALSE and a new
identically enrolled parent. Changed enrollment or series requires 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
)
# run the forecast iteration process
iterate_forecast(
agent_info = agent_info,
max_iter = 3,
weighted_mape_goal = 0.03
)
} # }