How it works

How the record is built

Ovillo does not let anything into the record on trust. This page explains what the record holds, the rules the code applies to every new item, what the assistant may and may not decide, and how you take a decision back. It is for families who want to know what happens without a click, and for developers.

What the record holds

The record is one encrypted JSON document with a fixed schema. Its main collections:

Collection	What is in it
Documents	One entry per file: name, type, size, hash, a pointer to its encrypted blobs, what reading found, and the patient-check result.
Timeline	Dated events, each with its wording, the original date as written, and its sources.
Trends	Tables of values over time, one per test, with the value as printed and the reference range as printed.
Medicines, allergies	Medicine notes kept in the wording of the document, and allergies.
Picture items	Current state, connections, gaps, conflicts, questions and next steps.
Visits, appointments, tasks	Your own visit notes, saved appointment briefs, and follow-ups.
Proposals	Items waiting for a decision, and the history of decided ones.
Learned tests, decisions, audit	Lab tests the app learned from your documents, the assistant's decisions, and the audit log.

The screens that show this are described in The record.

Provenance on every item

Every item says where it came from, in words you can read on the item itself:

Page {page} · read on this computer, not reviewed: a lab value filed by the lab reader.
Added automatically from {file} · not reviewed: a routine fact the assistant filed.
Decided by the assistant · not reviewed by you: an item the assistant approved from the waiting list.
Patient-entered · reviewed by vault user: something you wrote or approved yourself.

An item also carries the id of the document it cites, the page, and, for assistant items, the model that proposed it. Nothing is ever marked verified by a clinician. Approving an item adds a new entry; it never edits or deletes what was imported.

How new items get in

There are two routes: the lab reader, which works on its own on this Mac, and the assistant, when you have connected one. Both end in one rule: each new item is run through ordered checks, and the first check that fails is the hold. An item that passes every check is filed, marked, and can be undone. Without an assistant, the lab reader still files routine values and everything else waits for you.

Lab values

A value read from a document files itself only if it has a document date it is sure of, a known unit, a clear reading, and is inside its printed reference range. It is held if any of these is true, in this order:

the page prints it about someone else;
it may be from another specimen, such as urine or sweat;
it is far outside its range;
the reading is doubtful: an unknown unit for that test, a jump or reversed range, or a page OCR read poorly with no table to confirm it;
two readers disagree;
the date is a guess;
it is outside its range, or printed as a limit that could not be read.

A value already in the table for that date is skipped, not repeated.

Routine facts from the assistant

When the assistant reads a document, it reports each item through a tool called add_from_document. The code, not the model, decides whether it files itself. Only a new timeline event or a row in an existing trend table can. It files only if every one of these holds:

it cites the document it came from;
the document's text is available to check against;
it changes nothing already recorded, and the document has not already put 25 automatic items in;
a timeline event has a date the app can read ("last year" does not count);
it matches no alarm wording, such as malignancy, suspicion, progression, urgent or a mass (checked in English and Spanish, and deliberately without regard to negation, because a missed alarm costs more than an extra look);
it is not about another person or another specimen, and no value for the same test is already waiting;
it is within range, a trend row belongs to an existing table, and it is no new pattern;
every number in it, and every date, is written in the document's text, and at least three quarters of its words appear in the document, without dropping a "no" or "not".

Items that file this way are marked Added automatically and carry the source document.

Always held

These are held whatever else is true, and the model cannot release them on its own:

medicines and allergies;
anything the assistant frames as a pattern, connection, question, suggestion or follow-up;
the whole-record picture: current state, connections, gaps, conflicts, questions and next steps. A "documented" item needs a quote the app finds in a cited document, a connection says what would show it wrong, and a next step must name a date, a test or a clinician and cannot say to stop a medicine;
anything that would change what is already recorded;
a document held as possibly someone else's;
a lab value held for the reasons above, and new lab tests or unit conversions the app has not been taught.

Without an assistant, everything held waits for you in Review. Delete, export, settings, and moving anything between people stay human-only, always.

The assistant decides held items

With an assistant connected and the Settings switch Let the assistant decide held items on (the default), the assistant can decide what would otherwise wait for you. The code decides what waits; the assistant decides how, item by item.

A fixed list. A run starts from a list made when it starts, by triagePlan: held documents first, then held items, at most 40. Nothing raised during the run joins it, and items are handed over in batches of eight.
Read and decide only. In a run the assistant has read tools and two decision tools, decide_held_item (approve or reject) and decide_document_owner (this person's, or someone else's). It cannot raise an item and then approve it, and has no screen tools.
A reason with a quote. Every decision needs a reason, and the app checks it against the cited page.
Marked. Each decision is labelled Decided by the assistant · not reviewed by you, shown in Review with its reason and source, and written to the audit log.

A run starts after each review batch, after the picture pass, and from the Review button Let the assistant decide what's waiting.

What a quote must do

Approving needs a quote copied exactly from the cited page. Code finds it on the page, then checks that it carries the item (approveCheck and carriesItem in src/record.mjs):

a lab value: a line that prints the value next to the name of its test;
a medicine or allergy: the quote names it, and every number it states appears;
a learned test: the name as the page prints it;
anything else: every number appears, and at least half of the item's own content words are in the quote.

An item that cites no source can be left out, never approved. Naming the document is enough only to leave something out.

Never handed to the assistant

The family decides these, and the record refuses an assistant decision on them even if one were attempted:

your own visit notes;
anything citing a document held as someone else's;
a lab value held as maybe another specimen, or as maybe someone else's, whatever its first hold reason;
a lab value the cited page prints only on a line, or under a label line such as "Madre:", naming someone else;
anything whose cited page the injection scanner flags (see Privacy and security).

Documents held as possibly someone else's are handled narrowly. The assistant may release one only when it was held in the gentle "hard to read" state (a damaged scan of her own first name, no birth-date mismatch), on a quote that names the patient with her surnames. A document naming someone else, or a different birth date, can only be decided "someone else's" by the assistant, which keeps it held and out of her record, or left for you. Only you can say it is hers. Releasing a document teaches no name, and nothing is ever moved to another person.

Important. These checks limit the risk, they do not remove it. A model can still approve a value that the page really prints but that is wrong for this person, or release a document on a genuine quote. Turn the switch off to approve everything by hand, and look at the decisions in Review.

Marking and undo

Automatic items. Each has an Undo button. It removes the item; a lab table the reader created is removed too, unless a held value is waiting to go into it.
Assistant decisions. Each has Undo, and a run has Undo all from this run. Undo puts the item back to waiting, and removes what it filed. A released document is held again, and anything filed from it automatically is removed.
Until you act. A decision can be undone only until you act on what it filed: marking the medicine taken or stopped, completing or reopening the follow-up, removing the allergy, or forgetting a learned test. After that it stays, and says why. Undo all from this run undoes what it can and lists the rest.
Yours from then on. An item you undo is never handed to the assistant again. It waits for you.
The switch. Turning Let the assistant decide held items off stops a run between batches, and the record refuses any further assistant decision.

The audit log

The record keeps an audit log of what changed and who did it: documents added, lab values filed, automatic updates applied and undone, proposals raised, and assistant decisions and their undoing. Each entry has the action, the time, the item and an origin: you (vault-user) or the assistant side (agent). In normal use it is only added to. Like the rest of the record, it is encrypted and stays on your Mac.

Something unclear or out of date? Tell us on GitHub.