Templates

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.

Templates are on the Team plan and above. Below it, creating, changing or activating a judgment, or creating or changing a subscription, on a prefix returns plan_required. After a downgrade takes effect, a template freezes: its tenants keep answering with its active version and its subscriptions keep sending events, and you can still read it, backfill it, delete its judgments and subscriptions and detach tenants, but you can’t change it, and a write that would create a new namespace under it returns plan_required. See plans.

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:

POST /namespaces/acme%2Fprod%2F*/judgments

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 },
});

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},
)

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, threshold recommendations, and recipe suggestions and tuning, which test smaller context recipes on the pooled outcomes. The labelling queue works per namespace: preview, draw and label on each tenant’s path. A prefix path returns invalid_request. 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:

{
  "name": "needs_escalation",
  "active_version": 1,
  "freshness": {"policy": "on_change", "debounce_ms": 0},
  "thresholds": {"escalate": 0.85},
  "outcomes": {},
  "template": "acme/prod/*",
  "overrides": []
}

The get’s versions, every version with its definition, is left out of the example.

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, 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:

await db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", { thresholds: { escalate: 0.7 } });

db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", thresholds={"escalate": 0.7})

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:

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. To give a tenant calibration of its own without leaving the template, use its own fit instead.

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

Subscriptions for every tenant

A subscription created on the prefix path applies to every tenant under it, including tenants created later, with the same rules for which template a tenant follows:

await db.namespace("acme/prod/*").subscriptions.create({
  name: "escalations",
  filters: ["answers.needs_escalation.thresholds.escalate", "Eq", true],
  events: ["entered", "exited"],
  endpoint: endpoint.id,
});

db.namespace("acme/prod/*").subscriptions.create(
    name="escalations",
    filters=("answers.needs_escalation.thresholds.escalate", "Eq", True),
    events=["entered", "exited"],
    endpoint=endpoint["id"],
)

Per tenant. Each tenant keeps its own set of matching documents, and each event names the tenant in namespace and the prefix in subscription.defined_on. A tenant starts evaluating it at its next change, so idle tenants cost nothing; until then it reads syncing there.
Listed with template. A tenant’s subscription list and get include it, marked with the template, and show its status in that tenant. On the prefix path, status, live_at and lag_ms are null.
Managed on the prefix. Change and delete it on the prefix path; a tenant gets 409 conflict. Its query runs on a tenant’s path, over that tenant’s documents.
Its endpoint must cover the whole prefix: an endpoint scoped to acme/prod/ or wider, not one tenant.
The limit. A tenant creates a subscription only while it has fewer than 100, counting its template’s. Creating one on the prefix checks the template’s own count, so subscriptions the template gains later can take a tenant past 100.
Plans. Creating and changing one on a prefix needs the Team plan, like any template change. After a downgrade, existing ones keep sending events, deleting one works on any plan, and a new tenant under the frozen template returns plan_required.

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.
Changing or deleting an inherited subscription. Subscriptions can’t be detached, and creating one with an inherited subscription’s name is invalid_request.

Detach, the labelling queue, a subscription’s query, suggested parts, outcomes, documents, queries and writes take a namespace, never a prefix.

Calibration across tenants

Tenants post outcomes 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. A tenant without a fit of its own reads that pooled fit, so a tenant created today is calibrated from its first answer. Tenants under a non-production prefix, such as acme/staging/, are left out of the pool unless the template is under that prefix too.

Each tenant grows its own fit (Scale)

A tenant’s data can differ from the pool’s: another language, a stricter review team, a different base rate. On the Scale plan, a tenant with enough outcomes of its own in an epoch, 100 with 20 of each kind, also gets its own fit, weighted more heavily as its own outcomes grow (the report shows weight). Below 100 it reads the pool. A tenant’s own fit is used only when it clearly beats the pool on that tenant’s held-out outcomes. The tenant keeps what it would read otherwise (the pooled fit, or raw where the pool does not beat raw) until then. The template’s nightly fit makes every tenant’s fit in the same run, and tenants keep following the template: a new version starts every tenant on that version’s pool again, and there is nothing to detach. Composite judgments keep one pooled combiner for every tenant. Below Scale, every tenant reads the pooled fit. After a downgrade takes effect, the next nightly fit leaves every tenant on the pool again; an upgrade gives tenants their own fits at the next one.

Reports

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, and each epoch’s tenant says what the tenant reads:

{
  "tenant": {
    "applied": "tenant_shrunk",
    "reason": "tenant_better",
    "message": "This tenant's own fit, blended with the template's pool, did best on its held-out outcomes, and clearly better than the pool, so its answers read it.",
    "outcomes": 3000,
    "weight": 0.968,
    "held_out": {"raw_log_loss": 0.61, "pooled_log_loss": 0.55, "tenant_log_loss": 0.42}
  }
}

applied is tenant_shrunk (the tenant’s own fit, blended with the pool’s), pooled or raw. weight is how much the tenant’s own fit counts, rising with its outcomes. reason is tenant_better, pooled_better or raw_better once the tenant has its own fit; too_few_outcomes, awaiting_fit (the next nightly fit makes one) or plan_required before. It is non_production for a tenant under a non-production prefix, which reads the pool but adds nothing to it. The epoch’s stage, held_out, not_fitted and calibrated then describe the fit the tenant reads, measured on its own outcomes. On the prefix path, each epoch’s tenants counts the tenants with outcomes in it, and how many read their own fit, the pool, or raw.

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.
A tenant’s Calibration tab says, per epoch, whether it reads its own fit or the pool, and how much its own outcomes weigh. A template’s says how many tenants read their own fit. Below Scale, both say that every tenant reads the pool, with an upgrade for owners.
Below Team, the Templates page and each template say what templates do and that yours are frozen, with an upgrade for owners. A frozen template’s page still offers backfill; its new versions, activation and settings wait for an upgrade.

Get started

Before you build

Concepts

Guides

Relations

Engines

Reference

Create a judgment on a prefix

Which template a namespace follows

New and existing tenants

Change the question for every tenant

Tenant overrides

Detach

Subscriptions for every tenant

What a tenant cannot do

Calibration across tenants

Each tenant grows its own fit (Scale)

Reports

What stays per tenant

In the dashboard

​Create a judgment on a prefix

​Which template a namespace follows

​New and existing tenants

​Change the question for every tenant

​Tenant overrides

​Detach

​Subscriptions for every tenant

​What a tenant cannot do

​Calibration across tenants

​Each tenant grows its own fit (Scale)

​Reports

​What stays per tenant

​In the dashboard

Create a judgment on a prefix

Which template a namespace follows

New and existing tenants

Change the question for every tenant

Tenant overrides

Detach

Subscriptions for every tenant

What a tenant cannot do

Calibration across tenants

Each tenant grows its own fit (Scale)

Reports

What stays per tenant

In the dashboard