Mechanical budgets and H2O-style stopping-rule names

- rename: patience -> stopping_rounds, stopping tolerance now named
  stopping_tolerance (H2O conventions); old meta names honoured on
  resume
- max_steps / max_runtime: hard budgets enforced in code, not prompt -
  run_r_code refuses past the limit and tells the agent to finalise;
  warnings appear in tool results from 80% spend; refine/validate
  phases and repair rounds are skipped once exhausted; budget is
  disclosed in the system prompt when finite

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mattyoreilly

R/app.R

@@ -68,10 +68,10 @@ atlas_app_ui <- function() {
         bslib::accordion_panel(
           "When to stop",
           shiny::numericInput(
-            "patience", "Attempts in a row without improvement",
+            "stopping_rounds", "Attempts in a row without improvement",
             value = 3, min = 1, max = 10, step = 1),
           shiny::numericInput(
-            "min_improve", "Smallest improvement that counts (0.05 = 5%)",
+            "stopping_tolerance", "Smallest improvement that counts (0.05 = 5%)",
             value = 0.05, min = 0, max = 1, step = 0.01)
         )
       ),
@@ -232,8 +232,8 @@ atlas_app_server <- function(input, output, session) {
       atlas_app_worker,
       args = list(dir = dir, outcome = input$outcome,
                   n_models = input$n_models, goal = input$goal,
-                  rules = input$rules, patience = input$patience,
-                  min_improve = input$min_improve,
+                  rules = input$rules, stopping_rounds = input$stopping_rounds,
+                  stopping_tolerance = input$stopping_tolerance,
                   exclude = setdiff(setdiff(names(df), input$outcome),
                                     input$features)),
       stdout = "|", stderr = "2>&1"
@@ -493,7 +493,7 @@ atlas_load_results <- function(dir) {
 # stdout, which the app tails. With `instruction` set it resumes the existing
 # session and sends a follow-up instead of starting a fresh build.
 atlas_app_worker <- function(dir, outcome = NULL, n_models = 3, goal = NULL,
-                             rules = NULL, patience = 3, min_improve = 0.05,
+                             rules = NULL, stopping_rounds = 3, stopping_tolerance = 0.05,
                              exclude = NULL, instruction = NULL) {
   ask_via_files <- function(question) {
     qf <- file.path(dir, "question.txt")
@@ -541,7 +541,7 @@ atlas_app_worker <- function(dir, outcome = NULL, n_models = 3, goal = NULL,
   s <- Atlas::AtlasSession$new(data, outcome, n_models = n_models, goal = goal,
                                constraints = cons, dir = dir,
                                on_ask = ask_via_files, display = "markdown",
-                               patience = patience, min_improve = min_improve,
+                               stopping_rounds = stopping_rounds, stopping_tolerance = stopping_tolerance,
                                exclude = exclude,
                                interject = interject_via_files)
   s$build(verbose = TRUE)

R/atlas.R

@@ -11,12 +11,12 @@
 #' @param data A data.frame.
 #' @param outcome Name of the outcome column (string).
 #' @param n_models Maximum number of candidate models to build; the agent
-#'   stops earlier when the stopping rules trigger (see `patience` and
-#'   `min_improve`).
-#' @param patience Stopping rule: give up on an iteration (adding candidate
+#'   stops earlier when the stopping rules trigger (see `stopping_rounds` and
+#'   `stopping_tolerance`).
+#' @param stopping_rounds Stopping rule: give up on an iteration (adding candidate
 #'   models, or a refinement loop like "keep improving the features") after
 #'   this many consecutive attempts without improvement.
-#' @param min_improve Stopping rule: an attempt only counts as an improvement
+#' @param stopping_tolerance Stopping rule: an attempt only counts as an improvement
 #'   if it beats the best validation metric so far by at least this relative
 #'   fraction, between 0 and 1 — e.g. `0.05` for 5%.
 #' @param exclude Columns the models must not use — because they won't be
@@ -38,8 +38,8 @@
 #' @param refine After the winning algorithm is found (and constraints pass),
 #'   keep iterating on its feature selection and engineering — one change per
 #'   attempt, same validation scheme — until the stopping rules trigger
-#'   (`patience` consecutive attempts without a relative gain of at least
-#'   `min_improve`). The refined model lands in the results as
+#'   (`stopping_rounds` consecutive attempts without a relative gain of at least
+#'   `stopping_tolerance`). The refined model lands in the results as
 #'   `<winner>_refined`, alongside the original.
 #' @param validate Produce reviewable validation output for the winning model
 #'   (gain, calibration, grouped residuals, one-ways, PDPs) as interactive
@@ -55,9 +55,9 @@
 #' @param verbose Stream the agent's narration to the console.
 #' @param autonomous Run with no human in the loop: the agent states its plan
 #'   and proceeds instead of waiting for approval, and never asks questions.
-#'   Combine with a generous `n_models`/`patience` and `test_prop` for
+#'   Combine with a generous `n_models`/`stopping_rounds` and `test_prop` for
 #'   unattended experimentation runs — e.g.
-#'   `atlas(d, "y", autonomous = TRUE, n_models = 10, patience = 8,
+#'   `atlas(d, "y", autonomous = TRUE, n_models = 10, stopping_rounds = 8,
 #'   test_prop = 0.2)` — where the agent iterates keep/discard experiments
 #'   and the survivors are judged on the held-out test set at the end.
 #' @param test_prop Proportion of rows (0 to <1) to hold out as a final test
@@ -73,6 +73,12 @@
 #'   Keeps long runs inside the context window and stops them paying to
 #'   re-read their own history. `Inf` disables. The total cost of a session
 #'   is reported as `cost` in the results and by `print()`.
+#' @param max_steps,max_runtime Hard budgets, mechanically enforced (unlike
+#'   the stopping rules, which the agent applies itself): the maximum number
+#'   of code executions and wall-clock seconds for the session. The agent is
+#'   warned in tool results as a budget nears exhaustion; past the limit,
+#'   code execution is refused and it must finalise from what it has. `Inf`
+#'   (default) disables. Recommended for `autonomous` runs.
 #' @return An object of class `atlas`: list with `models` (named list of
 #'   fitted models), `leaderboard` (data.frame of validation metrics),
 #'   `test_leaderboard` (held-out test metrics, when `test_prop > 0`),
@@ -98,14 +104,16 @@
 atlas <- function(data, outcome, n_models = 3, goal = NULL,
                   constraints = NULL, chat = NULL, dir = NULL,
                   verbose = TRUE, max_fix_rounds = 2,
-                  patience = 3, min_improve = 0.05, refine = TRUE,
+                  stopping_rounds = 3, stopping_tolerance = 0.05, refine = TRUE,
                   validate = TRUE, exclude = NULL,
-                  autonomous = FALSE, test_prop = 0, compact_at = 1e5) {
+                  autonomous = FALSE, test_prop = 0, compact_at = 1e5,
+                  max_steps = Inf, max_runtime = Inf) {
   session <- AtlasSession$new(data, outcome, n_models = n_models, goal = goal,
                               constraints = constraints, chat = chat, dir = dir,
-                              patience = patience, min_improve = min_improve,
+                              stopping_rounds = stopping_rounds, stopping_tolerance = stopping_tolerance,
                               exclude = exclude, autonomous = autonomous,
-                              test_prop = test_prop, compact_at = compact_at)
+                              test_prop = test_prop, compact_at = compact_at,
+                              max_steps = max_steps, max_runtime = max_runtime)
   session$build(verbose = verbose, max_fix_rounds = max_fix_rounds,
                 refine = refine, validate = validate)
   session$results()