Assist layer¶
Assist is the one place model suggestions come from. The member app uses it to resolve places from captured links, and Backstage uses it to prepare review suggestions and translation drafts. This page is the system view for anyone adding a task or wondering why a suggestion looks the way it does. Code-level detail is in Assist service.
Mental model¶
Domain event
report filed, photo submitted, notice saved, link captured
report filed, photo submitted, notice saved, link captured
→
Domain job or hook
owned by the domain, never a handler
owned by the domain, never a handler
→
Assist engine
rules, model, constraints
rules, model, constraints
↓ stored on the item (ai_reviews) or cached by input
Item detail
staff read the suggestion with the item
staff read the suggestion with the item
- Nothing calls assist directly. No public or staff endpoint runs a task. A task runs from an integration: an async job, a save hook or a domain's own use case. Results are only read back as part of the item they belong to.
- Two audiences. Every task is registered as
apporbackstage. A domain holds a runner scoped to its audience, so a Backstage task cannot run from app code. Backstage tasks run only from Backstage-owned jobs and hooks, and a layout test enforces it. - Rules first, model second. Deterministic checks decide or constrain before the model runs and again after it answers. The model fills only what the rules leave open, and its answer can never override a hard rule.
- Closed vocabularies. Outputs are enums chosen from the task's registry entry, plus one short rationale. An unknown value is rejected and retried once, then the item stores "no suggestion".
- Assist suggests, people decide. Nothing is applied, sent or published by assist. Translations fill the editor for review and suggestions sit beside the evidence.
Determinism¶
The same input and prompt version reproduce the same stored result.
| Lever | How |
|---|---|
| Sampling | Temperature 0, JSON mode, top_p 1 and a seed derived from the input hash |
| Prompt | Versioned, with few-shot exemplars taken from the eval fixture, and a test that fails when the prompt, the fields or any rule changes without a new version |
| Cache | An identical input hash and prompt version returns the stored result and makes no call |
| Confidence | A fixed bucket (high, medium, low) from the model's own number and the rule signals, never the model's number alone |
| Record | Every result stores the task, prompt version, model, input hash, rules that fired and confidence |
Safety¶
- Member text is masked through
llm.Untrustedorllm.UntrustedAboutinside each task's renderer, so a caller cannot forget it. - A child safety report is never sent, and neither is any content that a deterministic check flags as possibly concerning a child, whatever reason the reporter picked. A rule stores a fixed "needs a person" record instead, and the content does not reach the prompt or the hash.
- Names, handles, emails and phone numbers of the members involved are masked in every prompt, on top of escaping the text. Pattern matching is best effort, so reviewed text is still treated as leaving for an external model.
- One
assistfeature switch (Backstage, with a reason, audited) turns every task off at once. It is separate from the daily token budgets, one for each model, which stop that model for the rest of the UTC day. A budget whose counter cannot be read stops the model too, and theassistswitch reads as off until its stored value has loaded. - Backstage review pictures are not sent. The transport is text only, so a photo review works from the place, the caption and the platform's own checks, and says so in its output.
Where to read next¶
- Tasks, ports, config, evals and how to add a task: Assist service
- Where suggestions appear for staff: Backstage
- Help article suggestions for members: Help service