docs: full pre-release audit — every example executed, gaps filled

A fresh-eyes completeness pass over README, quickstart, the site, and
the binding READMEs, with every SQL block executed against the built
extension across Python, Node (node:sqlite, better-sqlite3, Drizzle),
SQLAlchemy, Rust, and the SQLite CLI.

Broken examples found by execution and fixed: the README installing
snippet still called the deleted forecast TVF; the README distill
examples fed a TEXT column as a feature (students are numeric-only,
now documented); quickstart printed literal \n in headers. Stale
claims corrected: sub-pca is not the anomaly default (theta-classic
is), backtest pins theta-classic and accepts only statistical ids or
auto, predict_ulid requires an ISO-8601 argument and is deterministic.

Gaps filled: accepted timestamp formats and whole-second flooring;
predict()'s row_ref convention (first apply column echoed, never a
feature; features match train columns by name); distill_forecast's
window-mode column layout (context then horizon*nquant, by position);
predict_register in the functions reference; the missing quantiles
option and training defaults; documented limits (2,097,152 max input
rows, context_limit defaults, predict's 100k-row/64-feature caps); and
the CLI page now names the GitHub release assets + SHA256SUMS and
warns that macOS /usr/bin/sqlite3 cannot .load. The PyPI page body
(bindings/python/README.md) loses its stale everpure title and wrong
import.

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

Author: mstrathman

README.md

@@ -75,11 +75,11 @@ that model the same way it owns its tables.
 ```sql
 -- once: distill (your labels, or a teacher's precomputed predictions)
 SELECT model_id, holdout_metric FROM distill_predict(
-  'SELECT tenure, spend, plan, churned FROM customers',
+  'SELECT tenure, spend, churned FROM customers',
   '{"target":"churned","student_id":"churn-v1","student_kind":"gbt"}');
 
 -- forever: serve the student per row, in microseconds, no runtime attached
-SELECT * FROM predict(NULL, 'SELECT id, tenure, spend, plan FROM customers',
+SELECT * FROM predict(NULL, 'SELECT id, tenure, spend FROM customers',
                       '{"model":"churn-v1"}');
 
 -- the same move for time series: distill a Chronos-class teacher's forecasts
@@ -208,7 +208,9 @@ interpretable); `'gbt'` is a gradient-boosted forest with second-order
 matches or beats tuned XGBoost on most tasks; `'mlp'` is a one-hidden-layer
 neural net (classification only) for boundaries an axis-aligned tree ensemble
 renders poorly. All three run in the zero-dependency core and are
-deterministic.
+deterministic. Distillation feature columns must be numeric: encode
+categorical text before distilling (the in-context `knn5-incontext` handles
+text features itself; the distillers do not).
 
 When the teacher gives calibrated probabilities (as a foundation model does),
 distill its whole distribution instead of its hard label with `proba` and
@@ -220,7 +222,7 @@ hard label throws away.
 -- distill TabFM's predicted probabilities (columns p_stay, p_churn), while the
 -- true `churned` label scores the holdout
 SELECT model_id, holdout_metric FROM distill_predict(
-  'SELECT tenure, spend, plan, p_stay, p_churn, churned FROM scored',
+  'SELECT tenure, spend, p_stay, p_churn, churned FROM scored',
   '{"target":"churned","proba":["p_stay","p_churn"],
     "classes":["stay","churn"],"student_id":"churn-soft"}');
 ```
@@ -270,7 +272,7 @@ import sqlite3, sqlite_predict
 
 db = sqlite3.connect("app.db")
 sqlite_predict.load(db)
-db.execute("SELECT * FROM forecast('SELECT ts, value FROM readings', 24)")
+db.execute("SELECT forecast(ts, value, 24) FROM readings")
 ```
 
 Or drop the extension into any SQLite client directly. Three ways, in order of

bindings/python/README.md

@@ -1,12 +1,12 @@
-# everpure-sqlite-predict
+# sqlite-predict
 
 Prediction as a SQL primitive for SQLite: `forecast()`, `detect_anomalies()`,
 `predict()`. The wheel bundles the zero-dependency loadable extension for your
 platform.
 
 ```python
 import sqlite3
-from everpure import sqlite_predict
+import sqlite_predict
 
 db = sqlite3.connect(":memory:")
 sqlite_predict.load(db)

examples/quickstart.sql

@@ -13,7 +13,8 @@ SELECT datetime('2024-01-01', '+' || i || ' hours') AS ts,
           + (CASE WHEN i = 300 THEN 60 ELSE 0 END) AS value
 FROM t;
 
-.print '\n== forecast the next 24 hours, with prediction intervals =='
+.print ''
+.print '== forecast the next 24 hours, with prediction intervals =='
 -- forecast() is an aggregate: your statement supplies the rows (WHERE,
 -- joins, and GROUP BY all compose), and each group returns one JSON
 -- document: {"model", "status", "rows"}. Expand it to typed rows with
@@ -26,20 +27,23 @@ SELECT r.step,
 FROM forecast_rows((SELECT forecast(ts, value, 24) FROM readings)) AS r
 LIMIT 5;
 
-.print '\n== find the anomaly (sub-pca, a SOTA-level subsequence detector) =='
+.print ''
+.print '== find the anomaly (sub-pca, a SOTA-level subsequence detector) =='
 SELECT r.ts,
        round(r.value, 1)               AS value,
        round(r.anomaly_probability, 3) AS score
 FROM anomaly_rows((SELECT detect_anomalies(ts, value, '{"model":"sub-pca"}')
                    FROM readings)) AS r
 WHERE r.is_anomaly = 1;
 
-.print '\n== multi-series is just GROUP BY =='
+.print ''
+.print '== multi-series is just GROUP BY =='
 SELECT substr(ts, 12, 2) AS hour_of_day,
        json_extract(forecast(ts, value, 4), '$.status') AS status
 FROM readings GROUP BY hour_of_day LIMIT 4;
 
-.print '\n== how accurate is it here? backtest on your own data =='
+.print ''
+.print '== how accurate is it here? backtest on your own data =='
 SELECT fold, model, round(mase, 2) AS mase, round(coverage, 2) AS coverage
 FROM backtest('SELECT ts, value FROM readings', 24, '{"folds":5}')
 LIMIT 5;

website/src/content/docs/benchmarks.md

@@ -16,7 +16,7 @@ seasonal-naive floor of 1.0.
 | Model | MASE | Notes |
 | --- | --- | --- |
 | seasonal-naive | 1.11 | the floor |
-| theta-classic | 1.03 | bundled default, zero dependencies |
+| theta-classic | 1.03 | bundled statistical model, zero dependencies |
 | distilled Chronos student | 0.89 | native blob, no runtime at serve time |
 | Chronos (teacher, ONNX) | ~0.80 | for reference; needs the ONNX build |
 

website/src/content/docs/getting-started/cli.md

@@ -7,7 +7,9 @@ description: Load sqlite-predict in the SQLite CLI, or vendor the single C file.
 
 Download a prebuilt loadable for your platform from the
 [GitHub releases](https://github.com/PureStorage-OpenConnect/sqlite-predict/releases)
-and `.load` it:
+(`predict0-<os>-<arch>.{so,dylib,dll}`, checksums in `SHA256SUMS`) and
+`.load` it. One macOS note: the system `/usr/bin/sqlite3` is compiled without
+extension loading, so use a stock CLI (`brew install sqlite`):
 
 ```sh
 sqlite3 mydata.db

website/src/content/docs/guides/distillation.md

@@ -27,13 +27,17 @@ SELECT row_ref, prediction, confidence FROM predict(NULL,
 
 The `NULL` first argument is the signature of serving a student: `predict`
 normally takes a training query for in-context models, but a student carries
-its training inside its blob, so passing one is an error.
+its training inside its blob, so pass `NULL`; a query in that position is
+not read when a student serves the call.
 
 `student_kind` is `tree` (a single CART), `gbt` (a gradient-boosted forest
 with second-order leaves, which matches or beats tuned XGBoost on most
 tasks), or `mlp` (a one-hidden-layer net for boundaries a tree renders
 poorly). With `proba` and `classes` the student learns the teacher's full
 probability distribution (soft-label distillation), not just its argmax.
+Feature columns must be numeric: encode categorical text before distilling
+(the in-context `knn5-incontext` handles text features itself; the distiller
+does not).
 
 ## Forecasting: distill with `distill_forecast`, serve with `forecast`
 
@@ -55,9 +59,12 @@ SELECT forecast(ts, value, 12, '{"model":"auto"}') FROM readings;
 
 The student is a DLinear/TiDE-style net (a linear skip plus a small
 residual). Without an onnx teacher, `distill_forecast` also trains directly
-from windowed rows: each training row is `context` window columns followed by
-`horizon` continuation columns (your own teacher's forecasts, computed
-anywhere and stored as columns).
+from windowed rows: each training row is, by position, `context` window
+columns followed by `horizon` continuation columns (your own teacher's
+forecasts, computed anywhere and stored as columns), and the column count
+must match exactly. Pass `quantiles` to distill a teacher's quantile fan
+instead of a point forecast: the continuation part then holds
+`horizon * nquant` columns, one block of quantile levels per step.
 
 ## Distribute the student
 

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

@@ -14,8 +14,15 @@ is written, so they work on read-only databases and inside views.
 
 One `(ts, value)` observation per input row; rows are sorted by `ts`
 internally, so input order never matters. `horizon` is 1 to 1000, and it and
-`options` must be constant within a group. Returns one JSON document per
-group:
+`options` must be constant within a group.
+
+`ts` accepts ISO-8601 UTC text (`YYYY-MM-DD`, optionally followed by
+`[T ]HH:MM[:SS][Z]`) or a non-negative integer epoch, read as seconds, or as
+milliseconds when the value is at or above 100000000000. Every timestamp is
+floored to the whole second before modeling. A statement may feed at most
+2,097,152 input rows across its groups; more raises `PREDICT_ERR_RESOURCE`.
+
+Returns one JSON document per group:
 
 ```json
 {"model": "theta-classic",
@@ -29,7 +36,8 @@ SELECT city, forecast(ts, value, 24) FROM readings GROUP BY city;
 ```
 
 `model` is the resolved model id (useful with `'{"model":"auto"}'`); `status`
-is `ok`, `truncated`, `insufficient_history`, or `non_numeric`. A degraded
+is `ok`, `truncated`, `insufficient_history` (fewer than 8 points), or
+`non_numeric`. A degraded
 series returns a status document with empty `rows`; it does not fail the
 statement. An aggregate over zero rows returns `NULL` (like `sum()`).
 
@@ -38,7 +46,8 @@ error explaining that `forecast` is an aggregate over your rows.
 
 ### `detect_anomalies(ts, value [, options])`
 
-Same document pattern; each element of `rows` carries `ts`, `value`,
+Same document pattern and the same accepted timestamp forms; each element of
+`rows` carries `ts`, `value`,
 `forecast`, `lower_bound`, `upper_bound`, `is_anomaly`,
 `anomaly_probability`. The interval fields are null during warmup and for
 model `sub-pca`.
@@ -74,27 +83,48 @@ of `(time, value)`, optionally with grouping columns. Columns: `series_key`,
 
 Learns from `train_query` (features plus a `target` column) and predicts the
 target for every row of `apply_query`. Columns: `row_ref`, `prediction`,
-`confidence`, `status`. To serve a distilled student, pass its id as the
+`confidence`, `status`.
+
+The first column of `apply_query` is the row reference: it is echoed back as
+`row_ref` so you can join predictions to your rows, and it is **never a
+feature**. Every column after it is a feature and must match a `train_query`
+feature column **by name**; an apply column with no matching train column is
+an error. So `predict('SELECT f1, f2, label FROM t', 'SELECT id, f1, f2 FROM
+u', '{"target":"label"}')` trains on `f1, f2` and predicts one row per `u`
+row, keyed by `id`.
+
+To serve a distilled student, pass its id as the
 `model` option and `NULL` as `train_query` (the student already learned):
 `predict(NULL, 'SELECT id, f1, f2 FROM t', '{"model":"churn-v1"}')`.
 
+The default in-context model caps training at 100,000 rows and 64 feature
+columns; more raises `PREDICT_ERR_CONTEXT_TOO_LARGE` / `PREDICT_ERR_SCHEMA`.
+
 ### `distill_predict(train_query [, options])`
 
-Fits a native tabular student and registers it. Columns: `model_id`,
+Fits a native tabular student and registers it. Requires the `target` and
+`student_id` options; feature columns must be numeric. Columns: `model_id`,
 `content_hash`, `train_rows`, `holdout_metric`.
 
 ### `distill_forecast(train_query [, options])`
 
-Fits a native forecast student and registers it. Columns: `model_id`,
-`content_hash`, `train_rows`, `train_rmse`.
+Fits a native forecast student and registers it. Requires the `context`,
+`horizon`, and `student_id` options. Two input modes: with a `teacher`
+(ONNX build), `train_query` yields `(series_key, value)` rows and the teacher
+labels sliding windows; without one, each `train_query` row is a training
+window laid out by position as `context` input columns followed by the
+`horizon` continuation columns (or `horizon * nquant` quantile columns when
+`quantiles` is passed), and the column count must match exactly. Columns:
+`model_id`, `content_hash`, `train_rows`, `train_rmse`.
 
 ## Scalar utilities
 
 | Function | Returns |
 | --- | --- |
 | `predict_version()` | the extension version string |
-| `predict_ulid([ts])` | a fresh ULID, optionally seeded with an epoch-ms timestamp |
+| `predict_ulid(ts)` | the smallest ULID for an ISO-8601 UTC timestamp: deterministic (the time component is set, the entropy bits are zero), useful as a range key |
 | `predict_debug()` | build info: profile, compiled features, available runtimes |
+| `predict_register(model_id, config)` | registers an external model in `_predict_models` and returns its content hash; `config` is a bare weights path or a JSON object (`runtime`, `kind`, `license`, `weights_uri`, `io_spec`, `target`). Registration is metadata only: executing an `onnx` model still needs the ONNX build |
 
 See [Options](../options/) for the per-function option set and
 [Models](../models/) for the `model` values.

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

@@ -10,16 +10,18 @@ bundled model ships in the zero-dependency core, no ONNX runtime required.
 
 | `model` | Kind | Notes |
 | --- | --- | --- |
-| `theta-classic` | statistical | The Theta method. Default (`default-ts` aliases to it). Strong, cheap trend + seasonality baseline. |
+| `auto` | meta | The default when no `model` is named. Rolling-origin backtests each candidate per series and forecasts with the lowest-error one. See [Auto-selection](../../guides/auto-and-conformal/). |
+| `theta-classic` | statistical | The Theta method (`default-ts` aliases to it). Strong, cheap trend + seasonality baseline. |
 | `stub-seasonal-naive` | statistical | Seasonal-naive with drift. The benchmark floor every forecasting paper reports against. |
 | `tsb` | statistical | Teunter-Syntetos-Babai, for intermittent demand (many zeros). Forecast-only. |
-| `auto` | meta | Rolling-origin backtests each candidate per series and forecasts with the lowest-error one. See [Auto-selection](../../guides/auto-and-conformal/). |
 
 ## Anomaly detection
 
 | `model` | Kind | Notes |
 | --- | --- | --- |
-| `sub-pca` | statistical | Subsequence PCA (Jacobi eigensolver in C). Default detector; competitive with SOTA on the TSB-AD-U benchmark. |
+| `theta-classic` | statistical | The default detector: flags points that fall outside the one-step-ahead forecast interval. |
+| `stub-seasonal-naive` | statistical | The same residual detector over the seasonal-naive forecaster. |
+| `sub-pca` | statistical | Subsequence PCA (Jacobi eigensolver in C); competitive with SOTA on the TSB-AD-U benchmark. Pick it with `'{"model":"sub-pca"}'`; its rows carry no interval fields. |
 
 ## Tabular prediction
 

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

@@ -5,7 +5,9 @@ description: Every option each function accepts, passed as a trailing JSON objec
 
 Options are a single JSON object in the last argument. Unknown keys and
 wrong-typed values are rejected with `PREDICT_ERR_OPTIONS`, so a typo fails loud
-rather than being ignored.
+rather than being ignored. `distill_forecast` is the one exception today: it
+reads only its known keys and ignores anything else, so check its spelling
+yourself.
 
 ## forecast
 
@@ -17,7 +19,7 @@ rather than being ignored.
 | `folds` | integer | 20 | Rolling origins used by `auto` / conformal. |
 | `gap` | integer | 0 | Leakage guard between train and target. |
 | `candidates` | string[] | stat models + eligible registered students | Narrows the `auto` pool. |
-| `context_limit` | integer | model default | Cap on points fed to the model. |
+| `context_limit` | integer | 4096 | Cap on points fed to the model (the most recent are kept; a capped series reports status `truncated`). |
 
 Aggregate rules: the `options` argument and `horizon` must be the same value
 on every row of a group, and a `SELECT` string passed as the first argument is
@@ -27,7 +29,9 @@ columns and `GROUP BY` carries the series split.
 
 ## detect_anomalies
 
-`model` and `context_limit` as above, plus:
+`model` and `context_limit` as above, except that `model` defaults to
+`theta-classic` (the residual detector) and `context_limit` defaults to 0:
+the detector scores the whole series unless you cap it. Plus:
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
@@ -37,9 +41,11 @@ The same aggregate rules apply.
 
 ## backtest
 
-`confidence_level`, `interval_method`, `folds`, `gap`, `context_limit`, and
-`model` as for `forecast`, plus the query-shape keys (backtest takes its data
-as a query, so columns must be resolvable):
+`confidence_level`, `interval_method`, `folds`, `gap`, and `context_limit` as
+for `forecast`. `model` differs: it must be a statistical model id or `auto`,
+and it defaults to `theta-classic`, not `auto`; a distilled student competes
+inside `auto` but cannot be pinned here. Plus the query-shape keys (backtest
+takes its data as a query, so columns must be resolvable):
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
@@ -51,7 +57,7 @@ as a query, so columns must be resolvable):
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `target` | string | required | Column in `train_query` to learn. |
+| `target` | string | required for in-context models | Column in `train_query` to learn. A served student (`train_query` = `NULL`) needs no target. |
 | `task` | `classify` \| `regress` | inferred | Prediction task. |
 | `model` | string | `knn5-incontext` | Model or distilled student id. |
 | `device` | `cpu` \| `gpu` | `cpu` | Inference device (onnx build). |
@@ -60,22 +66,33 @@ as a query, so columns must be resolvable):
 
 ## distill_predict
 
+`target` and `student_id` are required. Feature columns must be numeric:
+encode categorical text before distilling (the in-context `knn5-incontext`
+handles text features itself; the distiller does not).
+
 | Key | Type | Meaning |
 | --- | --- | --- |
-| `target` | string | Target column. |
-| `task` | `classify` \| `regress` | Task. |
-| `student_id` | string | Id to register the student under. |
-| `student_kind` | `tree` \| `gbt` \| `mlp` | Student architecture. |
-| `teacher` | string | Teacher model (onnx build) for soft labels. |
-| `proba`, `classes` | | Soft-label distillation of a probability distribution. |
+| `target` | string | Target column. Required. |
+| `task` | `classify` \| `regress` | Task. Inferred when omitted. |
+| `student_id` | string | Id to register the student under. Required. |
+| `student_kind` | `tree` \| `gbt` \| `mlp` | Student architecture. Default `tree` (soft-label distillation implies `gbt`). |
+| `teacher` | string | A registered model that relabels the training rows first. |
+| `proba`, `classes` | string[] | Soft-label distillation: per-class probability columns and their class labels. |
 
 ## distill_forecast
 
+`context`, `horizon`, and `student_id` are required. Without a `teacher`,
+each `train_query` row is one training window laid out by position:
+`context` input columns, then the `horizon` continuation columns (or
+`horizon * nquant` quantile columns when `quantiles` is passed); the column
+count must match exactly.
+
 | Key | Type | Meaning |
 | --- | --- | --- |
-| `student_id` | string | Id to register the student under. |
-| `teacher` | string | Teacher forecast model (onnx build). |
-| `context` | integer | Input window length. |
-| `horizon` | integer | Forecast length the student is trained for. |
-| `hidden` | integer | Residual-net hidden width. |
-| `epochs`, `lr` | | Training epochs and learning rate. |
+| `student_id` | string | Id to register the student under. Required. |
+| `teacher` | string | Teacher forecast model (onnx build): `train_query` then yields `(series_key, value)` rows and the teacher labels sliding windows. |
+| `context` | integer | Input window length. Required; max 4096. |
+| `horizon` | integer | Forecast length the student is trained for. Required. |
+| `quantiles` | number[] | Quantile levels to distill from a teacher's quantile fan. Default: a point (median-only) student. |
+| `hidden` | integer | Residual-net hidden width, 0 to 2048 (0 = pure linear student). Default 256. |
+| `epochs`, `lr` | | Training epochs (default 1500) and learning rate (default 0.005). |