feat: auto is the forecast default when no model is named

A bare forecast(ts, value, h) now means "the best model available in
this database": rolling-origin selection over the bundled statistical
models plus every eligible registered forecast student, per series,
deterministically. Combined with implicit student discovery, the whole
distillation loop needs zero options: distill once, and every plain
forecast call everywhere starts considering your student.

Measured cost of the richer default: ~0.1 ms at 96 points, ~3 ms at
480, ~60 ms at the 4096-point context cap (vs ~2 ms pinned); the
escape hatches are pinning a model or lowering context_limit, both
documented. detect_anomalies keeps theta-classic (no auto selection
exists for scoring) and backtest keeps theta-classic (it evaluates a
named model); predict keeps knn5-incontext. The RFC's reserved
default-ts alias machinery is replaced by these concrete defaults.

Consequence made coherent: bare `candidates` now narrows the default
pool instead of erroring with "requires model=auto"; candidates plus a
pinned model remains a contradiction and still errors.

Fixed a latent bug this exposed: when an aggregate step raised (bad
horizon, query-string misuse), xFinal still ran the full pipeline with
unvalidated arguments, and the auto path's horizon-sized scratch then
hit malloc(0) and surfaced as a spurious MemoryError. Steps now set an
errored flag and the finals short-circuit; every step-phase error path
sets it.

Tests: default==auto byte-equality, bare-candidates narrowing plus the
pinned-model contradiction, and the updated default-model assertions.
183 pass on the plain build, 218 on onnx, ASan clean. Docs, README,
options reference, auto guide, RFC, and CHANGELOG updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mstrathman

CHANGELOG.md

@@ -8,6 +8,17 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`auto` is the forecast default.** A `forecast(ts, value, h)` call with
+  no `model` option now selects the best model per series instead of pinning
+  theta-classic, at a cost of single-digit milliseconds on typical series
+  (pin a `model` or lower `context_limit` on latency-critical long-series
+  paths). `candidates` no longer requires naming `model:"auto"` first, since
+  bare `candidates` narrows the default pool; combining `candidates` with a
+  pinned model remains an error. `detect_anomalies` (no auto exists) and
+  `backtest` (evaluates a named model) keep `theta-classic` as their
+  default. Also hardened: a step-phase aggregate error (bad horizon, query
+  string misuse) now short-circuits the final, instead of running the
+  pipeline with unvalidated arguments.
 - **Registered students compete under `auto` by default.** With
   `'{"model":"auto"}'` and no `candidates` list, the pool is the bundled
   statistical models plus every eligible registered forecast student:

README.md

@@ -140,12 +140,13 @@ trailing JSON object (`'{"confidence_level":0.9}'`).
 
 ### Calibrated intervals, auto-selection, and backtesting
 
-- **Auto-selection.** `'{"model":"auto"}'` picks the model with the lowest
-  rolling-origin error per series, deterministically, over the bundled
-  statistical models plus every eligible registered forecast student: distill
-  once and your model competes with the baselines automatically, at every
-  call site. `'{"model":"auto","candidates":[...]}'` narrows the pool. The
-  result document's `model` field reports the winner.
+- **Auto-selection is the default.** A call with no `model` option picks the
+  model with the lowest rolling-origin error per series, deterministically,
+  over the bundled statistical models plus every eligible registered forecast
+  student: distill once and your model competes with the baselines
+  automatically, at every call site. `'{"candidates":[...]}'` narrows the
+  pool; `'{"model":"theta-classic"}'` pins one. The result document's
+  `model` field reports the winner.
 - **Conformal intervals.** `'{"interval_method":"conformal"}'` replaces the
   default Gaussian band with a distribution-free one calibrated on out-of-sample
   residuals. On smooth data the default band is overconfident; conformal lands

predict-forecast.c

@@ -1524,7 +1524,8 @@ static int fc_discover_candidates(sqlite3 *db, const ForecastOpts *opts,
 static int fc_resolve_models(sqlite3 *db, const ForecastOpts *opts,
                              int horizon, FcModels *mc, char **errmsg) {
   memset(mc, 0, sizeof(*mc));
-  mc->is_auto = opts->model && strcmp(opts->model, "auto") == 0;
+  /* no model named means "the best available": auto is the default */
+  mc->is_auto = !opts->model || strcmp(opts->model, "auto") == 0;
   mc->model = mc->is_auto ? NULL : resolve_ts_model(opts->model);
   if (!mc->is_auto && !mc->model) {
     /* not a bundled model: maybe a registered forecast student (PSFCST) */
@@ -2821,6 +2822,7 @@ typedef struct {
   i64 horizon; /* forecast only */
   int have_horizon;
   int started;
+  int errored; /* a step raised: the final must not run the pipeline */
 } AggSeries;
 
 static void agg_series_clear(AggSeries *a) {
@@ -2869,19 +2871,22 @@ static void agg_step(sqlite3_context *ctx, int argc, sqlite3_value **argv,
           PREDICT_ERR_SCHEMA, fname, fname, horizon_arg >= 0 ? ", horizon" : "");
       sqlite3_result_error(ctx, msg ? msg : PREDICT_ERR_SCHEMA, -1);
       sqlite3_free(msg);
+      a->errored = 1;
       return;
     }
     if (horizon_arg >= 0) {
       if (sqlite3_value_type(argv[horizon_arg]) != SQLITE_INTEGER) {
         sqlite3_result_error(
             ctx, PREDICT_ERR_HORIZON ": horizon must be an integer", -1);
+        a->errored = 1;
         return;
       }
       a->horizon = sqlite3_value_int64(argv[horizon_arg]);
       a->have_horizon = 1;
       if (a->horizon < 1 || a->horizon > FORECAST_MAX_HORIZON) {
         sqlite3_result_error(
             ctx, PREDICT_ERR_HORIZON ": horizon out of range 1..1000", -1);
+        a->errored = 1;
         return;
       }
     }
@@ -2903,6 +2908,7 @@ static void agg_step(sqlite3_context *ctx, int argc, sqlite3_value **argv,
       sqlite3_result_error(
           ctx, PREDICT_ERR_HORIZON ": horizon must be constant within a group",
           -1);
+      a->errored = 1;
       return;
     }
     int opt_i = horizon_arg >= 0 ? horizon_arg + 1 : 2;
@@ -2916,6 +2922,7 @@ static void agg_step(sqlite3_context *ctx, int argc, sqlite3_value **argv,
       sqlite3_result_error(
           ctx, PREDICT_ERR_OPTIONS ": options must be constant within a group",
           -1);
+      a->errored = 1;
       return;
     }
   }
@@ -2954,6 +2961,7 @@ static void agg_step(sqlite3_context *ctx, int argc, sqlite3_value **argv,
   if (a->n >= FORECAST_MAX_TOTAL_ROWS) {
     sqlite3_result_error(ctx, PREDICT_ERR_RESOURCE ": too many input rows",
                          -1);
+    a->errored = 1;
     return;
   }
   if (a->n == a->cap) {
@@ -2968,6 +2976,7 @@ static void agg_step(sqlite3_context *ctx, int argc, sqlite3_value **argv,
       a->cap = 0;
       a->n = 0;
       sqlite3_result_error_nomem(ctx);
+      a->errored = 1;
       return;
     }
     a->ts = nts;
@@ -3045,6 +3054,11 @@ static void agg_fc_final(sqlite3_context *ctx) {
     sqlite3_result_null(ctx);
     return;
   }
+  if (a->errored) { /* a step already raised; the result is discarded */
+    agg_series_clear(a);
+    sqlite3_result_error_code(ctx, SQLITE_ERROR);
+    return;
+  }
   sqlite3 *db = sqlite3_context_db_handle(ctx);
   int horizon = (int)a->horizon;
 
@@ -3148,6 +3162,11 @@ static void agg_an_final(sqlite3_context *ctx) {
     sqlite3_result_null(ctx);
     return;
   }
+  if (a->errored) { /* a step already raised; the result is discarded */
+    agg_series_clear(a);
+    sqlite3_result_error_code(ctx, SQLITE_ERROR);
+    return;
+  }
   sqlite3 *db = sqlite3_context_db_handle(ctx);
 
   ForecastOpts opts;

tests/test_aggregate.py

@@ -348,3 +348,12 @@ def test_sqlalchemy_composes_the_aggregate(db):
         assert len(out) == 1
         d = json.loads(out[0].doc)
         assert d["status"] == "ok" and len(d["rows"]) == 4
+
+
+def test_no_model_defaults_to_auto(db):
+    rows, _ = syn.trend_season(n=96, seed=57)
+    syn.load_into(db, rows)
+    bare = db.execute("SELECT forecast(ts, value, 6) FROM series").fetchone()[0]
+    auto = db.execute("SELECT forecast(ts, value, 6,"
+                      " '{\"model\":\"auto\"}') FROM series").fetchone()[0]
+    assert bare and bare == auto  # byte-identical documents

tests/test_backtest.py

@@ -273,12 +273,20 @@ def test_candidates_restrict_and_select_pool(db):
     assert both == tsb_only                           # auto picks tsb (the better)
 
 
-def test_candidates_requires_auto(db):
+def test_candidates_narrows_the_default_and_rejects_named_models(db):
     series, _ = syn.trend_season(n=100, seed=1)
     syn.load_into(db, series)
+    # auto is the default, so bare candidates narrows the default pool
+    doc = json.loads(db.execute(
+        "SELECT forecast(ts, value, 6, ?) FROM series",
+        (json.dumps({"candidates": ["theta-classic"]}),)).fetchone()[0])
+    assert doc["status"] == "ok"
+    assert doc["model"] == "theta-classic"
+    # but candidates alongside a pinned non-auto model is a contradiction
     with pytest.raises(sqlite3.OperationalError) as e:
         db.execute("SELECT forecast(ts, value, 6, ?) FROM series",
-                   (json.dumps({"candidates": ["theta-classic"]}),)).fetchone()
+                   (json.dumps({"model": "tsb",
+                                "candidates": ["theta-classic"]}),)).fetchone()
     assert "PREDICT_ERR_OPTIONS" in str(e.value)
 
 

website/src/content/docs/guides/auto-and-conformal.md

@@ -5,14 +5,20 @@ description: Let sqlite-predict pick the model, and get calibrated prediction in
 
 ## Auto-selection
 
-You don't have to hand-pick a model. `'{"model":"auto"}'` runs a rolling-origin
-backtest of each candidate on the series and forecasts with the lowest-error one.
-The choice is deterministic: the same rows pick the same winner.
+You don't have to pick a model at all: **auto is the default**. A call with no
+`model` option runs a rolling-origin backtest of each candidate on the series
+and forecasts with the lowest-error one. The choice is deterministic: the same
+rows pick the same winner.
 
 ```sql
-SELECT forecast(ts, value, 12, '{"model":"auto"}') FROM readings;
+SELECT forecast(ts, value, 12) FROM readings;   -- auto, implicitly
 ```
 
+Selection backtests every candidate per call, which costs single-digit
+milliseconds on typical series and tens of milliseconds at the 4096-point
+context cap. On a latency-critical path over long series, pin a `model` or
+lower `context_limit`.
+
 The default pool is the bundled statistical models (`theta-classic`,
 `stub-seasonal-naive`, `tsb` for intermittent demand) **plus every eligible
 registered forecast student**: distill a model once and `auto` competes it

website/src/content/docs/reference/options.md

@@ -11,7 +11,7 @@ rather than being ignored.
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `model` | string | `theta-classic` | Forecast model, or `auto`. |
+| `model` | string | `auto` | A model id to pin, or `auto` (the default: best of the stats plus eligible registered students, per series). |
 | `confidence_level` | number (0,1) | 0.9 | Nominal coverage of the interval. |
 | `interval_method` | `residual` \| `conformal` | `residual` | Interval construction. |
 | `folds` | integer | 20 | Rolling origins used by `auto` / conformal. |