Screenings

This page describes the screenings level. It is off until .picker.json has a screenings section. With it on, pick checks every answer for regulated data before the answer leaves. Regulated data means facts about people that a law protects, such as a social security number or a medical record, and one match refuses the whole answer with exit code 13.

Most projects never turn this level on. The guardrails and the login already decide what can be asked for, and the screen is for the few databases that hold records about people.

Do you need this?

Turn it on when a database holds records about people, and someone outside your team could read the transcript. What select returns goes into the assistant's context, and from there into a transcript, a log, and wherever those are sent. The screen sits between the rows and all of that.

Note Do not screen a working database with true just to see what happens. One of the patterns matches any email address, and customer tables are full of them, so every select that returns one will refuse. The detector is working, but on a database nobody meant to screen.

What gets screened

• Three verbs are screened: select, describe and objects. Each one shows something a database holds, while catalogs and doctor report your own file and are not screened.
• The screen checks the answer leaving, never the table. A table may hold clinical notes in row 40,000, and a select that returns none of them is served.
• A query is judged under every scope it read. If you join a screened table to an unscreened one, the whole answer is screened.

A screenings file, and what it gives you

Add a screenings section with a screen object. Each key names what to screen, and each value says which categories to screen for. Here a database is screened, one scope is taken out, and one scope screens for more.

{
  "tools": {
    "servers": {
      "main": { "connect": "env:MAIN_SQL" }
    }
  },
  "guardrails": {
    "servers": {
      "main": {
        "databases": {
          "Sales": {
            "can": ["list", "select", "describe"],
            "scopes": [
              { "object": "ref.*",
                "can": ["list", "select"] },
              { "object": "dbo.Notes",
                "can": ["list", "select"] }
            ]
          }
        }
      }
    }
  },
  "screenings": {
    "screen": {
      "Sales": ["identifiers"],
      "Sales/ref.*": false,
      "Sales/dbo.Notes": ["identifiers", "clinical"]
    }
  }
}

levels
  tools       on, always; settings from C:\github\app\.picker.json
  guardrails  on, from C:\github\app\.picker.json
  screenings  on, from C:\github\app\.picker.json

main  (connect: env:MAIN_SQL)
  Sales: list select describe  [screen: identifiers]
    ref.*: list select  [screen: nothing]
    dbo.Notes: list select  [screen: identifiers clinical]
source: C:\github\app\.picker.json

• The screenings line says on, and names the file that turned it on.
• A [screen: …] marker shows only where a screen is set. A scope with no marker takes its database's screen.
• [screen: nothing] means the screen is off for that scope. It is shown because that scope said so, rather than taking the database's screen.
• No restart is needed. pick reads the file before every call, so the edit applies on the next one.

What a screen key names

A key names a database, or a database and one of its scopes. To name a scope, write the database, a slash, and the scope's object pattern exactly as the scope writes it: "Sales/dbo.Customers" or "Sales/ref.*".

Here is a screen at the tools level, which screens one whole database and leaves every other reachable database alone.

{
  "tools": {
    "servers": { "main": { "connect": "env:MAIN_SQL" } }
  },
  "screenings": {
    "screen": { "Clinic": true }
  }
}

• At the tools level, catalogs shows no screen markers. It lists no databases for an open server, so there is nothing to mark, and the screenings line in the levels block is how you confirm the section was read.
• A key that names no declared database or scope is refused when guardrails are on. A screen that names nothing would screen nothing while seeming to screen something.
• A screen inside a database or a scope is refused. That was the shape of an older version, and the message shows the key to write under screenings instead.
• The local file may not hold a screen. It may hold screenings.models only, as Name the directory shows.

What a screen value says

The value says which categories to screen for. There are three ways to write it, and one that is refused.

A misspelt category is refused too. Otherwise "lgal" would quietly take a screen away, and you would not find out until data left a database you thought was covered.

Note Three words that name a law are refused, and the message says what to write instead. phi, pii and sci each promise more than runs until a model is installed.

The four categories

What the patterns catch

These run inside pick itself, with no model and no second program. They are the same six patterns that fettle runs, and a check in this repository holds the two sets equal.

All six report as one category, identifiers. Each is an identifier with a fixed shape or a label in front of it, and none of them reads clinical language. The patterns run over the rows exactly as they would leave, so an MRN: line inside one notes cell is found.

Carving out a scope

A scope's screen replaces its database's screen. That lets you take the screen off reference data inside a screened database, or have one scope screen for more than the rest.

"screenings": {
  "screen": {
    "Sales": true,
    "Sales/ref.*": false,
    "Sales/dbo.Notes": ["identifiers", "clinical"]
  }
}

• A scope with no key of its own takes its database's screen. If silence meant "screen nothing here", the first database anyone screened would have a hole in it.
• The screen is a check under the scopes. It does not replace them. If you can name a column as sensitive, hide it with a column rule, and the scope removes it every time before the screen sees it. The screen is for what nobody expected, such as a social security number pasted into a notes column.

Prove it refuses

A correct file and a screen that holds are two different claims. Test the second one with made-up rows, such as invented numbers and fake customers, never real ones. Then select something you know holds an identifier.

$ pick select "SELECT name, notes FROM dbo.Intake"
pick: this response would disclose regulated data: 1 in identifiers. The matches are not
quoted, because the refusal would then disclose them. Select fewer columns or rows, or take
the screen off this scope if the content is not regulated.
$ echo $LASTEXITCODE
13

The refusal gives a category and a count, never the value. A refusal that showed the value would write it into the log, which is the harm the screen exists to stop. No rows are trimmed, because an answer with the bad rows quietly removed would look complete and would not be.

Each line below tests one edge:

When it refuses and you did not expect it

Every refusal names its own cause. The first few words say whether something was found or whether the screen could not run, and those are different problems.

Why every one of these refuses

Serving an answer because the check broke is the one outcome the screen must never produce. A burler that will not start, a model that will not load, an answer that will not parse, and a model that runs out of time all refuse with exit 13. So does a pattern that runs out of time on a very large answer, because a served answer must always mean the check ran.

This looks like an outage, and that is the intended trade. A screen that quietly stopped screening would be worse, because nobody would know.

What it costs

What it does not do

The models: the second tier

Note None of this is needed for identifiers. That category runs inside pick with nothing installed. This half covers the other three categories, clinical, legal and scientific, each of which needs a model.

A model here is a trained program that labels the words in a piece of text. It is handed the rows, and answers which words are a person, a date, an identifier, and so on. Setting one up takes five steps: install burler, choose the models, prepare them, lay out the files, and name the directory.

Install burler, the model host

burler is a second program, in its own download. The name is the mill trade's word for the person who picks the faults out of finished cloth before it leaves the mill, and this program's job is the same. It runs the models, and pick talks to it over a pipe.

It is separate because of what the models need. Running them needs ONNX Runtime, a library with native parts for each operating system, while pick stays a single file you copy onto a machine. Putting the models inside it would make every download carry a feature most projects never use.

$dir = "$env:LOCALAPPDATA\Programs\pick"      # wherever pick.exe already is
Expand-Archive burler-X.Y.Z-win-x64.zip -DestinationPath $dir -Force
Get-ChildItem $dir -Recurse | Unblock-File
Get-ChildItem $dir\burler.exe                 # it should be beside pick.exe

tar -xzf burler-X.Y.Z-osx-arm64.tar.gz -C ~/.local/bin
xattr -d com.apple.quarantine ~/.local/bin/burler   # macOS only
ls -l ~/.local/bin/burler                           # beside pick

Downloads come for the same four platforms as pick: win-x64, linux-x64, osx-x64 and osx-arm64. Take the one that matches your pick, because the two run together and must be built for the same machine.

Nothing happens yet. pick does not start burler until a models directory is named in the last step, so installing it early does no harm.

Note Already running fettle with models on this machine? Then burler is installed beside it, and the models directory exists. Put a copy of burler beside pick too, because each program looks only beside itself, and skip to naming the directory. One set of models serves both programs.

Choose the models

You need a model trained to label words, not a base model. BioBERT and SciBERT are base models, which know clinical or scientific language but have not been taught to label anything. What you need is a fine-tune: a base model trained further on a labelling task, such as finding patient details in clinical notes. Look for a model card that names a task, not only a subject, before you download anything.

Any model in the BERT family works, as long as it labels each word (a token classifier) and can be saved as ONNX.

There is no row for identifiers, because it is the pattern tier and takes no model. If you want names of people and places caught, that is a model under one of the three categories above.

Read the licence at the source, every time

Check the licence before you use a model. Some clinical models carry terms that forbid passing them on, and a models directory you share with a colleague is passing them on.

• A licence must exist at the source. No licence anywhere means no right to use it, and wide use is not a licence.
• A copy with no licence tag is not a model with no licence. Model hosts often lose the tag when a model is copied. Go to the project's own repository, read the licence file there, and record that place as the model's source.

These were checked against the model cards and source repositories on 20 August 2026, so check again before you rely on them. Terms change, and this table is a starting point, not legal advice.

Prepare them

burler runs models saved as ONNX, a file format that lets programs other than the one that trained a model run it. Most published models are not in that format yet, so you convert each one once, and Hugging Face's optimum tool does it in one command. The task name token-classification means a model that labels each word.

pip install optimum[onnxruntime]
optimum-cli export onnx --model ORG/CHECKPOINT --task token-classification out/

Quantising afterwards is optional, and worth doing. Quantising stores the model's numbers less precisely, usually in 8 bits instead of 32. The file shrinks to about a quarter and runs several times faster, at a small cost in accuracy. The same tool can do this, and the sizes on this page are for quantised models.

Lay the files out

Make one directory per category, named for the category, under one parent:

screening-models/
  clinical/
    model.onnx
    vocab.txt
    labels.json
    manifest.json
  legal/
    model.onnx
    vocab.txt
    labels.json
    manifest.json

Only the categories you screen need a directory. A category no screen names is never looked for, and models load one at a time, when first needed.

A directory missing any of the first three is refused by name, so you learn which file is missing, not just that something failed.

Write the manifest

The manifest has four fields, and each one is required and may not be empty.

{
  "checkpoint": "dmis-lab/biobert-base-cased-v1.1",
  "revision":   "a1b2c3d",
  "licence":    "Apache-2.0",
  "provenance": "https://github.com/dmis-lab/biobert"
}

• It is required because an optional record is one nobody writes. Six months later, nobody remembers where a model came from or on what terms.
• provenance is where you read the licence. That is often not where you downloaded the file, which is why both are recorded.
• Editing any field clears burler's memory of that model's answers. burler keeps recent answers keyed on the whole manifest, and a changed manifest means the model that judged them may have changed too.

Name the directory

Put the models directory in the local file, under screenings. Where the models sit is a fact about one machine, not about the project, and the local file stays out of source control.

// .picker.local.json, beside .picker.json
{
  "screenings": { "models": "C:/models/screening" }
}

Write the path with forward slashes, and know that a relative path is read from the folder of the file it is written in. If both files name a directory, the local file wins. As before, no restart is needed.

With the directory named, pick catalogs gains a models: line, and pick doctor checks the models directory and burler. The doctor runs those two checks only when screenings are on.

$ pick catalogs
levels
  tools       on, always; settings from C:\github\app\.picker.json
  guardrails  on, from C:\github\app\.picker.json
  screenings  on, from C:\github\app\.picker.json and C:\github\app\.picker.local.json

main  (connect: env:MAIN_SQL)
  Sales: list select describe  [screen: identifiers clinical]
models: C:\models\screening
source: C:\github\app\.picker.json

$ pick doctor
pick X.Y.Z
  ok tools: on, always; settings from C:\github\app\.picker.json
  ok guardrails: on, from C:\github\app\.picker.json
  ok screenings: on, from C:\github\app\.picker.json and C:\github\app\.picker.local.json
  ok configuration: C:\github\app\.picker.json
  ok server main: connects (1 database(s) declared)
  ok models: C:\models\screening
  ok burler: C:\Users\you\AppData\Local\Programs\pick\burler.exe

If burler is not beside pick, the doctor marks that line !! and says where it looked. The message adds that only model screening needs it, so a project that screens identifiers alone can ignore that line.

That is why pick does not check the directory when it reads the file. A file opened on a machine without the models is not broken, and refusing the whole file would take away every database instead of only the screen. The refusal comes at the answer instead, where it can name what could not run.

Running burler by hand

When the model tier is in doubt, run burler yourself. It reads one request per line and answers each one with one line.

$ burler --models C:/models/screening
{"op":"screen","categories":["clinical"],"payload":"the weather was fine"}
{"ok":true,"findings":[]}

Type the request line, press Enter, and read the answer.

An empty findings list means it checked and found nothing, and a missing one is a fault. The two are never written the same way.

More than one model in a category

Give the category a directory of subdirectories instead of one model:

screening-models/
  legal/
    cuad-clauses/       model.onnx, vocab.txt, labels.json, manifest.json
    legalbert-ner/      model.onnx, vocab.txt, labels.json, manifest.json

Their findings add together. A detection by any of them refuses, so a second model can only make the screen stricter. burler looks for model.onnx directly inside the category, and if it is there, that is the one model. If not, it loads every subdirectory that holds one.

A shared models directory

The models directory may be one that other programs or machines use. One set can serve a whole team, or serve fettle and pick side by side, but know what you are trusting when the directory is not yours alone.

• Whoever can write that directory chooses what judges your answers. A model swapped for one that finds nothing turns the second tier off, and nothing would report it.
• A shared directory that goes away is a refusal. Once the directory is named, an unreachable one refuses every model-screened answer, and it will look like an outage.
• Read the manifests you did not write. They are the only record of what those models are, and of the terms they came with.

Where the rest is written down