> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Judgments

> Typed questions kept answered for every document.

export const productName = "Vainona";

A judgment is a definition attached to a namespace. It says what {productName} should know about every document in it. A judgment defined on a prefix such as `acme/prod/*` is a [template](/guides/templates), inherited by every namespace under it.

```json theme={null}
{
  "name": "needs_escalation",
  "type": "bool",
  "question": "Does this ticket require a human to take over from the automated flow?",
  "criteria": "Escalate when the customer is at risk of leaving, mentions legal action, or the automation has failed twice.",
  "context": {"fields": ["state.subject", "state.body", "attributes.plan"], "last_n": {"state.messages": 3}, "max_tokens": 4000},
  "engine": {"name": "jev", "version": "current"},
  "freshness": {"policy": "on_change", "debounce_ms": 0},
  "thresholds": {"escalate": 0.85},
  "activate": true
}
```

## Types

| Type     | Definition                                                                                                       | Answer                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `bool`   | `question` only                                                                                                  | `p`, the probability of yes                                                                       |
| `choice` | `options`: 2 to 254 `{value, description}` entries. {productName} appends `none_of_the_above` as a final option. | `value` (the most likely option), `dist`, and `escape_p` (the probability of `none_of_the_above`) |
| `score`  | `levels`: 2 to 10 ordered `{value, label, description}` entries                                                  | `score` (the probability-weighted mean of the level values) and `dist`                            |

A `bool` answer has no `value`. Booleans come only from named thresholds.

A `bool` judgment can instead ask 2 to 8 narrow yes/no `parts` and combine them with weights fitted on your labels. It is measured on those labels before it answers; see [composite judgments](/guides/composite-judgments).

## Thresholds

Thresholds are named numbers evaluated when an answer is read, and returned as booleans under `answers.{name}.thresholds`. For a `bool`, a threshold is true when `p` is at least the number. For a `score`, it is true when `score` is at least the number. For a `choice`, it names an option and a minimum probability: `"escalate": {"value": "fraud", "gte": 0.7}`. They are always evaluated against the raw fields, never the `calibrated` ones.

Thresholds are settings, not part of a version. Change them with `PATCH /namespaces/{ns}/judgments/{name}`:

```json theme={null}
{"thresholds": {"escalate": 0.79, "review": 0.5}}
```

The `thresholds` you send replace the whole set, so include the ones you want to keep. `{}` removes them all. The change applies at the next read to every answer, including answers already computed, with no recompute and no new version, and is recorded in your audit log. Thresholds given when you create a version replace the current ones when that version becomes active. To pick a threshold from your own outcomes, see [the recommender](/guides/measure-improve-tune#pick-thresholds-with-the-recommender).

## Engine

Every judgment names one engine version, such as `{"name": "jev", "version": "current"}`. `current` runs whichever Jev model the provider serves now, and each answer records the epoch of model behaviour that produced it (`engine_version`, such as `current+2026-09-24.1`). Nothing picks an engine for you, unless you set a namespace's `default_engine`. The version must be `active` in the registry; see [engines](/engines/index).

## Context recipe

`context` says which parts of the document the engine sees. It is the main lever on both cost and accuracy; see [writing a context recipe](/guides/context-recipes).

A recipe can also read other documents: the ones that point at the judged document, such as an account's tickets, or the one it points at, such as an order line's product. See [relations](/concepts/relations).

## Versions

Versions are immutable. Posting a definition with an existing name creates version `n+1`. The first version of a name is active when it is created. A later version stays inactive until you activate it, or you pass `activate: true`.

`POST /namespaces/{ns}/judgments/{name}/activate` with `{"version": 4}` makes version 4 the one new evaluations use. Existing answers keep their `judgment_version` until they are recomputed. If the new version's engine or definition differs from the active one, the call returns `202` with a `shadow` job instead. The job judges a sample of 1,000 documents under the new version and reports the distribution shift, the threshold flips and the cost of recomputing everything. `POST /jobs/{id}/confirm` makes the switch. `"force": true` skips the report and switches at once, and so does `activate: true` on create, except for a [composite](/guides/composite-judgments#activate-it-measured-on-your-labels), which always runs its shadow job. See [changing a question safely](/guides/measure-improve-tune#change-a-question-safely-with-a-shadow-report).

Freshness policy, debounce and thresholds are settings, not part of the definition. Changing them with `PATCH /namespaces/{ns}/judgments/{name}` creates no version. See [choosing a freshness policy](/guides/freshness-policies).

`horizon` is part of the definition: a duration such as `"30d"`, `0s` by default. It says how far ahead a judgment predicts, and each [outcome](/guides/measure-improve-tune#real-world-outcomes-with-a-horizon) is joined to the answer current at its `observed_at` minus the horizon. Changing it creates a version.

`DELETE /namespaces/{ns}/judgments/{name}` deactivates a judgment. Its answers and evaluations are kept. A namespace can have 100 active judgments.

## Backfill

A new judgment has no answers for existing documents. `POST /namespaces/{ns}/judgments/{name}/backfill` without `confirm` returns an estimate and does nothing:

```json theme={null}
{"estimate": {"documents": 87291033, "tokens": 174582066000, "judgment_units": 174582066, "cost_usd": 16041.15, "duration_s": 7793842}}
```

`cost_usd` is what the backfill costs you: its `judgment_units` at the [prices per unit](/pricing#judgments) of the tiers your organization will be in, counting what it has already used this month, the same on every engine. Here each document's context and question come to 2,000 tokens, so 2 units, and the units past the first 100M this month are at the lower second-tier price. `duration_s` is the expected wall-clock time at the current share of the engine's rate limit. Here it is about 90 days on Jev, which is why it is shown next to the cost. With `"confirm": true` the backfill starts as a job, which you can follow, pause, resume or cancel under `/jobs/{id}`. Backfills respect the namespace budget, and a `filters` expression limits a backfill to matching documents.