Core concepts
Engines, your models, their versions and the prediction lifecycle.
Spavik separates the prediction technology from the model you create for your business. A model has versions that record its successive states.
The engine
An engine is the prediction technology used to build and serve your model. Several customer models can use the same engine, each with its own data and prediction target. The engine determines the supported tasks and the credits charged per prediction.
Read GET /v1/engine-families for the available families and the configured
default. At training, engine_family is optional; the API selects its default
when omitted. A model keeps the same family throughout its lifetime.
GET /v1/engines lists exact engine versions, capabilities, prices, plan
requirements and retirement dates. Choose identifiers from that catalogue:
presage illustrates a family, presage-2 an exact version and presage-latest
a family alias. Use an available identifier for your account.
For predictions, engine_version selects an engine within the model's family.
Omitting it selects the latest active version in that family. Keep the exact
engine returned with each result. Forecast and backtest also accept an
optional family and engine version. See Get started.
Your model
Your model is the reusable prediction object you create for a business task:
for example, predicting customer churn from your customer data. It combines
your prepared examples, the target, the feature schema and the artifacts needed
by the selected engine. It has a model_id that you use for later predictions.
The target is the column you want to predict. Spavik infers the task from it:
| Target contains | Task | What predict returns |
|---|---|---|
Categories (0/1, yes/no, A/B/C) | classification | The class, plus a probability per class |
| Continuous numbers (an amount, a duration) | regression | A numeric value |
Check the returned task, especially for numeric labels. New prediction rows must carry the model's feature columns, with the same preparation as training. Keep the returned identifier and schema; you do not resend the training data with each prediction.
The prepared examples retained by your model are its context data. They belong to the model and its versions; they are not a separate object to manage. The model also keeps the artifacts required by its engine family. Integrating observed outcomes updates this model state.
The version
Training creates the first version of your model. Integrating reported outcomes
with refresh creates a new version under the same model identifier. The active
version serves predictions; earlier versions remain in the version history.
A model version records a state of your data, feature schema, diagnostics and
retained examples, including the engine used to prepare it. This model version
is distinct from the serving engine version. The API may serve it with a newer
active engine in the same family without creating another model version.
Use engine_version to select a serving version and keep the exact returned
engine alongside the model version for each prediction.
n_train and n_sampled_from
n_train is the number of examples retained. If n_sampled_from is larger,
the engine selected a subset of the usable input rows. Review this when
interpreting the model's results.
Prediction and forecasting
Two different operations, not to be confused.
predict | forecast | |
|---|---|---|
| Question asked | "For this row, what value?" | "For the next 7 days, what values?" |
| Needs a model | yes | no |
| Keeps anything | yes, a reusable model | no, nothing |
| Billing | scored rows × serving engine tariff | horizon × serving engine tariff per call, all series included |
Use predict for a label or quantity explained by features known at prediction
time. Use forecast to extend an observed series. A future quantity can also
use regression with features available at the requested horizon; dates alone
do not decide the formulation.
Checking before you commit
Both workflows have a free evaluation that creates no persistent model. The question is whether the engine finds predictive signal it can exploit in the supplied data, measured against the required references.
Before training, evaluate returns structural validation and an engine trial.
Before forecasting, backtest replays history against later observations. It can
include diagnostic predictions with include_backtest_predictions: true.
Both return the API's assessment: a comparison on
the evaluated observations, not a certification of reliability.
Read assessment.status, assessment.metric and assessment.message unchanged.
The statuses are better_than_baseline, not_better_than_baseline, inconclusive
and not_evaluated. See Read an evaluation for their
meaning, metrics and observation counts.
Tabular evaluation uses a random holdout and exposes no temporal or group split controls. It cannot establish performance on future periods or unseen entities when those require separate splits. A forecasting backtest does not evaluate an arbitrary regression model. Compare approaches only under matching protocols.
The feedback loop
This is what separates a frozen model from a service that improves.
Report what actually happened with submit_outcomes. The performance response
compares predictions with matched outcomes. Read observed.assessment with
the task's metrics, matching baselines, evaluated counts and results by version.
Scores that cannot be computed remain null with a reason. Decide whether to refresh
from that evidence and your use case. A deterioration alone does not establish
leakage: investigate feature availability, data drift and evaluation coverage.
See The feedback loop to set it up.
Automatic updates
At creation, auto_update lets incoming outcomes trigger the integration,
without an explicit refresh request. Configure this when creating your
model.
Watch out for one trap: one call to submit_outcomes is one batch. With
auto_update, sending outcomes one at a time triggers one integration per
outcome. Batch them.
Active, archived, deleted
A model is active while it serves predictions and counts against the plan's quota. Archiving it stops both: it keeps its versions, context and reported outcomes, and restoring it puts it back in service, taking a slot again. Keep prediction inputs and results in your application; there is no prediction history endpoint. Deleting it is the only irreversible move: the artefacts leave the engine and the pending outcomes go with them. A training that fails leaves nothing behind.
How is this guide?
Last updated on