> ## 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.

# Templates

> Define a judgment once on a namespace prefix, and every tenant under it has it.

A platform with one namespace per tenant usually wants the same judgments in every tenant. A template does that. You define the judgment once, on a namespace prefix, and every namespace under the prefix inherits it. That includes tenants created later. There are no per-tenant calls.

## Create a judgment on a prefix

A template is a namespace path ending in `/*`. Create a judgment there exactly as you would on a namespace:

```text theme={null}
POST /namespaces/acme%2Fprod%2F*/judgments
```

<CodeGroup>
  ```ts TypeScript theme={null}
  await db.namespace("acme/prod/*").judgments.create({
    name: "needs_escalation",
    type: "bool",
    question: "Does this ticket require a human to take over from the automated flow?",
    context: { fields: ["state.subject", "state.body"] },
    engine: { name: "jev", version: "current" },
    freshness: { policy: "on_change" },
    thresholds: { escalate: 0.85 },
  });
  ```

  ```python Python theme={null}
  db.namespace("acme/prod/*").judgments.create(
      name="needs_escalation",
      type="bool",
      question="Does this ticket require a human to take over from the automated flow?",
      context={"fields": ["state.subject", "state.body"]},
      engine={"name": "jev", "version": "current"},
      freshness={"policy": "on_change"},
      thresholds={"escalate": 0.85},
  )
  ```
</CodeGroup>

Send the `*` as it is and each `/` as `%2F`. The SDKs do this for you. The judgment routes work on the prefix path as on a namespace: create, list, get, `PATCH`, delete, activate, backfill, calibration and threshold recommendations.

Every namespace under `acme/prod/` now has `needs_escalation`. A tenant's judgment list and get include it, marked with the template it comes from:

```json theme={null}
{
  "name": "needs_escalation",
  "active_version": 2,
  "freshness": {"policy": "on_change", "debounce_ms": 0},
  "thresholds": {"escalate": 0.79},
  "template": "acme/prod/*",
  "versions": [...]
}
```

## Which template a namespace follows

* **The most specific prefix wins.** Templates do not nest. With templates on `acme/*` and `acme/prod/*`, the namespace `acme/prod/tenant_123` inherits only the judgments of `acme/prod/*`. That stays true even if every judgment on `acme/prod/*` is deactivated.
* **A namespace's own judgment wins.** If a namespace already has a judgment with the template judgment's name, it keeps its own, and does not inherit that one.

`GET /templates` lists your organization's templates, 100 per page, with an optional `prefix`. It is `db.templates.list()` in both SDKs. A template stays listed after its judgments are deactivated. `GET /namespaces` does not list templates. To list the namespaces a template reaches, use `GET /namespaces?prefix=acme/prod/`.

## New and existing tenants

A namespace created after the template's first version is judged in full, from its first write.

A namespace that already existed when you added the template judgment is treated as if you had just created the judgment there. For an `on_change` judgment, documents written from then on are judged, and existing documents wait for a backfill you confirm, because nothing is backfilled without an estimate.

A backfill on the prefix path covers every tenant:

* Without `confirm`, the estimate covers every namespace that follows the template's judgment. It counts up to 100 of them, spread evenly by name, and scales that to all of them, so it can be off when tenant sizes vary a lot. Each namespace's counts are reused for 5 minutes, so an estimate can miss the last few minutes of writes.
* With `"confirm": true`, one job runs the namespaces one at a time. Each stays within its own budget. A namespace whose budget is paused is skipped and its answers stay `stale`, so it does not hold up the rest.

## Change the question for every tenant

Create a new version on the prefix path, then activate it there. You get one [shadow report](/guides/measure-improve-tune#change-a-question-safely-with-a-shadow-report), sampled across the tenants, and the job's `namespace` is the prefix. Confirming it switches every tenant. `force: true` skips the report, as on a namespace.

Tenants always follow the template's active version.

## Tenant overrides

A tenant may override two settings of an inherited judgment: its thresholds and its freshness policy. Use the usual `PATCH` on the tenant's own path:

<CodeGroup>
  ```ts TypeScript theme={null}
  await db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", { thresholds: { escalate: 0.7 } });
  ```

  ```python Python theme={null}
  db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", thresholds={"escalate": 0.7})
  ```
</CodeGroup>

* An override replaces the whole object. A thresholds override replaces the template's whole set, as any threshold `PATCH` does. A freshness override is the whole freshness setting: once a tenant overrides freshness, a later template change to its debounce does not reach that tenant.
* A `PATCH` on the prefix path changes the settings of every tenant that has no override of them.

## Detach

A tenant that needs more than an override can detach the judgment:

```text theme={null}
POST /namespaces/acme%2Fprod%2Ftenant_123/judgments/needs_escalation/detach
```

It is `ns.judgments.detach(name)` in both SDKs. The judgment becomes the tenant's own copy, and it stops following the template.

* It keeps the template's version numbers, up to and including the active version, which stays active.
* It keeps the tenant's effective thresholds and freshness, override or inherited.
* It keeps its answers and evaluations. Nothing is judged again.
* It drops the template's pooled calibration. Its answers have no `calibrated` object until its own nightly fit on the tenant's outcomes.

Detaching a judgment the namespace already owns changes nothing, so a retry is safe.

## What a tenant cannot do

On an inherited judgment, these return `409 conflict`:

* Creating a judgment with the inherited name.
* Activating a version. The tenant follows the template's active version.
* Deleting it. Detach it first.

Detach, outcomes, documents, queries and writes take a namespace, never a prefix.

## Calibration across tenants

Tenants post [outcomes](/guides/measure-improve-tune#post-labelled-examples) on their own namespace paths. Calibration on the prefix pools every tenant's outcomes into one fit per template version and engine epoch, refitted nightly. Every inherited answer uses that pooled fit.

The calibration report and threshold recommendations on the prefix path use the pooled outcomes. On a tenant's path they use that tenant's outcomes.

## What stays per tenant

Answers, evaluations, budgets and billing stay with each tenant's namespace. The limit of 100 active judgments counts a namespace's own judgments only. A template has its own limit of 100.

## In the dashboard

* The **Templates** page lists your templates and each template's tenants.
* A tenant's judgment shows the template it comes from, and marks the settings the tenant overrides.
* **Detach** asks you to confirm before it runs.