Power User Guide
Running CasePrepd from the command line, batch processing, and the settings worth knowing about. For everyday GUI use, see the main User Guide.
The Command-Line Interface
CasePrepd ships with a headless CLI that runs the full pipeline (extraction → preprocessing → vocabulary → semantic indexing → key excerpts) without launching the GUI. Useful when you want to:
- Batch-process many cases overnight without babysitting the GUI.
- Script a workflow that combines CasePrepd with other tools (spreadsheets, court-reporting software, etc.).
- Pipe machine-readable JSON output into something else.
- Run from a remote desktop / server without the GUI overhead.
The CLI uses the same code and the same on-device AI models as the GUI. Privacy guarantees are identical — no network calls.
Quick Examples
The CLI lives in the installed app folder. From an installed CasePrepd,
you can either invoke CasePrepd.exe with CLI flags (if you
built that wrapper) or use the Python entry point from a developer
install:
python -m src.cli --input docs/ --output out/
That single command runs the full pipeline on every supported file in
docs/ and writes vocabulary, key excerpts, and a combined
report to out/.
Vocabulary only, specific files
python -m src.cli --input case1.pdf case2.pdf --output out/ --only vocab
Run a single search, JSON output
python -m src.cli --input docs/ --output out/ \
--query "knee injury timeline" --format json
Both human and machine outputs
python -m src.cli --input docs/ --output out/ --format both
Flag Reference
| Flag | Required? | Description |
|---|---|---|
--input |
Yes | One or more files, or a single directory (recursively scanned for supported types). |
--output |
Yes | Directory where outputs are written. Created if it doesn't exist. |
--only |
No | Repeatable. Limit outputs to vocab, excerpts, and/or combined. Default: all three. |
--query |
No | Run a single semantic search with this phrase. Default: no search. |
--format |
No | human (default), json, or both. |
--verbose / -v |
No | Enable debug-level logging to stderr. |
Supported input file types: .pdf, .docx,
.txt, .rtf, .png, .jpg,
.jpeg.
Output Files
What gets written depends on which --only filters and
--format you pass:
| File | When written | Format |
|---|---|---|
vocabulary.docx |
--only vocab (or default), if vocab not empty |
Word |
key_excerpts.txt |
--only excerpts (or default) |
Plain text |
combined.docx |
--only combined (or default) |
Word |
vocabulary.json |
--format json/both, if vocab not empty |
JSON |
excerpts.json |
--format json/both |
JSON |
search.json |
--format json/both and --query given |
JSON |
First run is slow because the embedding models have to load from disk. Subsequent runs in the same process reuse the loaded models. If you're batch-processing many cases, run them all in a single CLI invocation rather than one per case.
Debug Mode (Developers Only)
Running the GUI with --debug routes vocabulary feedback to
the developer training CSV instead of your personal one. The window
title shows CasePrepd [DEBUG] so it's obvious which mode
you're in.
CasePrepd.exe --debug
Use this only if you're contributing training data to the shipped developer baseline. Regular users should never use this flag — you'd be polluting the baseline with case-specific ratings that don't generalize.
Two separate CSV files are involved:
config/default_feedback.csv— the developer baseline that ships with the installer.%APPDATA%\CasePrepd\feedback\user_feedback.csv— your personal ratings.
At training time, both are combined with source-based weighting: when you have few ratings, the developer baseline dominates; as you add your own ratings, your preferences gradually take over.
Logs and Data Folders
Useful when something goes wrong, or when you want to back up your settings and saved corpora:
| Path | What's in it |
|---|---|
%APPDATA%\CasePrepd\logs\caseprepd.log |
Structured rolling log. The main source of truth when debugging. |
%APPDATA%\CasePrepd\logs\main_log_YYYYMMDD_HHMMSS.txt |
Captured stdout/stderr per session. Useful for crashes that happen before logging is fully set up. |
%APPDATA%\CasePrepd\crash.log |
Import-time failures (very early crashes that never reach the GUI). |
%APPDATA%\CasePrepd\config\user_preferences.json |
All your settings. Safe to back up or copy between machines. |
%APPDATA%\CasePrepd\feedback\user_feedback.csv |
Your Keep/Skip vocabulary ratings — the model's training data. Worth backing up. |
%APPDATA%\CasePrepd\corpus\ |
Your saved corpora (one folder per corpus). Worth backing up. |
To get to %APPDATA%\CasePrepd quickly: open File Explorer,
paste that string into the address bar, hit Enter.
Settings Worth Tweaking
Settings → opens a dialog with dozens of tunables. Most defaults are reasonable. These are the ones that meaningfully change output quality or performance.
Vocabulary → Occurrence Floor
Minimum number of times a term must appear before it's eligible for the vocabulary list. Default catches single-mention rarities while filtering OCR noise. Bump up (3–5) for huge document sets where the list is too long; drop to 1 if you're worried about missing something rare in a small case.
Vocabulary → Exception Score
Terms with a quality score above this threshold bypass the occurrence floor. Useful for: a key witness mentioned only twice still shows up because the score is high enough.
Export → Search relevance floor
Minimum relevance score (0–1) for a search result to be included in an export. Doesn't affect what you see in the Search tab, only what ends up in exported reports.
There's a separate, non-UI threshold called
retrieval_relevance_gate (default 0.50) that controls
when the Search tab gives up and shows
"No relevant excerpts found in documents." Editable in
%APPDATA%\CasePrepd\config\user_preferences.json.
Key Excerpts — Auto-Scaled
There's no manual excerpt-count setting. The number of excerpts
auto-scales with document length (roughly 1 per 5 pages, capped at
5–15 total). Power users can adjust the cap by editing
user_preferences.json.
Text Preprocessing toggles
Each toggle controls a cleanup step (page-number stripping, header/footer removal, line-number stripping, etc.). All on by default, which is right for transcripts. If you're processing unusual document types where cleanup is misfiring, you can turn individual steps off.
Back to Basics
The everyday GUI features are covered in the main User Guide: the four tabs, the Vocabulary table, the Corpus feature, search phrasing tips, and common troubleshooting.