Documentation · Advanced

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:

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:

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.