Skip to content

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
→
Domain job or hook
owned by the domain, never a handler
→
Assist engine
rules, model, constraints
↓ stored on the item (ai_reviews) or cached by input
Item detail
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 app or backstage. 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.Untrusted or llm.UntrustedAbout inside 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 assist feature 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 the assist switch 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.