Skip to contents

For IT and quality teams

Source: vignettes/articles/for-it-and-quality.Rmd
for-it-and-quality.Rmd

Someone on your team wants to train a model on your documents. Before you say yes, you will want to know where things run, what is kept, what leaves the building, who decides, and what the record shows afterwards. This page answers those questions, and says plainly what is not there yet.

Where it runs

Everything runs on the machine where R runs: a laptop, a workstation, or a Posit Connect server. The models are open-weight models from Hugging Face, pinned to exact versions, loaded from safetensors files only. The Python side runs in its own environment, built from a lock of pinned packages with hashes (see Install without the internet).

Nothing needs a dragonfarm server. There is no dragonfarm cloud service.

What is kept

All of it sits in one folder, the runs folder:

  • document sets: the text read from your files, cut into chunks, and a search index;
  • training runs: the data used, the settings, the trained adapter, the evaluation;
  • a catalogue: a small database of what happened.

On a laptop the catalogue is a SQLite file in that folder. A team can point everyone at one Postgres database instead, with one setting.

What leaves the machine

Nothing, unless someone chooses a service that is elsewhere:

  • asking Claude to judge or write questions (Anthropic);
  • reading a web page as a document;
  • publishing a model to Hugging Face;
  • a model server on another machine;
  • a free-tier model provider, after a person has opted in, with a daily cap;
  • training on a cloud GPU (Kaggle, Lightning AI), with the user’s own key;
  • checking that a saved key works.

Every one of these goes through one check first. It is written to the record (where, why, how much), and an admin can limit the hosts it may reach, down to none at all. With none, a test tries every one of them and each is refused before anything is sent. Downloading the open models themselves is separate, because it sends no data of yours; a second switch, Offline, stops downloads too, for machines that must not reach the internet at all.

Who decides

A policy says what each automated helper (agent) may do. Training a model, proposing a model version, deleting, and anything that leaves the machine wait for a person. People see these requests in a “Waiting for you” card: approve, and it runs in their name; decline, and it never runs.

Only an admin changes the policy, in the app or from R. Every change is a new version with who made it and why; older versions stay readable.

A trained model becomes a numbered version of a named model only when a person signs it off, with what the approval means (“approved for answering questions on our SOPs”). The policy can require that the signer is not the person who proposed it.

In governed mode, a trained model answers people only once it is an approved version; until then it is refused before it runs. On a server (Posit Connect, or a shared Postgres catalogue) governed mode and the four-eyes sign-off are on unless an admin turns them off; on a single laptop they are off unless switched on. Untrained models are not affected, and a candidate can still be tried and evaluated before anyone signs it off.

What the record shows

The catalogue keeps an entry for each:

  • tool call, with its arguments and a fingerprint of the result;
  • answer from documents, with the exact chunks, the reader version, the model and its pinned version, the settings, every excerpt shown to the model, and the answer;
  • approval request and decision;
  • training run: who created it, the model and its pinned version, a fingerprint of the training rows, the document set behind them, and any personal-data approval;
  • policy version, model version and sign-off;
  • call that left the machine;
  • check for personal data (counts only, never the values).

The database refuses to change or delete these entries. That holds for SQLite and for Postgres.

Checking and reproducing

  • Re-read check. A document set can be read again and compared with what was saved. On our own sets, including ones made by older versions of the reader, they came back byte for byte.
  • Replay. A recorded search, answer or agent task can be run again and compared with the original. When it differs, the record says whether the documents were re-read or the model changed. Eight recorded answers from a 3B model on FDA guidance came back identical: the same excerpts, the same prompt, the same words.
  • Figures. Every answer is checked, without a model, for figures that appear in none of its excerpts and for citations that point nowhere; the app flags them under the answer. On 224 recorded answers it flagged one, a real mistake, and nothing else. It cannot tell whether the words are right.
  • Personal data. A set can be checked for email addresses, phone numbers, US social security numbers, card numbers, and labelled dates of birth and patient or record ids, by fixed patterns. Every hit is listed for a person to judge.
  • Provenance. Monitor downloads a short report for any run: who started it, the base model, its revision and licence, the training rows with fingerprints, which version of which document set they came from (and whether the set has been re-read since), the approvals, the evaluation and the sign-offs.
  • Before deleting. Deleting a run first says what depends on it: runs that continue from it and model versions, with approved ones called out.

Setting it up for a team

On a server such as Posit Connect, three things make it a team tool:

  • One record for everyone. Set the environment variable DRAGONFARM_CATALOG to a Postgres address (postgresql://user:password@host/db). Every person’s answers, approvals and sign-offs then land in one append-only database.
  • People and documents. In Settings, the policy card names the admins (people or sign-in groups) and says who may see which documents, one rule per line: sops | hr-*.pdf | hr keeps the HR files of the set sops for the hr group. Nobody outside it is shown a passage from them.
  • Rules of the house. The same card switches on governed mode, the four-eyes sign-off, and where data may go, down to nowhere.

Each save is a new policy version with who saved it and why. The card refuses a change that would leave its author without admin rights, so no one locks the team out by accident.

Two database roles

The record is append-only because the database refuses changes and deletions. Whoever owns the tables could switch that off, so the app should not own them. Give the database two roles:

  • an owner, used once to create the catalogue and again only when an upgrade changes its layout;
  • an app role, the one in DRAGONFARM_CATALOG, which can read and add rows but not change, delete or switch off anything.
-- as a database administrator
CREATE ROLE dragonfarm_owner LOGIN PASSWORD '...';
CREATE ROLE dragonfarm_app   LOGIN PASSWORD '...';
CREATE DATABASE dragonfarm OWNER dragonfarm_owner;

Then open dragonfarm once with the owner’s address in DRAGONFARM_CATALOG (for example dragonfarm::dragon_app()), which creates the tables, and grant the app role what it needs:

-- as dragonfarm_owner, in the dragonfarm database
GRANT USAGE ON SCHEMA public TO dragonfarm_app;
GRANT SELECT, INSERT ON ALL TABLES IN SCHEMA public TO dragonfarm_app;
GRANT UPDATE ON runs TO dragonfarm_app;          -- a run's state changes
GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO dragonfarm_app;

From then on the app connects as dragonfarm_app. A catalogue that is already set up is left alone, so the app needs no more than this. Tested on Postgres 16: the app role records events, and changing an event, deleting one, or disabling or dropping the protection is refused.

Keys

Keys for outside services are kept in the operating system’s keychain (Windows Credential Manager, macOS Keychain), never in scripts or project files. A key set by an admin in the environment takes precedence.

Not there yet

  • Identity. On a server that signs people in, such as Posit Connect, the record names the signed-in person, the policy can name who may change it, and it can limit documents to groups so that no one else is shown a passage from them; on a laptop it names the operating system user. This was tested with a simulated sign-in, not yet on a real Connect server, and a sign-off is still not an electronic signature in the sense of 21 CFR Part 11.
  • Validation. There is no validation pack yet. Settings can run a qualification report (installation and the controls above, on throwaway data, with evidence for each check), which a validation can build on.
  • Personal data. Names, street addresses and non-US national identifiers are not detected.
  • Planted instructions. Text inside a document can still steer an answer now and then: on our two test sets the 7B was steered on 4 of 12 and 1 of 12 questions. The test sets ship with dragonfarm, so you can measure your own model the same way. No helper can act outside its policy, but answers should be read with their sources.
  • Encryption. Files are protected by the machine’s own disk encryption and permissions; dragonfarm adds none of its own.