feat(onnx): derive io_spec from the model — register with just a path

Cuts the ONNX registration UX from ~10 lines of nested JSON to one line.
predict_register now reads a model's input/output tensors and fills in the
io_spec automatically, so the common case is:

  SELECT predict_register('clf', '/models/clf.onnx');
  SELECT * FROM predict(NULL, 'SELECT id, f1, f2 FROM t', '{"model":"clf"}');

- predict0_onnx_introspect() opens the model and derives layout (1 input ->
  vector, 3 named x_train/y_train/x_query -> in_context), tensor names,
  output kind (float [N,K>1] -> probs, [N,1]/[N] -> value), and class count
  (labels default 0..K-1). It builds the io_spec via json_object, and refuses
  to guess ambiguous shapes (multi-output, non-float, unnamed 3-input) by
  asking for an explicit io_spec.
- predict_register accepts a bare weights path or a JSON config; runtime
  ('onnx'), kind ('student'), and license ('unspecified', which the gate
  allows) all default. in-context adds a top-level target (a SQL column
  introspection can't infer), spliced into the derived io_spec via json_set.
- features[] is now optional everywhere: absent -> positional mapping (apply
  column order), validated against the model's input width; present ->
  name-based mapping (the override). The tensor feature dim F is computed per
  call instead of assumed == named-feature count.
- The explicit-io_spec path is unchanged (all prior tests pass), and the
  ASan/LSan soak now also exercises the introspection + positional path.

5 new tests cover bare-path vector/regressor registration, in-context
weights+target, the unspecified-license default, and positional count
validation. README/ARCHITECTURE/CHANGELOG updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: mstrathman <matthew.strathman@gmail.com>

Author: mstrathman

ARCHITECTURE.md

@@ -48,7 +48,18 @@ serves two `io_spec` layouts. The **vector** layout is a self-contained model
 mapping a feature vector to a prediction. The **in_context** layout is a
 teacher (TabFM-shaped): it ingests the `train_query` rows as three tensors
 (`x_train`, `y_train`, `x_query`) each call and labels the query rows against
-that context. Both cache one onnxruntime session per (weights, device,
+that context.
+
+The `io_spec` is usually derived, not written. `predict_register` reads the
+model's input/output tensors (`predict0_onnx_introspect`) to fill in the
+layout, tensor names, output kind, and class count, so a bare weights path is
+a complete registration for the vector case (in-context adds only `target`,
+which is a SQL column introspection can't see). An explicit `io_spec`
+overrides the derivation. Feature columns map positionally by default (apply
+column order); a `features` list switches to name-based mapping. All the JSON
+handling — reading the `io_spec`, building the derived one — goes through
+SQLite's JSON1 (`json_extract`/`json_each`/`json_object`), never a hand-rolled
+parser. Both cache one onnxruntime session per (weights, device,
 precision), run query rows in batches, and select the execution provider
 explicitly, erasing no failure into a silent CPU fallback. Weights are pinned
 by content hash, so a receipt records exactly which bytes ran, and the

CHANGELOG.md

@@ -25,9 +25,12 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   (`make loadable-onnx-gpu`) adds the CUDA and TensorRT execution providers
   and fp16/int8 precision, compile-checked in CI and validated on a
   dedicated GPU job. The default build stays zero-dependency.
-- `predict_register(model_id, config_json)` to register an external model,
+- `predict_register(model_id, config)` to register an external model,
   pinning its weights by content hash. `_predict_models` gains `weights_uri`
-  and `io_spec`; receipts record the execution provider and precision.
+  and `io_spec`; receipts record the execution provider and precision. The
+  config can be a bare weights path: the io_spec is read off the model
+  (tensor names, output kind, class count) and feature columns map by
+  position, so the common case is one line. An explicit io_spec overrides.
 - A license gate: a non-permissive model requires `accept_license` to match
   before it will run.
 - Test suite, AddressSanitizer/UBSan and valgrind soak targets, a libFuzzer

README.md

@@ -81,14 +81,29 @@ which compresses a teacher into a compact model that serves in
 microseconds.
 
 An opt-in ONNX build (`make loadable-onnx`) runs exported models through
-onnxruntime: register one with `predict_register()` and call it by name. It
-serves two shapes, with a cached session and batched inference:
+onnxruntime. Point `predict_register()` at a model file and call it by name;
+the io_spec is read off the model (input/output tensors, output kind, class
+count), so the common case is one line:
+
+```sql
+SELECT predict_register('churn', '/models/churn.onnx');
+SELECT * FROM predict(NULL, 'SELECT id, tenure, spend FROM customers',
+                      '{"model":"churn"}');
+```
+
+Feature columns map by position (apply-query order); pass an explicit
+`io_spec` only to override — real class labels, a named-feature mapping, or a
+model whose tensors introspection can't disambiguate. It serves two shapes,
+with a cached session and batched inference:
 
 - **vector** — a self-contained model (a distilled student, or any exported
   tabular classifier/regressor) mapping a feature vector to a prediction.
+  A bare weights path is enough.
 - **in_context** — a teacher that ingests the `train_query` rows as context
-  on each call and labels the `apply_query` rows against them, the way
-  TabFM works.
+  on each call and labels the `apply_query` rows against them, the way TabFM
+  works. Register it with the weights path plus a `target` (the training
+  label column, which introspection can't infer): `predict_register('t',
+  '{"weights_uri":"/m.onnx","target":"label"}')`.
 
 Both run on CPU today. A GPU build (`make loadable-onnx-gpu`) adds the CUDA
 and TensorRT execution providers and fp16/int8 precision; it needs an

onnx_export_2026-07-22_17-08-29-313987_conversion.md

@@ -197,6 +197,16 @@ int predict0_onnx_predict(sqlite3 *db, const char *model_id,
                           predict0_result **rows, int *n,
                           char receipt_id_out[PREDICT_ULID_BUFSIZE],
                           char **errmsg);
+
+/* Derive an io_spec by reading a model's input/output tensors, so a caller
+ * can register with just a weights path. On success returns SQLITE_OK and a
+ * sqlite3_malloc'd JSON io_spec in *io_spec_out (caller frees). Covers the
+ * unambiguous shapes (1 input -> vector; 3 inputs named x_train/y_train/
+ * x_query -> in_context; a single output whose width picks probs vs value);
+ * anything it cannot disambiguate returns an error asking for an explicit
+ * io_spec. */
+int predict0_onnx_introspect(sqlite3 *db, const char *weights_uri,
+                             char **io_spec_out, char **errmsg);
 #endif
 
 /* Deterministic logical digest of all user tables (schema + rows,