Inference (v2, Beta)

This guide explains the inference operations on the v2 (rep2) engine: predict, recommend, relate, ranking by context, and explainable results with $why. v2 is in beta; the statistical model is the same family as v1 inference, exposed through the simpler Query2 syntax.

The idea behind Aito is that the same from/where you'd use to filter data is also the evidence for a prediction. You don't train a model per question — you ask the database.

Predict

Point predict at a field and Aito ranks its values by probability given your where evidence:

{
  "from": "products",
  "where": { "name": { "$match": "rye bread" } },
  "predict": "category",
  "select": ["$p", "$value"]
}

Each hit has a $value (a candidate category) and $p (its probability). Results are ordered most-probable first.

Across linked tables

Evidence can come from a linked table using a dotted path, and basedOn projects linked-table fields into the prediction context as extra evidence:

{
  "from": "invoices",
  "where": { "description": "monthly cloud hosting", "processor.company": 11 },
  "basedOn": ["role", "department"],
  "predict": "glCode",
  "select": ["$p", "$value"]
}

Cross-table predict / recommend / relate run end-to-end on v2, and cross-table priors (the dominant accuracy contributor) are on by default. You can also predict the link itself (e.g. predict processor and let the engine draw on the linked employee's attributes), and match into array/multi-value columns with $has (membership), so a tag list or a basket of products is first-class evidence.

Recommend

recommend is predict paired with a goal — rank candidates by how well they achieve a desired outcome, not just by similarity:

{
  "from": "impressions",
  "where": { "user": "john" },
  "recommend": "product",
  "goal": { "click": true },
  "limit": 10
}

This ranks products by P(click | user=john, product), i.e. what John is most likely to actually click — not merely what's popular.

Rank by context

You can rank candidates by the probability of a condition evaluated against the context (from) table, using $context inside orderBy:

{
  "from": "impressions",
  "get": "product",
  "orderBy": { "$p": { "$context": { "click": true } } },
  "select": ["$value", "$p"]
}

"Rank products by P(click | product)". It reuses the recommend machinery — the context condition becomes the goal — so there's no separate scoring path.

Relate

relate returns statistical relations instead of rows — which features move a target, with lift and information-gain style statistics:

{
  "from": "impressions",
  "where": { "click": true },
  "relate": ["product.category"]
}

Use it to discover what's associated with an outcome.

Explainable results — $why

Predictions you can't explain are hard to trust. Add $why to select and every ranked candidate comes back with the factor tree that produced its score. For a collection where color predicts label (red→a, blue→b):

{
  "from": "obs",
  "where": { "color": "red" },
  "predict": "label",
  "select": ["$p", "$value", "$why"]
}

returns, for the top candidate:

{
  "$p": 0.8,
  "$value": "a",
  "$why": {
    "type": "product",
    "factors": [
      { "type": "baseP", "value": 0.5, "proposition": { "label": { "$has": "a" } } },
      { "type": "relatedPropositionLift", "proposition": { "color": "red" }, "value": 1.6 }
    ]
  }
}

Read it back: the base rate for label=a is 0.5, the evidence color=red lifts it by 1.6×, and 0.5 × 1.6 ≈ the predicted 0.8. The explanation isn't a post-hoc approximation — it's the actual arithmetic the engine did.

Group factors. Because group re-expression is on by default (and with config.ai: "high"), a factor may itself be a $group: several correlated features the engine folded into one theme so they contribute a single, redundancy-adjusted lift instead of each casting a near-duplicate vote (see Tuning inference — config.ai below). The tree is still exact arithmetic — a group is one node whose lift already accounts for the correlation among its members — but it reads as a theme ({ "type": "...", "$group": [ … ] }) rather than a flat list of individual features. This is what keeps confidence honest when a record has many overlapping features; it is slightly less literal to skim than per-feature factors.

Probabilities, honestly

A few properties worth knowing:

  • Scores are calibrated probabilities, not arbitrary relevance numbers — a $p of 0.8 means roughly an 80% chance. Calibration is kept honest by support-tempering (on by default): confidence is tempered by the effective statistical support of the evidence, visible as a support-tempering(auto) factor in $why; config.calibrate can additionally fit a residual temperature. See Score Calibration.
  • A $numeric / quantity field contributes via its neighbourhood, so sparse numeric evidence is smoothed rather than memorized (see Schema Design).
  • Unsupported computed columns fail loud (a 4xx), never a silent empty value.

Tuning inference — config.ai

When known features are correlated — brand and model, or several tokens that always co-occur — treating each as independent evidence over-weights the overlap and inflates confidence. config.ai selects how the engine re-expresses the known features before predicting, to correct for that.

v2 defaults to group. Group formation is on out of the box, because real-world evidence is usually correlated and honest confidence on redundant features is the common case. Set config.ai per query to change it:

{
  "from": "products",
  "where": { "brand": "acme", "line": "pro", "color": "red" },
  "predict": "category",
  "config": { "ai": "fast" }
}
config.aiWhat it does
fast (flat)Plain naive Bayes — no re-expression. Cheapest; opt into this only when features are genuinely independent.
v1 (and)Peels clear feature combinations into joint terms (an "and" of co-occurring evidence).
groupGroup formation — themes correlated features into a single group that contributes once.
high (v2) (default)And + group formation. Strong combinations become joint terms; the semi-weak correlated residual is themed into groups. Most robust against correlated-feature overconfidence — the engine default when config.ai is absent.

The default profile (v2 / high) pairs And re-expression with group formation, which detects that several features move together and folds them into one group that contributes a single, calibrated piece of evidence, rather than letting each cast a near-duplicate vote. This directly counters the over-confidence a record with many redundant features would otherwise produce. It composes with config.calibrate (the residual temperature fit); the two are independent knobs. To turn re-expression off entirely, set config.ai: "fast". An unknown profile name is rejected loudly (4xx), never silently ignored.