Helpers: diagram descriptions and "explain simply"
From Zacess main at 2bc7be2. Edit this page on GitHub
Optional helpers that describe a diagram or explain a block more simply. They follow the rules in
"AI, last and labelled" in our privacy commitments by construction. The code is in
crates/zacess-core/src/assist.
The rules, as built
| Rule | How the code keeps it |
|---|---|
| The original is the source of truth | A helper's result is an annotation beside the block, never a change to it. The annotation keeps a copy of the block's text. Exports render the original first with the help after it |
| Optional and off by default | The policy starts with everything off. Nothing runs until the person turns helpers on |
| On-device first, cloud only in the paid tier | Device helpers are tried before cloud ones. A cloud helper runs only when the person has allowed the cloud and has the paid tier; otherwise the assistant says what it needs and offers the alternative |
| Never where a mistake could mislead without the original shown | An equation is never rewritten: its "simple explanation" is its exact natural reading. A simplified text that changes any number, unit or symbol is refused. The original is always alongside |
| Always labelled | Every annotation carries who made it, which model if any, where it ran and when. Exports show and announce the label: "Simpler explanation generated by rule-based simplifier on this device, not part of the original" |
The helpers that ship with the core
Neither uses a model, so each says exactly what it is.
- Rule-based simplifier (device): splits long sentences at clause boundaries, swaps common academic words for plainer ones (therefore to so, approximately to about, requires to needs) and leaves every number, unit and symbol untouched.
- Diagram text reader (device): runs the OCR engine on the image and reports the text it can read, line by line, then says plainly that how the parts connect still needs a person. It never guesses what a picture shows.
Platform shells add on-device models (Apple Foundation Models, Gemini Nano) and the paid tier adds
cloud models behind the same Helper trait. The assistant's choice and the labelling do not change.
Outcomes
Asking for help gives one of: the annotation that was added; helpers are off; the cloud is needed, with the reason and an alternative; nothing to work on (for example an image with no file); or a failure with its message. The interface shows these as they are rather than hiding them.
In the document
Annotations are stored on the document (see the document model)
and can be removed one by one. The HTML and EPUB exports render each as an <aside role="note">
beside its block, with the label as its accessible name.