Quickstart

1. Install

Python 3.13 or newer. The core package pulls only pydantic and pyyaml; the heavy stages sit behind extras. The full pipeline needs detector, gliner, and llm; add pdf to read .pdf inputs.

pip install -U "tacit-deid[detector,gliner,llm]"
python -m spacy download en_core_web_lg     # one time, for Stage 0

Extra	Adds	When
`detector`	Presidio, spaCy, Faker	always, for Stage 0
`llm`	LiteLLM, instructor	always, for the judge loop and extraction
`bedrock`	boto3	your in-boundary model is on Amazon Bedrock
`gliner`	GLiNER	always, for the default model detector (weights download on first use)
`transport`	httpx	`send`, `pull`, `roundtrip`

2. Configure

One file, tacit_deid.yaml, that you own. Credentials are not in it: LiteLLM reads them from the environment or disk.

model: bedrock/us.anthropic.claude-sonnet-4-6        # your in-boundary model id
allowed_endpoint_hosts:                              # fail-closed: only these hosts may be called
  - amazonaws.com
region: us-east-1
boundary_k: 11
detectors: [presidio, gliner-pii-open]               # the default; [presidio] runs without a model

The endpoint gate runs when the LLM client is constructed, before any Protected Health Information (PHI) is sent. A model whose resolved host is not on the list raises EndpointNotAllowedError. See Configuration for every field.

3. Check the input

tacit-deid inspect consult.json --config tacit_deid.yaml

No model client is built and nothing is sent. The report names the format, the size against the cap, anything that would be refused at load, and any keep value that matches nothing. Exit 2 when a record would be refused. See Feeding it transcripts.

4. Run

tacit-deid run consult.json --config tacit_deid.yaml --out artifact.json

On success the artifact is written owner-only and the exit code is 0. On a refusal the command prints REFUSED: <reason> and exits 2; no artifact exists and nothing was sent. By default the run also writes runs/<id>/ with the local ledger and every model call; that folder holds real identifiers and stays inside your boundary (--no-trace skips it). A directory, a JSON Lines file, or a CSV runs as a batch with --out-dir: one engine build, one artifact per record, and an owner-only manifest.json.

5. Send, regenerate, pull

send, pull, and roundtrip read TACIT_API_URL and TACIT_API_KEY from a key file or the environment. The key is an ak_ key from an org you administer.

tacit-deid send artifact.json --key-file .env.local
tacit-deid pull art_... --key-file .env.local --regenerate --wait
tacit-deid roundtrip consult.json --config tacit_deid.yaml --key-file .env.local   # all of it plus the oracle

send re-validates the file against the wire contract first, so a ledger or a transcript can never be sent by mistake. See The Tacit side.

As a library

from tacit_deid import deidentify, load_config, load_inputs
from tacit_deid.cli import build_deps

cfg = load_config("tacit_deid.yaml")
deps = build_deps(cfg)                       # detectors, LLM clients (gate runs here), base rates
[record] = load_inputs("consult.json")

result = deidentify(record.text, deps, cfg.engine_config(), keep=record.keep)
if result.crossed and result.artifact is not None:
    print(result.artifact.model_dump_json(indent=2))
else:
    print("refused:", result.refusal_reason)

build_deps wires one LiteLLMClient for extraction and one LLMJudge for the loop, both behind the same endpoint gate, plus the configured detectors and the base-rate provider. Pass a TraceCollector as on_trace to keep every model call in the returned ledger.

Getting started

How it works

Operating it

Reference

Quickstart

Quickstart

1. Install

2. Configure

3. Check the input

4. Run

5. Send, regenerate, pull

As a library

​Quickstart

​1. Install

​2. Configure

​3. Check the input

​4. Run

​5. Send, regenerate, pull

​As a library

Quickstart

1. Install

2. Configure

3. Check the input

4. Run

5. Send, regenerate, pull

As a library