Usage walkthrough

Numbered examples cover the main flows (rust/examples/, python/examples/). Run the Rust examples from rust/.

#	Flow	When to use it	Rust	Python
01	Basic scan	One-off, blocking scan of a single text	cargo run --example 01_basic_scan	python python/examples/01_basic_scan.py
02	Enqueue / consume	Many texts, async, one shared result queue	cargo run --example 02_enqueue_consume	python python/examples/02_enqueue_consume.py
03	L2 → L3 promotion	Heavy ONNX model runs only when L2 promotes	cargo run --example 03_l2_l3_promotion	python python/examples/03_l2_l3_promotion.py
04	Execution gates	Turn levels/models on or off per request	cargo run --example 04_execution_gates	python python/examples/04_execution_gates.py
05	Dynamic PII	Runtime GLiNER labels + evidence spans	cargo run --example 05_dynamic_pii	python python/examples/05_dynamic_pii.py
06	Unified L3 speedup	Compare two promoted Dedicated models with one coalesced Multi inference	cargo run --release --example 06_multi_l3_speedup	python python/examples/06_multi_l3_speedup.py
07	Contextual gates (Rust) / multi-head L2 validation (Python)	Gate pipelines on metadata and other results; run all seven L2 classifiers on real unified-v3 Val rows	cargo run --example 07_contextual_gates	python python/examples/07_multitask_val_l2.py
08	L3 pipeline policies	Configure clustering, aggregation, progress, and early exit by logical head	cargo run --example 08_l3_pipeline_policies	python python/examples/08_l3_pipeline_policies.py
09	Caching	Compare memory-only, persistent async, write-through, and cache metadata	cargo run --example 09_caching -- async	python python/examples/09_caching.py /tmp/patronus-cache.redb
10	Normalize text	Normalize text before scanning or before using it directly	cargo run --example 10_normalize_text	python python/examples/10_normalize_text.py
11	L1 PII/DLP latency	Release-mode latency of native PII and DLP on short, 4 KiB and 100 KiB inputs	cargo run --release --example 11_l1_pii_dlp_latency	—
12	L1 PII fixture eval	Span-level evaluation of native PII against a JSONL fixture	cargo run --example 12_l1_pii_fixture_eval	—
13	L1 golden eval	Check native PII/DLP against the golden suites (pii, dlp or all)	cargo run --example 13_l1_golden_eval -- all	—
14	Shell commands	shell_command (Cat) with user Cedar policies next to PII, DLP and injection	cargo run --example 14_shell_command	—

Examples 01, 02, 04, 10, 11, 12 and 13 run fully offline (download_files=false, native L1 + cached L2). Examples 03, 05, 06, 07, 08, 09 and 14 need model assets and will print a warmup error if they are missing.

Ark Core has its own example, ark-core/examples/core_scanner.rs: one Core Scanner for PII, DLP, injection (rules + Wolf) and Cat shell_verdict (cargo run -p patronus-ark-core --features download --example core_scanner). See Ark Core.

01 — Basic scan

Build a gateway for a set of categories and call scan_all. You get one result per configured pipeline, each with category, class_name, confidence, level, and model. Best for simple, synchronous checks.

02 — Enqueue / consume

enqueue(text) returns a request id immediately and does the work on a background worker. consume_next_event drains a single shared queue that carries results for every request, so a fast L2 result is never blocked behind another request waiting on L3. Correlate each event by request_id; exactly one terminal finished event follows all results for a request.

03 — L2 → L3 promotion

With max_level = L3, an NTDB L2 classifier can promote a scan to the full ONNX transformer. The queue first publishes the L2 fallback result, then the final L3 result — both under the same request_id. Configured L3 models are held resident in RAM and evicted only after the idle TTL (PATRONUS_L3_TTL_SECS); set it to -1 to keep loaded sessions resident.

04 — Execution gates

ScanGateMatrix (Rust) / an execution_gates dict (Python) decides which levels and which individual models run. Set a default with set_execution_gates, or pass a gate per request to enqueue. max_level remains the hard upper bound.

05 — Dynamic PII

dynamic-pii is an L3-only GLiNER pipeline. Choose entity labels at runtime, gate it on another pipeline's result (e.g. run only when injection flags the text), and read first-class evidence_spans with byte- and char-accurate offsets. See the pipeline design in Models & the NTDB format and the dynamic PII configuration.

06 — Unified L3 speedup

The same cache-unique text promotes both Injection and Sensitive Document to L3. Dedicated executes two L3 models; Multi returns both logical head results from one shared physical_job_id. Each strategy runs in a fresh process, L3 sessions are materialized before timing, and the example prints median and mean end-to-end latency plus the measured speedup.

07 — Multi-head L2 validation / contextual gates

Python (07_multitask_val_l2.py) runs all seven L2 NTDB classifiers on real unified-v3 validation rows and reports their per-head agreement — a fast way to sanity-check the L2 packages without invoking L3. The Rust example in slot 07 is a separate contextual-gates demo (07_contextual_gates.rs), documented under Conditional gates.

08 — L3 pipeline policies

Tune L3 execution per logical head and per request. The example turns on request-wide progress reporting and sets per-pipeline policies — injection uses representative clustering with an any_positive_or_highest aggregation and request-wide early exit, tool_class uses verify_representative — then adds a conditional l3_policy override that applies only when routing classified the text as a code request. See the L3 worker policy.

09 — Caching

Runs the same input twice and prints cache metadata. The Python example also shows the early partial Dynamic PII result event. See Configure and understand caching for the exact, similarity, Dynamic PII, storage-mode, and latency breakdown.

10–13 — Normalization and L1 checks

10_normalize_text shows the text normalization step on its own. 11–13 are Rust-only L1 tools: a release-mode PII/DLP latency run, a span-level PII fixture evaluation, and the golden suite check. See Normalize text before scanning.

14 — Shell commands

The shell_command category (Cat) next to PII, DLP and injection, with user .cedar policies set through set_shell_command_policy_config. The patronus.verdict/1 document is in layers[0].details["verdict"]. See Check shell commands.