Train and integrate predictive models

Grid's public Node API authorizes the owning model and forwards training and trained-model operations to Runtime Host. Runtime Host owns jobs, immutable model versions, artifacts, calibration evidence, and the selected pin. These routes do not publish a pretrained package to a remote Registry.

The 0.65.0 contract documented here is still a release candidate. Confirm the exact deployment version, edition, and capability catalog before relying on calibrated prediction behavior.

Choose the two identities deliberately

ownerModelId identifies the saved workbook whose access policy and Files sandbox authorize the operation. modelId identifies the trained model. Keep both in logs and retained receipts; they are not interchangeable.

Operation	Public route	Expected result
Start training	POST /api/train/start	202 and a job descriptor
Read a job	GET /api/train/:jobId	Current status and, when ready, the result manifest
Cancel	POST /api/train/:jobId/cancel	Current job descriptor
Register an uploaded artifact	POST /api/train/register	201 and the new owner-scoped model version
List readable models	GET /api/train/models	Records and immutable versions
Pin a version	POST /api/train/models/:id/pin	The version used by an unversioned formula reference
Archive	POST /api/train/models/:id/archive	The model becomes non-executable
Rename	POST /api/train/models/:id/rename	Display or function name changes without replacing artifact bytes

Training, cancellation, registration, pinning, archival, and rename require write access to the owner model. A returned trained-model:// value is an artifact identity, not a filesystem path or download URL.

Start and follow a point model

{
  "ownerModelId": "workbook-id",
  "modelId": "demand",
  "family": "linearRegression",
  "taskType": "regression",
  "features": [[1], [2], [3], [4]],
  "labels": [2, 4, 6, 8]
}

Poll the returned jobId until it is ready, failed, or cancelled. A ready result includes an exact candidate reference such as demand@2; use that version while validating the model. Do not let an existing pin silently substitute an older version during review.

Request calibrated prediction only when the data supports it

For eligible XGBoost regression, add a predictionUncertainty member:

{
  "predictionUncertainty": {
    "mode": "required",
    "probabilities": [0.9],
    "calibrationSplit": "temporal"
  }
}

This fragment belongs inside a complete training request. mode is off, auto, or required. auto may return a valid point-only model with an unavailable reason; required fails when the requested calibration cannot be admitted. Neither mode turns malformed input or invalid data into a fallback.

The current producer supports upper endpoints only. P90 needs at least 110 finite labeled rows: 99 calibration rows, 10 training rows, and one test row. Temporal mode preserves supplied row order and does not sort a timestamp column. Read the returned uncertainty capability and endpoint evidence rather than inferring it from job success.

Validate, then pin

Use exact-version formulas while reviewing the candidate:

point = PREDICT("demand@2", A2:C2)
upper_p90 = PREDICTION_BOUND("demand@2", A2:C2, 0.9, "upper")
evidence = MODEL_UNCERTAINTY("demand@2")

PREDICTION_BOUND fails closed when the exact model version does not advertise the requested admitted endpoint. An upper P90 is a marginal coverage target for comparable future rows, not a per-row guarantee, confidence interval for the mean, or full predictive distribution.

After the exact version passes review, pin it explicitly:

POST /api/train/models/demand/pin
Content-Type: application/json

{"version": 2}

An unversioned PREDICT("demand", features) then follows that pin. Preserve the job ID, owner model, exact model version, metrics, calibration evidence, and pin action as separate evidence.

Register external artifacts without trusting caller claims

An external registration path must stay inside the owner's Files sandbox. Absolute paths, traversal, and URLs are refused. Grid assigns the manifest path. When an exported provider sidecar is used, supply its owner-relative path and digest together.

The caller cannot self-assert predictive uncertainty. Grid derives the capability from integrity-admitted provider evidence, including format, hashes, calibration provenance, and endpoint evidence. A display summary does not authorize inference.

For the interpretation and formula contract, continue with Train and use calibrated predictions.

Integrate an opened native document

The 0.70.0 development workbench also admits training from a retained Dataset. Supply the snapshot, feature columns, optional target and reviewed budget. Retained data and legacy arrays are alternative inputs; do not combine them. Training a later candidate preserves the existing pin. Select the candidate explicitly, using the expected current pin to detect a conflicting selection.

Desktop's opened-document transport selects the physical document and model member before calling the same Rust training owner. Its jobs, uploaded assets, registry versions and prediction results belong to that document. The hosted HTTP routes above do not select an opened desktop document by display name. Keep the admitted native owner with the request instead of translating it to an unrelated hosted workbook ID.

Use the exact trained candidate for Predict and fresh Evaluate. Saved-result Evaluate reads retained outcomes without subject calls. Preparing a formula returns a Code draft for review; it does not save source or write inputs. Publishing a retained result requires a declared input, the reviewed source identity and the expected destination revision. Native rule dispatch follows the original document scheduler.

See Workbook surfaces for native workbench admission and the canonical Capture, Train, Evaluate and publication examples.