scan_directory_tool
Scan a local dataset or model directory to detect PII and secrets before publishing. Get a clear report of what personal data it contains to avoid leaks.
Instructions
Recursively scan a local dataset or model directory for PII and secrets before you publish it.
Call this before releasing, uploading, or sharing a dataset/model
directory whenever you need to know what personal data it contains --
it is the read-only first step agents should take ahead of
redact_directory_tool or package_release_tool, and the right
choice on its own when you only need a report, not a redacted copy.
Do not call it on directories you do not have read access to, or
expect it to catch anything beyond what Presidio's own recognizers
detect (no custom regex or heuristics are layered on top).
path must be a directory (or single file) that already exists on
disk and is readable by the current process; it walks CSV, JSON/
JSONL, and plain-text files under it. This call is read-only: it
never writes, moves, or deletes anything, makes no network requests
(Presidio and spaCy run entirely locally), and is safe to call
repeatedly -- re-running it against an unchanged directory returns
the same findings. On a missing path, or any internal failure, it
returns {"error": ..., "error_type": ...} instead of raising or
crashing the server -- check for an error key before reading
findings.
spacy_model selects the spaCy model Presidio's NLP engine uses
(defaults to en_core_web_sm; must already be installed via
python -m spacy download <model>, this tool does not install
one). score_threshold (0.0-1.0, default 0.35) drops any finding
below that Presidio confidence score -- raise it to cut false
positives, lower it to widen recall. Example calls:
scan_directory_tool(path="./data"),
scan_directory_tool(path="./data", score_threshold=0.5),
scan_directory_tool(path="./models/card-dir", spacy_model="en_core_web_lg").
Returns a JSON object with root_path, files_scanned,
files_skipped, findings (a list of objects each with
file_path, entity_type, start/end offsets, score,
text_preview, line_number, field_name, detector),
entity_counts (per-type totals), total_findings,
detector_name, and language. For flag-level detail beyond this
docstring, run the equivalent CLI form: releaseguard scan --help.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| spacy_model | No | ||
| score_threshold | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||