# ocrtech CLI reference Moved verbatim from the README on 2026-09-24. Host addresses in the remote examples are historical; use the `k2` SSH alias. Install the package first (see the README). ## CLI ```bash ocrtech prepare-data labels.csv --out data/manifests --image-field image_path --text-field text ocrtech prepare-data labels.csv --out data/manifests --image-field image_path --text-field text --skip-invalid ocrtech prepare-data gauravgiri/nepali-ocr-dataset --hf --split train --limit 100 --out data/manifests ocrtech prepare-data prashant0919/nepali-synthetic-ocr-lines --hf --split train --limit 100 --out data/manifests ocrtech prepare-data nvidia/OCR-Synthetic-Multilingual-v1 --hf --hf-subset en --split test --limit 1000 --out data/manifests-english-test ocrtech merge-manifests data/manifests/gauravgiri__nepali-ocr-dataset-train.jsonl data/manifests/prashant0919__nepali-synthetic-ocr-lines-train.jsonl --out data/manifests/nepali-mixed-all.jsonl ocrtech audit-manifest data/manifests/labels-train.jsonl --require-slice nepali --require-slice english ocrtech split-manifest data/manifests/labels-train.jsonl --out data/splits --eval-ratio 0.15 ocrtech rebalance-manifest data/splits/train.jsonl --out data/splits/train-rebalanced.jsonl --slice english --slice nepali ocrtech audit-recognizer-corpus --train-manifest data/splits/train-rebalanced.jsonl --eval-manifest data/splits/eval.jsonl --out outputs/recognizer-corpus-audit ocrtech build-recognizer-corpus data/manifests/english-lines.jsonl data/manifests/nepali-lines.jsonl data/manifests/mixed-crops.jsonl --out data/splits/recognizer-train-balanced.jsonl --target-latin-only 200 --target-devanagari-only 200 --target-mixed 100 --target-real 100 --target-synthetic 100 ocrtech materialize-references data/splits/eval.jsonl --out data/references --rewritten-manifest data/splits/eval-with-refs.jsonl ocrtech create-eval-pack --out data/eval-pack --input-format image --degradation clean --degradation scan ocrtech create-eval-pack --out data/eval-pack-table-figure-dev-v1 --input-format image --template table-ledger --template figure-caption --count-per-template 8 --variant-offset 100 --degradation clean --degradation scan --degradation blur --degradation low_contrast --degradation skew ocrtech audit-eval-pack data/eval-pack/manifests/ocrtech-eval-pack.jsonl --require-claim-ready ocrtech train-recognizer --train-manifest data/splits/train.jsonl --eval-manifest data/splits/eval.jsonl --out runs/recognizer ocrtech train-recognizer --backend hf-vision-encoder-decoder --base-model microsoft/trocr-small-printed --train-manifest data/splits/train.jsonl --eval-manifest data/splits/eval.jsonl --out runs/hf-recognizer ocrtech bundle-recognizer-training --recipe-dir runs/recognizer --train-manifest data/splits/train-rebalanced.jsonl --eval-manifest data/splits/eval.jsonl --out runs/recognizer-training-bundle --require-corpus-audit ocrtech export-recognizer --training-config runs/recognizer/paddle_recognizer.yml --checkpoint runs/recognizer/checkpoints/best_accuracy --out runs/recognizer/export ocrtech package-recognizer --inference-dir runs/recognizer/export/inference --dictionary runs/recognizer/nep_eng_dict.txt --out runs/recognizer/package --model-id ocrtech-nep-eng-rec-v1 --train-manifest data/splits/train.jsonl --eval-manifest data/splits/eval.jsonl --training-summary runs/recognizer/recognizer-training-summary.json --admission-validation-report outputs/validation-next-recognizer-hard50/validation.json ocrtech package-hf-recognizer --model-dir runs/hf-recognizer/final-model --out runs/hf-recognizer/package --model-id ocrtech-hf-nep-eng-rec-v1 --base-model microsoft/trocr-small-printed --train-manifest data/splits/train.jsonl --eval-manifest data/splits/eval.jsonl --training-summary runs/hf-recognizer/recognizer-training-summary.json --admission-validation-report outputs/validation-next-recognizer-hard50/validation.json ocrtech train-corrector --clean-manifest data/splits/train.jsonl --out runs/corrector ocrtech train-corrector --hf-dataset cfilt/RoundTripOCR-nepali --hf-split train --limit 1000 --out runs/corrector-cfilt ocrtech audit-model runs/recognizer/package/model-card.json ocrtech audit-remote-host --host 100.97.238.103 --user k2 --password-env OCRTECH_REMOTE_PASSWORD --workdir '~/ocr-tech' --require-path '~/ocr-tech' --min-free-gb 20 --require-paddle-training --out outputs/remote-audit ocrtech bootstrap-remote-host --host 100.97.238.103 --user k2 --password-env OCRTECH_REMOTE_PASSWORD --workdir '~/ocr-tech' --out outputs/remote-bootstrap ocrtech sync-remote-workspace --host 100.97.238.103 --user k2 --password-env OCRTECH_REMOTE_PASSWORD --local-root . --remote-workdir '~/ocr-tech' --exclude .venv --exclude outputs --exclude runs --out outputs/remote-sync ocrtech preflight-claim --eval-manifest data/eval-pack/manifests/ocrtech-eval-pack.jsonl --references-dir data/eval-pack/references --baselines candidate,tesseract,stock-paddle --candidate-model-config runs/recognizer/package/model-card.json --fallback-model-config runs/vlm-fallback/package/model-card.json --train-manifest data/splits/train.jsonl --out outputs/preflight ocrtech parse-doc examples/sample-page.txt --out outputs/sample --engine sidecar ocrtech parse-doc page.png --out outputs/page --engine candidate --model-config runs/recognizer/package/model-card.json --fallback-model-config runs/vlm-fallback/package/model-card.json ocrtech benchmark examples/sample-page.txt --out outputs/bench --baselines ours --candidate-model-config runs/recognizer/package/model-card.json --fallback-model-config runs/vlm-fallback/package/model-card.json ocrtech summarize-benchmark --benchmark-report outputs/bench/report.json --out outputs/bench-summary --candidate ours --baseline tesseract --metric cer ocrtech benchmark-error-analysis --benchmark-report outputs/bench/report.json --out outputs/bench-error-analysis --system surya --baseline tesseract --metric cer ocrtech export-failure-manifest --source-manifest data/splits/eval.jsonl --top-failures outputs/bench-error-analysis/top-failures.json --out data/splits/eval-hard.jsonl --split hard_eval ocrtech recognizer-admission-decision --validation-report outputs/validation-next-recognizer-hard50/validation.json --out outputs/recognizer-admission-next ocrtech paper-benchmark-table --summary outputs/paper-claimpack-summary-tesseract/summary.json --summary outputs/paper-claimpack-summary-surya/summary.json --summary outputs/paper-claimpack-summary-stock-paddle/summary.json --out outputs/paper-claimpack-table --system candidate --system surya --system tesseract --system stock-paddle --label 'candidate=Candidate' --label 'surya=Surya' --label 'tesseract=Tesseract' --label 'stock-paddle=Stock Paddle' --source-preference 'candidate=outputs/paper-claimpack-summary-tesseract/summary.json' --source-preference 'tesseract=outputs/paper-claimpack-summary-tesseract/summary.json' --source-preference 'surya=outputs/paper-claimpack-summary-surya/summary.json' --source-preference 'stock-paddle=outputs/paper-claimpack-summary-stock-paddle/summary.json' --metric cer --metric table_cell_f1 --metric reading_order_pair_accuracy --metric latency_seconds ocrtech calibrate-quality-router --experiment-report outputs/calibration-experiment/experiment.json --out outputs/quality-router-calibration --model-id ocrtech-tesseract-quality-router --primary-engine tesseract --secondary-engine tesseract --primary-engine-kwarg 'language=nep+eng' --primary-engine-kwarg 'psm=6' --secondary-engine-kwarg 'language=nep+eng' --secondary-engine-kwarg 'psm=13' ocrtech calibrate-script-router --experiment-report outputs/script-calibration/experiment.json --out outputs/script-router-calibration --model-id ocrtech-tesseract-surya-script-router --primary-engine tesseract --secondary-engine surya --primary-engine-kwarg 'language=nep+eng' --primary-engine-kwarg 'psm=6' --secondary-engine-kwarg 'mode=auto' ocrtech calibrate-tesseract-psm-ensemble --primary-experiment-report outputs/psm13-calibration/experiment.json --variant-experiment psm7=outputs/psm7-calibration/experiment.json --variant-experiment psm11=outputs/psm11-calibration/experiment.json --variant-experiment psm13=outputs/psm13-calibration/experiment.json --out outputs/psm-ensemble-calibration --model-id ocrtech-tesseract-psm-ensemble ocrtech run-experiment --eval-manifest data/eval-pack/manifests/ocrtech-eval-pack.jsonl --out outputs/experiment --baselines candidate,tesseract,stock-paddle --candidate-model-config runs/recognizer/package/model-card.json --fallback-model-config runs/vlm-fallback/package/model-card.json ocrtech review-claim --experiment outputs/internal-claim/experiment.json --experiment outputs/ocrbench-v2/experiment.json --config claim-review.json --model-config runs/recognizer/package/model-card.json --out outputs/claim-review ocrtech validate-claim --benchmark-report outputs/bench/report.json --config validation.json --candidate-model-config runs/recognizer/package/model-card.json --fallback-model-config runs/vlm-fallback/package/model-card.json --out outputs/validation ``` `parse-doc` writes: - `document.json` - `document.md` - `tables/*.csv` - `tables/*.html` - `figures/*.png` - `figures/metadata.json` - `quality.json` Figure exports are explicit. If an engine supplies `figure.image_path`, `parse-doc` copies that file into `figures/`. If an engine supplies only a figure bbox and the source is a regular image or page-bundle directory, `parse-doc` crops the region into `figures/{figure_id}.png` when Pillow is available. For bundles, it uses `figure.page_index` to select the page image. If the artifact cannot be created, `figures/metadata.json` records `metadata.export_warnings` instead of silently dropping the figure image. When `--fallback-engine` or `--fallback-model-config` is configured, `document.json` records `metadata.fallback` with the primary engine, fallback engine/model card, confidence threshold, trigger reason, and success/error outcome. Benchmarks surface this as diagnostic metrics such as `fallback_triggered`, `fallback_succeeded`, and `fallback_failed`. The same fallback flags are available on `benchmark` and `run-experiment` for candidate/ours runs, and experiment metadata records the fallback model-card path, SHA-256, and confidence threshold. ## Engines `auto` tries deterministic sidecar OCR first, then PaddleOCR, then Tesseract. Optional engines fail loudly when binaries or packages are missing. Sidecar inputs are useful for tests and staged pipelines. For `page.png`, provide one of: - `page.png.ocr.json` - `page.ocr.json` - `page.png.txt` - `page.txt` ## Data Use `prepare-data` to verify actual fields and image paths before training. By default it fails on the first bad row. Use `--skip-invalid` when the upstream dataset is messy and you want a usable manifest plus an explicit reject log instead of a silent partial corpus. Use `merge-manifests` to assemble multi-source corpora without ad hoc `cat` pipelines, then `audit-manifest` before training and `split-manifest` to create deterministic leakage-safe train/eval manifests. The split groups exact sample signatures before assignment so duplicate image+text examples cannot land on both sides. Known Hugging Face adapters now stamp verified slice metadata automatically: - `gauravgiri/nepali-ocr-dataset`: `nepali`, `real` - `prashant0919/nepali-synthetic-ocr-lines`: `nepali`, `synthetic` - `nvidia/OCR-Synthetic-Multilingual-v1 --hf-subset en`: `english`, `synthetic`, `line_crop`, `en` Use `rebalance-manifest` only on the training split after `split-manifest`. Rebalancing before the split would turn deliberate duplication into leakage. Use `audit-recognizer-corpus` before launching a recognizer training job. It checks the actual train/eval manifests for sample counts, Latin-script coverage, Devanagari coverage, mixed-script examples, real/synthetic training coverage, and train/eval leakage. This guardrail was added after the failed PaddleOCR mixed v4 branch: a new GPU run should not start unless English preservation and Nepali coverage are explicit in the corpus. Use `build-recognizer-corpus` to assemble and upsample the training manifest by actual text buckets, not by wishful dataset labels. It tracks `latin_only`, `devanagari_only`, `mixed_devanagari_latin`, `real`, and `synthetic` coverage, then writes a build JSON/Markdown summary next to the output manifest. It does not invent missing categories: if a required bucket is absent from the input manifests, the command fails so you know to add real source data before using GPU time. `train-recognizer --backend paddleocr` writes `recognizer-training-summary.json` alongside the generated PaddleOCR config. Keep that file with any remote/GPU training bundle and pass it to `package-recognizer --training-summary`; it records manifest hashes, slice counts, character coverage, label/config hashes, and launch hyperparameters. `bundle-recognizer-training` records the bundled summary path and SHA-256 under `training_summary`, and packaged recognizer model cards record the same provenance when supplied. For real remote/GPU runs, use `bundle-recognizer-training --require-corpus-audit`; it runs the recognizer corpus audit and refuses to create the bundle if the corpus does not meet the configured English, Devanagari, mixed-script, real/synthetic, and leakage gates. The gate also checks isolated Latin-only and Devanagari-only samples; a corpus made entirely of mixed-script rows is not enough to protect English preservation or Nepali-only recognition. Planned source datasets: - `gauravgiri/nepali-ocr-dataset` - `prashant0919/nepali-synthetic-ocr-lines` - `nvidia/OCR-Synthetic-Multilingual-v1` - `cfilt/RoundTripOCR-nepali` The verified Hugging Face adapters are intentionally dataset-specific where the upstream schema is non-standard: - `gauravgiri/nepali-ocr-dataset`: generic `image` + `text` - `prashant0919/nepali-synthetic-ocr-lines`: `metadata.jsonl` plus per-line image files, downloaded lazily for the requested rows - `cfilt/RoundTripOCR-nepali`: correction pairs via `ocr` and `correct` - `nvidia/OCR-Synthetic-Multilingual-v1`: HDF5 shards with `annotations.line_bboxes`; use `--hf-subset en` for English crops Some upstream corpora are dirty. For example, the current `gauravgiri/nepali-ocr-dataset` sample prefix includes null `text` rows, so use `--skip-invalid` when you want a prepared manifest plus an explicit reject log instead of a hard stop. ## Baselines The benchmark command supports: - `ours` - `tesseract` - `stock-paddle` - `glm-ocr` - `paddleocr-vl` `glm-ocr` and `paddleocr-vl` are external command hooks: ```bash export OCRTECH_GLM_OCR_CMD='python scripts/run_glm_ocr.py --input {input} --out {out}' export OCRTECH_PADDLEOCR_VL_CMD='python scripts/run_paddleocr_vl.py --input {input} --out {out}' ``` The command must include both `{input}` and `{out}` placeholders. It may print Markdown to stdout or write `{out}/document.md`; `ocrtech` now normalizes that Markdown into its own `document.json` schema so external VLM baselines can still be scored for text, table cells, and reading order. The bundled wrappers are thin adapters, not magic: - `scripts/run_glm_ocr.py` uses the official `transformers` path from the `zai-org/GLM-OCR` model card. - `scripts/run_paddleocr_vl.py` uses the official `PaddleOCRVL(...).predict(...)` path from the `PaddlePaddle/PaddleOCR-VL-1.6` model card. - GLM-OCR still expects a git `transformers` build upstream. On `k2`, the released `transformers 4.57.6` package was not enough to instantiate its processor classes; a dedicated Python 3.11 env with git `transformers` and `torchvision` was required before the wrapper would run. - PaddleOCR-VL still needs the OCR extras that the official docs call out, for example `pip install "paddlex[ocr]==3.7.1"`. ## Validation Before SOTA Claims Use `validate-claim` before making any quality claim. The default validator is intentionally strict and will fail unless the benchmark report has held-out sample coverage, required slices, leakage checks, paired candidate-vs-baseline gates, and per-gate evidence such as paired wins and optional significance thresholds. Use `recognizer-admission-decision` after a recognizer admission validation run. It writes a small JSON/Markdown decision artifact: `admit` only for `claim_status=validated` with `passed=true`, otherwise `reject` with failed gate metrics and next actions for the next model branch. Use `create-eval-pack` for internal mixed Nepali/English document tests and `audit-eval-pack` to check whether the pack is claim-ready. The internal pack now includes a real `multi_page` slice in addition to the single-page paragraph, table, form, and figure templates. Text packs are for pipeline smoke tests only; image packs are required for OCR claims. Use `preflight-claim` before `run-experiment` on any claim-grade run. It fails early on missing references, invalid model cards, missing baseline dependencies, non-claim-ready eval packs, bad validation configs, and train/eval leakage. For routed or thresholded candidates such as `quality_select_composite` and `script_select_composite`, claim-grade runs also require explicit calibration provenance in the model card. If the candidate was calibrated on the same eval manifest you are about to benchmark, `preflight-claim` now fails on purpose. For those routed candidates, claim-grade runs also need the raw component baselines in the same benchmark. If a `script_select_composite` candidate is built from Tesseract and Surya, the claim run must include `candidate,tesseract,surya`; otherwise the repo now fails preflight because distinctness cannot be checked honestly. Use `run-experiment` to benchmark every manifest input, write reproducibility metadata, and run claim validation in one output directory. Use `review-claim` after the internal pack and public benchmark suites have all been run. It audits the portfolio-level evidence bundle so one green experiment does not get misrepresented as a broad SOTA claim. Use a candidate model card for any real benchmark of `ours`; see [docs/MODELS.md](MODELS.md). Use `filter-manifest` when a baseline is too expensive to run on the full pack and you need a reproducible exploratory subset instead of hand-editing a JSONL. See [docs/PREFLIGHT.md](PREFLIGHT.md), [docs/CLAIM_REVIEW.md](CLAIM_REVIEW.md), [docs/EVAL_PACK.md](EVAL_PACK.md), [docs/MODELS.md](MODELS.md), [docs/EXPERIMENTS.md](EXPERIMENTS.md), and [docs/VALIDATION.md](VALIDATION.md). ## Remote Training Use `docs/REMOTE_TRAINING.md` for the current `k2` host notes, `audit-remote-host`, and the safe SSH workflow. Do not commit SSH passwords or machine-specific secrets.