Add 195 files (runs/hf-recognizer-mixed-v2-full/finalized/package/artifacts/model/model.safetensors ...)
1ef1de7 verified Download src/ocrtech/cli.py from prosperious/ocr-tech-k2: direct link, hf CLI and curl.
- Browser
- Download file 93 kB
-
https://huggingface.co/prosperious/ocr-tech-k2/resolve/main/src/ocrtech/cli.py
- Command line
-
hf download hf://prosperious/ocr-tech-k2/src/ocrtech/cli.py
-
curl -L -o cli.py https://huggingface.co/prosperious/ocr-tech-k2/resolve/main/src/ocrtech/cli.py
93 kB
"""Command-line interface for ocrtech."""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
from .admission import assert_recognizer_family_not_stopped, decide_recognizer_admission, review_recognizer_failures
from .benchmark import derive_table_postprocess_benchmark, rescore_benchmark_report, run_benchmark, summarize_benchmark_report
from .calibration import calibrate_quality_router, calibrate_script_router, calibrate_tesseract_psm_ensemble
from .claim_review import review_claim
from .crops import extract_crop_manifest
from .datasets import audit_manifest, audit_recognizer_corpus, build_recognizer_corpus, filter_manifest, merge_manifests, rebalance_manifest, split_manifest
from .error_analysis import analyze_benchmark_errors, export_failure_manifest
from .errors import OcrTechError
from .evalpack import audit_eval_pack, create_eval_pack
from .experiments import run_experiment
from .language_registry import audit_font_renderability, audit_language_registry
from .manifest import inspect_hf_dataset, load_manifest, normalize_manifest_images, prepare_hf_dataset, prepare_local_dataset
from .models import audit_model_card, write_model_card
from .oracle import build_benchmark_oracle
from .paper import export_paper_benchmark_table
from .pipeline import parse_document
from .preflight import run_claim_preflight
from .public_benchmarks import audit_public_benchmark_manifest, list_public_benchmarks, prepare_public_benchmark
from .references import materialize_references
from .remote import DEFAULT_PYTHON_CANDIDATES, audit_remote_host, bootstrap_remote_host, sync_remote_workspace
from .source_audit import (
DEFAULT_GORKHAPATRA_CATEGORY_URLS,
DEFAULT_GORKHAPATRA_EPAPER_URL,
DEFAULT_NAYA_NEPAL_PUBLICATION_URL,
audit_gorkhapatra_language_pages,
audit_gorkhapatra_source,
prepare_gorkhapatra_language_page_review,
prepare_gorkhapatra_language_page_pack,
prepare_gorkhapatra_pack,
)
from .table_analysis import analyze_table_cells
from .training import (
PADDLE_DEVANAGARI_PPOCRV3_PRETRAINED,
bundle_recognizer_training,
finalize_hf_recognizer_run,
generate_correction_pairs,
package_hf_text_corrector_model,
package_hf_recognizer_model,
package_paddleocr_model,
write_corrector_recipe,
write_hf_text_corrector_recipe,
write_hf_recognizer_recipe,
write_recognizer_export_recipe,
write_recognizer_recipe,
)
from .validation import validate_claim
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="ocrtech", description="Nepali + English OCR document parser")
subparsers = parser.add_subparsers(dest="command", required=True)
prepare = subparsers.add_parser("prepare-data", help="download/verify/convert datasets into manifests")
prepare.add_argument("source", help="local CSV/JSONL/directory or Hugging Face dataset id")
prepare.add_argument("--out", default="data/manifests", help="output manifest directory")
prepare.add_argument("--dataset-name", help="manifest dataset name")
prepare.add_argument("--split", default="train", help="dataset split")
prepare.add_argument("--image-field", help="explicit image field")
prepare.add_argument("--text-field", help="explicit text field")
prepare.add_argument("--hf-subset", help="known HF dataset subset/language selector (for example: en)")
prepare.add_argument("--limit", type=int, help="max rows to convert")
prepare.add_argument("--hf", action="store_true", help="load source with Hugging Face datasets")
prepare.add_argument("--skip-invalid", action="store_true", help="skip invalid rows and write a reject report")
prepare.add_argument("--strict-chars", action="store_true", help="reject unsupported dictionary characters")
prepare.add_argument("--slice", action="append", default=[], help="slice label to stamp into manifest metadata; repeatable")
prepare.set_defaults(func=cmd_prepare_data)
inspect_hf = subparsers.add_parser("inspect-hf-dataset", help="inspect a Hugging Face dataset schema before manifest conversion")
inspect_hf.add_argument("dataset_id", help="Hugging Face dataset id")
inspect_hf.add_argument("--out", default="outputs/hf-dataset-inspection")
inspect_hf.add_argument("--split", default="train")
inspect_hf.add_argument("--hf-subset", help="dataset subset/language selector")
inspect_hf.add_argument("--image-field", help="explicit image field")
inspect_hf.add_argument("--text-field", help="explicit text field")
inspect_hf.add_argument("--limit", type=int, default=3)
inspect_hf.set_defaults(func=cmd_inspect_hf_dataset)
audit_manifest_parser = subparsers.add_parser("audit-manifest", help="audit a training or evaluation manifest")
audit_manifest_parser.add_argument("manifest")
audit_manifest_parser.add_argument("--out", default="outputs/manifest-audit")
audit_manifest_parser.add_argument("--no-verify-hashes", action="store_true")
audit_manifest_parser.add_argument("--require-slice", action="append", default=[])
audit_manifest_parser.add_argument("--strict-chars", action="store_true")
audit_manifest_parser.set_defaults(func=cmd_audit_manifest)
split = subparsers.add_parser("split-manifest", help="create deterministic leakage-safe train/eval manifests")
split.add_argument("manifest")
split.add_argument("--out", default="data/splits")
split.add_argument("--eval-ratio", type=float, default=0.15)
split.add_argument("--seed", type=int, default=13)
split.add_argument("--stratify-by", choices=["slices", "dataset", "document_type", "none"], default="slices")
split.add_argument("--group-by", choices=["sample_signature", "text_sha256", "image_sha256", "image_path", "sample_id"], default="sample_signature")
split.set_defaults(func=cmd_split_manifest)
rebalance = subparsers.add_parser("rebalance-manifest", help="upsample underrepresented slices in a manifest for training")
rebalance.add_argument("manifest")
rebalance.add_argument("--out", default="data/manifests/rebalanced.jsonl")
rebalance.add_argument("--slice", action="append", default=[], help="slice to rebalance; repeatable")
rebalance.add_argument("--target-count", type=int, help="target count per requested slice; defaults to the largest requested slice")
rebalance.add_argument("--seed", type=int, default=13)
rebalance.set_defaults(func=cmd_rebalance_manifest)
corpus_audit = subparsers.add_parser("audit-recognizer-corpus", help="audit train/eval manifests before recognizer training")
corpus_audit.add_argument("--train-manifest", required=True)
corpus_audit.add_argument("--eval-manifest", required=True)
corpus_audit.add_argument("--out", default="outputs/recognizer-corpus-audit")
corpus_audit.add_argument("--min-train-samples", type=int, default=1000)
corpus_audit.add_argument("--min-eval-samples", type=int, default=100)
corpus_audit.add_argument("--min-train-english", type=int, default=200)
corpus_audit.add_argument("--min-train-devanagari", type=int, default=200)
corpus_audit.add_argument("--min-train-mixed", type=int, default=25)
corpus_audit.add_argument("--min-eval-english", type=int, default=50)
corpus_audit.add_argument("--min-eval-devanagari", type=int, default=50)
corpus_audit.add_argument("--min-eval-mixed", type=int, default=10)
corpus_audit.add_argument("--min-train-latin-only", type=int, default=50)
corpus_audit.add_argument("--min-train-devanagari-only", type=int, default=50)
corpus_audit.add_argument("--min-eval-latin-only", type=int, default=10)
corpus_audit.add_argument("--min-eval-devanagari-only", type=int, default=10)
corpus_audit.add_argument("--min-train-real", type=int, default=100)
corpus_audit.add_argument("--min-train-synthetic", type=int, default=100)
corpus_audit.set_defaults(func=cmd_audit_recognizer_corpus)
corpus_build = subparsers.add_parser("build-recognizer-corpus", help="assemble and upsample a recognizer training manifest by script buckets")
corpus_build.add_argument("manifests", nargs="+")
corpus_build.add_argument("--out", required=True)
corpus_build.add_argument("--target-latin-only", type=int, default=0)
corpus_build.add_argument("--target-devanagari-only", type=int, default=0)
corpus_build.add_argument("--target-mixed", type=int, default=0)
corpus_build.add_argument("--target-real", type=int, default=0)
corpus_build.add_argument("--target-synthetic", type=int, default=0)
corpus_build.add_argument("--seed", type=int, default=13)
corpus_build.set_defaults(func=cmd_build_recognizer_corpus)
merge = subparsers.add_parser("merge-manifests", help="combine multiple manifests into one auditable corpus")
merge.add_argument("manifests", nargs="+")
merge.add_argument("--out", default="data/manifests/combined.jsonl")
merge.set_defaults(func=cmd_merge_manifests)
filter_parser = subparsers.add_parser("filter-manifest", help="select a reproducible subset of a manifest")
filter_parser.add_argument("manifest")
filter_parser.add_argument("--out", default="data/manifests/filtered.jsonl")
filter_parser.add_argument("--sample-id", action="append", default=[], help="exact sample_id to include; repeatable")
filter_parser.add_argument("--slice", action="append", default=[], help="required slice label; repeatable")
filter_parser.add_argument("--document-type", action="append", default=[], help="required document_type metadata value; repeatable")
filter_parser.add_argument("--degradation", action="append", default=[], help="required degradation metadata value; repeatable")
filter_parser.add_argument("--limit", type=int)
filter_parser.set_defaults(func=cmd_filter_manifest)
refs = subparsers.add_parser("materialize-references", help="write benchmark reference files from a manifest and optionally rewrite manifest metadata")
refs.add_argument("manifest")
refs.add_argument("--out", default="data/references")
refs.add_argument("--rewritten-manifest", help="optional manifest output path with metadata.reference_path populated")
refs.set_defaults(func=cmd_materialize_references)
normalize_images = subparsers.add_parser("normalize-manifest-images", help="copy/convert manifest images to OCR-supported suffixes")
normalize_images.add_argument("manifest")
normalize_images.add_argument("--out", default="data/normalized-images")
normalize_images.add_argument("--image-dir-name", default="images")
normalize_images.add_argument("--output-manifest-name", default="manifest-images-normalized.jsonl")
normalize_images.set_defaults(func=cmd_normalize_manifest_images)
create_eval = subparsers.add_parser("create-eval-pack", help="generate a held-out Nepali + English document eval pack")
create_eval.add_argument("--out", default="data/eval-pack", help="eval-pack output directory")
create_eval.add_argument("--count-per-template", type=int, default=1)
create_eval.add_argument("--input-format", choices=["text", "image"], default="text")
create_eval.add_argument("--degradation", action="append", help="degradation to generate; repeatable")
create_eval.add_argument("--seed", type=int, default=13)
create_eval.add_argument("--font-path", help="font path for image rendering")
create_eval.add_argument("--template", action="append", default=[], help="template name to generate; repeatable")
create_eval.add_argument("--variant-offset", type=int, default=0, help="starting copy index for generated template variants")
create_eval.set_defaults(func=cmd_create_eval_pack)
audit_eval = subparsers.add_parser("audit-eval-pack", help="audit eval-pack manifest integrity and claim readiness")
audit_eval.add_argument("manifest", help="eval-pack manifest JSONL")
audit_eval.add_argument("--out", default="outputs/eval-pack-audit")
audit_eval.add_argument("--require-claim-ready", action="store_true")
audit_eval.set_defaults(func=cmd_audit_eval_pack)
crops = subparsers.add_parser("extract-crops", help="extract line/cell/caption recognizer crops from rendered eval-pack layout metadata")
crops.add_argument("manifest", help="source eval-pack manifest JSONL")
crops.add_argument("--out", default="data/crops", help="crop manifest output directory")
crops.add_argument("--crop-type", action="append", default=[], choices=["line", "table-cell", "figure-caption"], help="crop type to extract; repeatable")
crops.add_argument("--split", default="train", help="split label for emitted crop manifest rows")
crops.add_argument("--dataset-name", default="ocrtech-crops")
crops.add_argument("--min-text-length", type=int, default=1)
crops.set_defaults(func=cmd_extract_crops)
train_rec = subparsers.add_parser("train-recognizer", help="write a PaddleOCR recognizer training recipe")
train_rec.add_argument("--train-manifest", required=True)
train_rec.add_argument("--eval-manifest", required=True)
train_rec.add_argument("--out", default="runs/recognizer")
train_rec.add_argument("--backend", choices=["paddleocr", "hf-vision-encoder-decoder"], default="paddleocr")
train_rec.add_argument("--base-model", default=PADDLE_DEVANAGARI_PPOCRV3_PRETRAINED)
train_rec.add_argument("--dictionary")
train_rec.add_argument("--max-target-length", type=int, default=128)
train_rec.add_argument("--train-batch-size", type=int, default=8)
train_rec.add_argument("--eval-batch-size", type=int, default=8)
train_rec.add_argument("--learning-rate", type=float, default=5e-5)
train_rec.add_argument("--epochs", type=float, default=3.0)
train_rec.add_argument("--failure-review", help="recognizer-failure-review.json used to reject stopped model families")
train_rec.add_argument("--run", action="store_true", help="run PaddleOCR training command after writing config")
train_rec.set_defaults(func=cmd_train_recognizer)
export_rec = subparsers.add_parser("export-recognizer", help="write or run a PaddleOCR recognizer export recipe")
export_rec.add_argument("--training-config", required=True)
export_rec.add_argument("--checkpoint", required=True)
export_rec.add_argument("--out", default="runs/recognizer/export")
export_rec.add_argument("--inference-dir")
export_rec.add_argument("--paddleocr-dir", default="PaddleOCR")
export_rec.add_argument("--run", action="store_true")
export_rec.set_defaults(func=cmd_export_recognizer)
package_rec = subparsers.add_parser("package-recognizer", help="package PaddleOCR inference artifacts into a candidate model card")
package_rec.add_argument("--inference-dir", required=True)
package_rec.add_argument("--dictionary", required=True)
package_rec.add_argument("--out", default="runs/recognizer/package")
package_rec.add_argument("--model-id", required=True)
package_rec.add_argument("--base-model", default=PADDLE_DEVANAGARI_PPOCRV3_PRETRAINED)
package_rec.add_argument("--train-manifest")
package_rec.add_argument("--eval-manifest")
package_rec.add_argument("--training-summary")
package_rec.add_argument("--metrics-report")
package_rec.add_argument("--admission-validation-report")
package_rec.set_defaults(func=cmd_package_recognizer)
bundle_rec = subparsers.add_parser("bundle-recognizer-training", help="package recognizer recipe, manifests, and images for transfer to a training host")
bundle_rec.add_argument("--recipe-dir", required=True)
bundle_rec.add_argument("--train-manifest", required=True)
bundle_rec.add_argument("--eval-manifest", required=True)
bundle_rec.add_argument("--out", default="runs/recognizer-training-bundle")
bundle_rec.add_argument("--archive-name", default="recognizer-training-bundle.tar.gz")
bundle_rec.add_argument("--base-dir", default=".")
bundle_rec.add_argument("--failure-review", help="recognizer-failure-review.json used to reject stopped model families before bundling")
bundle_rec.add_argument("--require-corpus-audit", action="store_true", help="fail unless train/eval manifests pass recognizer corpus coverage checks")
bundle_rec.add_argument("--min-train-samples", type=int, default=1000)
bundle_rec.add_argument("--min-eval-samples", type=int, default=100)
bundle_rec.add_argument("--min-train-english", type=int, default=200)
bundle_rec.add_argument("--min-train-devanagari", type=int, default=200)
bundle_rec.add_argument("--min-train-mixed", type=int, default=25)
bundle_rec.add_argument("--min-eval-english", type=int, default=50)
bundle_rec.add_argument("--min-eval-devanagari", type=int, default=50)
bundle_rec.add_argument("--min-eval-mixed", type=int, default=10)
bundle_rec.add_argument("--min-train-latin-only", type=int, default=50)
bundle_rec.add_argument("--min-train-devanagari-only", type=int, default=50)
bundle_rec.add_argument("--min-eval-latin-only", type=int, default=10)
bundle_rec.add_argument("--min-eval-devanagari-only", type=int, default=10)
bundle_rec.add_argument("--min-train-real", type=int, default=100)
bundle_rec.add_argument("--min-train-synthetic", type=int, default=100)
bundle_rec.set_defaults(func=cmd_bundle_recognizer_training)
package_hf = subparsers.add_parser("package-hf-recognizer", help="package a Hugging Face OCR model directory into a candidate model card")
package_hf.add_argument("--model-dir", required=True)
package_hf.add_argument("--out", default="runs/hf-recognizer/package")
package_hf.add_argument("--model-id", required=True)
package_hf.add_argument("--base-model", required=True)
package_hf.add_argument("--train-manifest")
package_hf.add_argument("--eval-manifest")
package_hf.add_argument("--training-summary")
package_hf.add_argument("--metrics-report")
package_hf.add_argument("--admission-validation-report")
package_hf.add_argument("--max-new-tokens", type=int, default=128)
package_hf.set_defaults(func=cmd_package_hf_recognizer)
finalize_hf = subparsers.add_parser("finalize-hf-recognizer-run", help="package and audit a completed Hugging Face recognizer training run")
finalize_hf.add_argument("--run-dir", required=True)
finalize_hf.add_argument("--out")
finalize_hf.add_argument("--model-id", required=True)
finalize_hf.add_argument("--base-model", required=True)
finalize_hf.add_argument("--train-manifest")
finalize_hf.add_argument("--eval-manifest")
finalize_hf.add_argument("--training-summary")
finalize_hf.add_argument("--admission-validation-report")
finalize_hf.add_argument("--max-new-tokens", type=int, default=128)
finalize_hf.set_defaults(func=cmd_finalize_hf_recognizer_run)
package_hf_corrector = subparsers.add_parser("package-hf-corrector", help="package a Hugging Face text corrector into a composite OCR candidate model card")
package_hf_corrector.add_argument("--model-dir", required=True)
package_hf_corrector.add_argument("--out", default="runs/hf-corrector/package")
package_hf_corrector.add_argument("--model-id", required=True)
package_hf_corrector.add_argument("--base-model", required=True)
package_hf_corrector.add_argument("--base-engine", default="tesseract")
package_hf_corrector.add_argument("--base-engine-kwarg", action="append", default=[], help="base OCR engine kwarg as key=value; repeatable")
package_hf_corrector.add_argument("--train-manifest")
package_hf_corrector.add_argument("--eval-manifest")
package_hf_corrector.add_argument("--metrics-report")
package_hf_corrector.add_argument("--max-new-tokens", type=int, default=256)
package_hf_corrector.set_defaults(func=cmd_package_hf_corrector)
pair_mining = subparsers.add_parser("generate-correction-pairs", help="run an OCR engine on a manifest and write noisy-clean correction pairs")
pair_mining.add_argument("--manifest", required=True)
pair_mining.add_argument("--out", required=True)
pair_mining.add_argument("--engine", default="tesseract", choices=["tesseract", "paddleocr", "surya", "candidate", "ours", "sidecar"])
pair_mining.add_argument("--model-config")
pair_mining.add_argument("--limit", type=int)
pair_mining.add_argument("--only-errors", action="store_true")
pair_mining.set_defaults(func=cmd_generate_correction_pairs)
train_corr = subparsers.add_parser("train-corrector", help="write an OCR correction training recipe")
train_corr.add_argument("--out", default="runs/corrector")
train_corr.add_argument("--clean-manifest", help="clean OCR manifest used to synthesize noisy pairs")
train_corr.add_argument("--pairs-source", help="JSONL with noisy_text and clean_text fields")
train_corr.add_argument("--hf-dataset", help="verified HF correction dataset id, for example cfilt/RoundTripOCR-nepali")
train_corr.add_argument("--hf-split", default="train")
train_corr.add_argument("--limit", type=int)
train_corr.add_argument("--seed", type=int, default=13)
train_corr.add_argument("--backend", choices=["recipe", "hf-seq2seq"], default="recipe")
train_corr.add_argument("--base-model", default="google/byt5-small")
train_corr.add_argument("--eval-ratio", type=float, default=0.1)
train_corr.add_argument("--max-source-length", type=int, default=256)
train_corr.add_argument("--max-target-length", type=int, default=256)
train_corr.add_argument("--train-batch-size", type=int, default=16)
train_corr.add_argument("--eval-batch-size", type=int, default=16)
train_corr.add_argument("--learning-rate", type=float, default=5e-5)
train_corr.add_argument("--epochs", type=float, default=3.0)
train_corr.add_argument("--run", action="store_true")
train_corr.set_defaults(func=cmd_train_corrector)
model_card = subparsers.add_parser("create-model-card", help="write a candidate model artifact card")
model_card.add_argument("--out", required=True)
model_card.add_argument("--model-id", required=True)
model_card.add_argument("--backend", choices=["paddleocr", "sidecar", "tesseract", "surya", "hf_vision_encoder_decoder", "text_correction_composite", "quality_select_composite", "quality_ranked_ensemble", "script_select_composite", "line_align_composite", "table_cell_refine_composite", "figure_caption_refine_composite"], default="paddleocr")
model_card.add_argument("--base-model", default=PADDLE_DEVANAGARI_PPOCRV3_PRETRAINED)
model_card.add_argument("--artifact", action="append", default=[], help="required model artifact path; repeatable")
model_card.add_argument("--backend-kwarg", action="append", default=[], help="backend kwarg as key=value; repeatable")
model_card.add_argument("--paddleocr-kwarg", action="append", default=[], help="deprecated alias for --backend-kwarg; repeatable")
model_card.add_argument("--train-manifest")
model_card.add_argument("--eval-manifest")
model_card.add_argument("--metrics-report")
model_card.add_argument("--admission-validation-report")
model_card.add_argument("--fallback-model-card", help="fallback component model-card path to record in provenance")
model_card.add_argument("--notes")
model_card.set_defaults(func=cmd_create_model_card)
model_audit = subparsers.add_parser("audit-model", help="audit a candidate model card and artifacts")
model_audit.add_argument("model_config")
model_audit.add_argument("--out", default="outputs/model-audit")
model_audit.set_defaults(func=cmd_audit_model)
parse = subparsers.add_parser("parse-doc", help="convert image/PDF/text sidecar to Markdown, JSON, tables, and figures")
parse.add_argument("input")
parse.add_argument("--out", default="outputs/document")
parse.add_argument("--engine", default="auto", choices=["auto", "sidecar", "tesseract", "paddleocr", "surya", "candidate", "ours"])
parse.add_argument("--model-config", help="candidate model card path when --engine candidate/ours")
parse.add_argument("--fallback-engine", choices=["sidecar", "tesseract", "paddleocr", "surya"])
parse.add_argument("--fallback-model-config", help="candidate model card path to use as a selective fallback engine")
parse.add_argument("--low-confidence-threshold", type=float, default=0.80)
parse.add_argument("--fallback-min-quality-score", type=float, help="trigger configured fallback when primary document quality score is below this value")
parse.set_defaults(func=cmd_parse_doc)
benchmark = subparsers.add_parser("benchmark", help="compare OCR baselines on the same files")
benchmark.add_argument("inputs", nargs="*")
benchmark.add_argument("--inputs-from-manifest", help="load benchmark input paths from a manifest image_path field")
benchmark.add_argument("--out", default="outputs/benchmark")
benchmark.add_argument("--baselines", default="ours,tesseract,stock-paddle,glm-ocr,paddleocr-vl")
benchmark.add_argument("--references-dir")
benchmark.add_argument("--eval-manifest")
benchmark.add_argument("--candidate-model-config")
benchmark.add_argument("--fallback-engine", choices=["sidecar", "tesseract", "paddleocr", "surya"])
benchmark.add_argument("--fallback-model-config", help="candidate model card path to use as a selective fallback engine")
benchmark.add_argument("--low-confidence-threshold", type=float, default=0.80)
benchmark.add_argument("--fallback-min-quality-score", type=float, help="trigger configured candidate fallback when primary document quality score is below this value")
benchmark.add_argument("--resume-existing", action="store_true", help="score existing document.json outputs and run only missing pages")
benchmark.add_argument("--sample-timeout-seconds", type=int, help="mark one page as error if a baseline exceeds this runtime")
benchmark.add_argument("--capture-gpu-metrics", action="store_true", help="sample nvidia-smi before and after each benchmark row when available")
benchmark.set_defaults(func=cmd_benchmark)
summarize = subparsers.add_parser("summarize-benchmark", help="summarize aggregate and paired benchmark metrics from report.json")
summarize.add_argument("--benchmark-report", required=True)
summarize.add_argument("--out", default="outputs/benchmark-summary")
summarize.add_argument("--candidate", default="candidate")
summarize.add_argument("--baseline", action="append", default=[], help="baseline to compare against candidate; repeatable")
summarize.add_argument("--metric", action="append", default=[], help="metric to summarize in paired comparisons; repeatable")
summarize.set_defaults(func=cmd_summarize_benchmark)
rescore = subparsers.add_parser("rescore-benchmark", help="recompute benchmark metrics from existing document.json outputs")
rescore.add_argument("--benchmark-report", required=True)
rescore.add_argument("--out", default="outputs/benchmark-rescored")
rescore.add_argument("--references-dir")
rescore.add_argument("--eval-manifest")
rescore.set_defaults(func=cmd_rescore_benchmark)
derive_table = subparsers.add_parser(
"derive-table-postprocess-benchmark",
help="derive a table-postprocessed candidate from an existing baseline document output",
)
derive_table.add_argument("--benchmark-report", required=True)
derive_table.add_argument("--out", default="outputs/benchmark-table-postprocess-derived")
derive_table.add_argument("--source-baseline", required=True)
derive_table.add_argument("--candidate-baseline", default="candidate")
derive_table.add_argument("--references-dir")
derive_table.add_argument("--eval-manifest")
derive_table.set_defaults(func=cmd_derive_table_postprocess_benchmark)
table_cells = subparsers.add_parser("analyze-table-cells", help="analyze cell-level table OCR errors from benchmark document outputs")
table_cells.add_argument("--benchmark-report", required=True)
table_cells.add_argument("--eval-manifest", required=True)
table_cells.add_argument("--out", default="outputs/table-cell-analysis")
table_cells.add_argument("--candidate", default="candidate")
table_cells.add_argument("--baseline", action="append", default=[], help="baseline to compare against candidate; repeatable")
table_cells.add_argument("--top-n", type=int, default=25)
table_cells.set_defaults(func=cmd_analyze_table_cells)
paper_table = subparsers.add_parser("paper-benchmark-table", help="merge benchmark summary artifacts into a paper-ready comparison table")
paper_table.add_argument("--summary", action="append", default=[], required=True, help="path to summarize-benchmark summary.json; repeatable")
paper_table.add_argument("--out", default="outputs/paper-table")
paper_table.add_argument("--slice", default="all")
paper_table.add_argument("--metric", action="append", default=[], help="aggregate metric column to include; repeatable")
paper_table.add_argument("--system", action="append", default=[], help="system row to include and order explicitly; repeatable")
paper_table.add_argument("--label", action="append", default=[], help="display label override as system=Label; repeatable")
paper_table.add_argument("--source-preference", action="append", default=[], help="pin a system to one summary artifact as system=path; repeatable")
paper_table.add_argument("--title", help="optional table title")
paper_table.set_defaults(func=cmd_paper_benchmark_table)
oracle = subparsers.add_parser("benchmark-oracle", help="compute per-sample oracle headroom from a benchmark report")
oracle.add_argument("--benchmark-report", required=True)
oracle.add_argument("--out", default="outputs/benchmark-oracle")
oracle.add_argument("--metric", default="cer")
oracle.add_argument("--direction", choices=["lower", "higher"])
oracle.add_argument("--system", action="append", default=[], help="system to include in oracle selection; repeatable")
oracle.add_argument("--oracle-name", default="oracle")
oracle.set_defaults(func=cmd_benchmark_oracle)
error_analysis = subparsers.add_parser("benchmark-error-analysis", help="rank hard samples and slice gaps from a benchmark report")
error_analysis.add_argument("--benchmark-report", required=True)
error_analysis.add_argument("--out", default="outputs/benchmark-error-analysis")
error_analysis.add_argument("--system", required=True)
error_analysis.add_argument("--baseline", action="append", default=[], help="baseline to compare against system; repeatable")
error_analysis.add_argument("--metric", default="cer")
error_analysis.add_argument("--direction", choices=["lower", "higher"])
error_analysis.add_argument("--top-n", type=int, default=20)
error_analysis.set_defaults(func=cmd_benchmark_error_analysis)
failure_manifest = subparsers.add_parser("export-failure-manifest", help="write a manifest from ranked benchmark failure rows")
failure_manifest.add_argument("--source-manifest", required=True)
failure_manifest.add_argument("--top-failures", required=True)
failure_manifest.add_argument("--out", required=True)
failure_manifest.add_argument("--split", help="optional split override for selected entries")
failure_manifest.set_defaults(func=cmd_export_failure_manifest)
admission_decision = subparsers.add_parser("recognizer-admission-decision", help="summarize whether a recognizer admission validation report promotes or rejects a model branch")
admission_decision.add_argument("--validation-report", required=True)
admission_decision.add_argument("--out", default="outputs/recognizer-admission-decision")
admission_decision.set_defaults(func=cmd_recognizer_admission_decision)
failure_review = subparsers.add_parser("recognizer-failure-review", help="aggregate recognizer admission failures across runs and flag exhausted model families")
failure_review.add_argument("--admission-decision", action="append", default=[], help="recognizer-admission-decision.json path; repeatable")
failure_review.add_argument("--validation-report", action="append", default=[], help="validation.json path to convert into a review input; repeatable")
failure_review.add_argument("--model-card", action="append", default=[], help="model-card.json path matched to inputs by order when provenance is unavailable; repeatable")
failure_review.add_argument("--min-rejections-to-stop", type=int, default=3)
failure_review.add_argument("--out", default="outputs/recognizer-failure-review")
failure_review.set_defaults(func=cmd_recognizer_failure_review)
calibrate = subparsers.add_parser("calibrate-quality-router", help="calibrate a quality-routed composite candidate from a calibration experiment")
calibrate.add_argument("--experiment-report", required=True)
calibrate.add_argument("--out", default="outputs/quality-router-calibration")
calibrate.add_argument("--model-id", required=True)
calibrate.add_argument("--base-model", default="tesseract-ocr")
calibrate.add_argument("--primary-engine", required=True)
calibrate.add_argument("--secondary-engine", required=True)
calibrate.add_argument("--primary-engine-kwarg", action="append", default=[], help="primary engine kwarg as key=value; repeatable")
calibrate.add_argument("--secondary-engine-kwarg", action="append", default=[], help="secondary engine kwarg as key=value; repeatable")
calibrate.add_argument("--candidate-baseline", default="candidate")
calibrate.add_argument("--primary-baseline", default="tesseract")
calibrate.add_argument("--metric", default="cer")
calibrate.add_argument("--direction", choices=["lower", "higher"])
calibrate.add_argument("--threshold-start", type=float, default=-0.20)
calibrate.add_argument("--threshold-end", type=float, default=0.20)
calibrate.add_argument("--threshold-step", type=float, default=0.01)
calibrate.add_argument("--notes")
calibrate.set_defaults(func=cmd_calibrate_quality_router)
calibrate_script = subparsers.add_parser("calibrate-script-router", help="calibrate a script-routed composite candidate from a calibration experiment")
calibrate_script.add_argument("--experiment-report", required=True)
calibrate_script.add_argument("--out", default="outputs/script-router-calibration")
calibrate_script.add_argument("--model-id", required=True)
calibrate_script.add_argument("--base-model", default="tesseract+surya")
calibrate_script.add_argument("--primary-engine", required=True)
calibrate_script.add_argument("--secondary-engine", required=True)
calibrate_script.add_argument("--primary-engine-kwarg", action="append", default=[], help="primary engine kwarg as key=value; repeatable")
calibrate_script.add_argument("--secondary-engine-kwarg", action="append", default=[], help="secondary engine kwarg as key=value; repeatable")
calibrate_script.add_argument("--primary-baseline", default="tesseract")
calibrate_script.add_argument("--secondary-baseline", default="surya")
calibrate_script.add_argument("--metric", default="cer")
calibrate_script.add_argument("--direction", choices=["lower", "higher"])
calibrate_script.add_argument("--script", default="devanagari")
calibrate_script.add_argument("--threshold-start", type=float, default=0.0)
calibrate_script.add_argument("--threshold-end", type=float, default=0.6)
calibrate_script.add_argument("--threshold-step", type=float, default=0.05)
calibrate_script.add_argument("--routing-granularity", choices=["document", "page"], default="document")
calibrate_script.add_argument("--secondary-structure-backfill", action="store_true")
calibrate_script.add_argument("--notes")
calibrate_script.set_defaults(func=cmd_calibrate_script_router)
calibrate_ensemble = subparsers.add_parser("calibrate-tesseract-psm-ensemble", help="calibrate a quality-ranked Tesseract PSM ensemble from separate variant experiments")
calibrate_ensemble.add_argument("--primary-experiment-report", required=True)
calibrate_ensemble.add_argument("--variant-experiment", action="append", default=[], help="variant label and experiment report as label=path; repeatable")
calibrate_ensemble.add_argument("--out", default="outputs/tesseract-psm-ensemble-calibration")
calibrate_ensemble.add_argument("--model-id", required=True)
calibrate_ensemble.add_argument("--metric", default="cer")
calibrate_ensemble.add_argument("--direction", choices=["lower", "higher"])
calibrate_ensemble.add_argument("--bias-start", type=float, default=-0.12)
calibrate_ensemble.add_argument("--bias-end", type=float, default=0.12)
calibrate_ensemble.add_argument("--bias-step", type=float, default=0.02)
calibrate_ensemble.add_argument("--language", default="nep+eng")
calibrate_ensemble.add_argument("--selection-margin", type=float, default=0.0)
calibrate_ensemble.add_argument("--notes")
calibrate_ensemble.set_defaults(func=cmd_calibrate_tesseract_psm_ensemble)
experiment = subparsers.add_parser("run-experiment", help="run benchmark and validation from an eval manifest")
experiment.add_argument("--eval-manifest", required=True)
experiment.add_argument("--out", default="outputs/experiment")
experiment.add_argument("--baselines", default="ours,tesseract,stock-paddle,glm-ocr,paddleocr-vl")
experiment.add_argument("--references-dir")
experiment.add_argument("--validation-config")
experiment.add_argument("--candidate-model-config")
experiment.add_argument("--fallback-engine", choices=["sidecar", "tesseract", "paddleocr", "surya"])
experiment.add_argument("--fallback-model-config", help="candidate model card path to use as a selective fallback engine")
experiment.add_argument("--low-confidence-threshold", type=float, default=0.80)
experiment.add_argument("--fallback-min-quality-score", type=float, help="trigger configured candidate fallback when primary document quality score is below this value")
experiment.add_argument("--train-manifest", action="append", default=[])
experiment.add_argument("--skip-validation", action="store_true")
experiment.add_argument("--require-validated", action="store_true")
experiment.add_argument("--preflight", action="store_true", help="run claim preflight before benchmark and stop on failure")
experiment.add_argument("--allow-smoke-eval-pack", action="store_true", help="allow smoke eval packs during run-experiment preflight")
experiment.add_argument("--require-trained-recognizer", action="store_true", help="require trained recognizer provenance during run-experiment preflight")
experiment.add_argument("--require-model-admission", action="store_true", help="require passing recognizer admission during run-experiment preflight")
experiment.set_defaults(func=cmd_run_experiment)
preflight = subparsers.add_parser("preflight-claim", help="fail early if claim benchmark inputs, models, references, or engines are not ready")
preflight.add_argument("--eval-manifest", required=True)
preflight.add_argument("--out", default="outputs/preflight")
preflight.add_argument("--baselines", default="candidate,tesseract,stock-paddle,glm-ocr,paddleocr-vl")
preflight.add_argument("--references-dir")
preflight.add_argument("--candidate-model-config")
preflight.add_argument("--fallback-model-config", help="fallback model card path to audit before claim benchmark runs")
preflight.add_argument("--validation-config")
preflight.add_argument("--train-manifest", action="append", default=[])
preflight.add_argument("--allow-smoke-eval-pack", action="store_true")
preflight.add_argument("--require-trained-recognizer", action="store_true")
preflight.add_argument("--require-model-admission", action="store_true")
preflight.set_defaults(func=cmd_preflight_claim)
public_list = subparsers.add_parser("list-public-benchmarks", help="list known public benchmark registry entries")
public_list.set_defaults(func=cmd_list_public_benchmarks)
public_prepare = subparsers.add_parser("prepare-public-benchmark", help="convert a verified public benchmark into an auditable manifest")
public_prepare.add_argument("benchmark", choices=["opendatalab/OmniDocBench"])
public_prepare.add_argument("--out", required=True)
public_prepare.add_argument("--limit", type=int)
public_prepare.add_argument("--language")
public_prepare.add_argument("--subset")
public_prepare.add_argument("--data-source")
public_prepare.add_argument("--require-tables", action="store_true")
public_prepare.add_argument("--annotation-path", help="local OmniDocBench.json path for offline/schema-fixture conversion")
public_prepare.add_argument("--local-image-root", help="local dataset root containing images/ for offline conversion")
public_prepare.set_defaults(func=cmd_prepare_public_benchmark)
public_audit = subparsers.add_parser("audit-public-benchmark", help="audit a public benchmark manifest for claim readiness")
public_audit.add_argument("manifest")
public_audit.add_argument("--out", default="outputs/public-benchmark-audit")
public_audit.add_argument("--benchmark", help="override benchmark name when manifest metadata is ambiguous")
public_audit.add_argument("--min-samples", type=int)
public_audit.add_argument("--allow-missing-reference-paths", action="store_true")
public_audit.set_defaults(func=cmd_audit_public_benchmark)
gorkhapatra_audit = subparsers.add_parser("audit-gorkhapatra-source", help="audit Gorkhapatra/Naya Nepal article images and epaper PDFs")
gorkhapatra_audit.add_argument("--out", default="outputs/gorkhapatra-source-audit")
gorkhapatra_audit.add_argument("--category-url", action="append", default=[], help="Naya Nepal category URL; repeatable")
gorkhapatra_audit.add_argument("--epaper-url", action="append", default=[], help="Gorkhapatra epaper list URL; repeatable")
gorkhapatra_audit.add_argument("--category-html", action="append", default=[], help="local category HTML fixture/path; repeatable")
gorkhapatra_audit.add_argument("--epaper-html", action="append", default=[], help="local epaper list HTML fixture/path; repeatable")
gorkhapatra_audit.add_argument("--no-default-urls", action="store_true", help="only use explicitly supplied URLs/HTML files")
gorkhapatra_audit.add_argument("--download-assets", action="store_true", help="download and hash discovered article images/PDFs")
gorkhapatra_audit.add_argument("--max-article-images", type=int, default=0, help="max article images to download; 0 means no limit")
gorkhapatra_audit.add_argument("--max-epaper-pdfs", type=int, default=0, help="max epaper PDFs to download; 0 means no limit")
gorkhapatra_audit.add_argument("--timeout-seconds", type=float, default=30.0)
gorkhapatra_audit.set_defaults(func=cmd_audit_gorkhapatra_source)
gorkhapatra_pack = subparsers.add_parser("prepare-gorkhapatra-pack", help="turn a Gorkhapatra source audit into a pending-reference validation manifest")
gorkhapatra_pack.add_argument("source_audit_json")
gorkhapatra_pack.add_argument("--out", default="data/gorkhapatra-pack")
gorkhapatra_pack.add_argument("--no-article-images", action="store_true")
gorkhapatra_pack.add_argument("--no-epaper-pages", action="store_true")
gorkhapatra_pack.add_argument("--max-article-images", type=int, default=0)
gorkhapatra_pack.add_argument("--max-epaper-pdfs", type=int, default=0)
gorkhapatra_pack.add_argument("--max-pages-per-pdf", type=int, default=2)
gorkhapatra_pack.add_argument("--split", default="eval")
gorkhapatra_pack.add_argument("--dataset-name", default="gorkhapatra-naya-nepal")
gorkhapatra_pack.set_defaults(func=cmd_prepare_gorkhapatra_pack)
language_pages = subparsers.add_parser("audit-gorkhapatra-language-pages", help="align Naya Nepal publication cards to same-date Gorkhapatra PDF language pages")
language_pages.add_argument("--out", default="outputs/gorkhapatra-language-pages")
language_pages.add_argument("--publication-url", action="append", default=[])
language_pages.add_argument("--epaper-url", action="append", default=[])
language_pages.add_argument("--publication-html", action="append", default=[])
language_pages.add_argument("--epaper-html", action="append", default=[])
language_pages.add_argument("--no-default-urls", action="store_true")
language_pages.add_argument("--download-pdfs", action="store_true")
language_pages.add_argument("--render-pages", action="store_true")
language_pages.add_argument("--max-publication-items", type=int, default=0)
language_pages.add_argument("--max-epaper-pdfs", type=int, default=0)
language_pages.add_argument("--timeout-seconds", type=float, default=30.0)
language_pages.set_defaults(func=cmd_audit_gorkhapatra_language_pages)
language_page_pack = subparsers.add_parser("prepare-gorkhapatra-language-page-pack", help="turn language-page alignment hits into a pending-reference manifest")
language_page_pack.add_argument("language_page_audit_json")
language_page_pack.add_argument("--out", default="data/gorkhapatra-language-page-pack")
language_page_pack.add_argument("--split", default="eval")
language_page_pack.add_argument("--dataset-name", default="gorkhapatra-language-pages")
language_page_pack.add_argument("--max-samples", type=int, default=0)
language_page_pack.set_defaults(func=cmd_prepare_gorkhapatra_language_page_pack)
language_page_review = subparsers.add_parser("prepare-gorkhapatra-language-page-review", help="write a manual review sheet for language-page candidates")
language_page_review.add_argument("language_page_pack_manifest")
language_page_review.add_argument("--out", default="data/gorkhapatra-language-page-review")
language_page_review.set_defaults(func=cmd_prepare_gorkhapatra_language_page_review)
language_registry = subparsers.add_parser("audit-language-registry", help="audit a multilingual OCR language registry")
language_registry.add_argument("registry")
language_registry.add_argument("--out", default="outputs/language-registry-audit")
language_registry.add_argument("--min-nepal-languages", type=int, default=10)
language_registry.add_argument("--allow-non-limbu-first", action="store_true")
language_registry.add_argument("--no-verify-local-paths", action="store_true")
language_registry.set_defaults(func=cmd_audit_language_registry)
font_audit = subparsers.add_parser("audit-font-renderability", help="audit registry font coverage and optional rendered samples")
font_audit.add_argument("registry")
font_audit.add_argument("--out", default="outputs/font-renderability-audit")
font_audit.add_argument("--all-scripts", action="store_true", help="audit secondary/future scripts in addition to primary scripts")
font_audit.add_argument("--min-coverage-ratio", type=float, default=0.95)
font_audit.add_argument("--render-samples", action="store_true", help="write sample PNGs when Pillow is installed")
font_audit.set_defaults(func=cmd_audit_font_renderability)
remote = subparsers.add_parser("audit-remote-host", help="audit a remote host for training and benchmark readiness")
remote.add_argument("--host", required=True)
remote.add_argument("--user")
remote.add_argument("--port", type=int, default=22)
remote.add_argument("--password-env")
remote.add_argument("--min-python", default="3.11")
remote.add_argument("--min-free-gb", type=float, default=20.0)
remote.add_argument("--workdir")
remote.add_argument("--require-gpu", action="store_true")
remote.add_argument("--require-paddle-training", action="store_true", help="fail if the host is not a valid official Paddle training target")
remote.add_argument("--python-candidate", action="append", default=[])
remote.add_argument("--require-command", action="append", default=[])
remote.add_argument("--optional-command", action="append", default=[])
remote.add_argument("--require-path", action="append", default=[])
remote.add_argument("--out", default="outputs/remote-audit")
remote.set_defaults(func=cmd_audit_remote_host)
bootstrap = subparsers.add_parser("bootstrap-remote-host", help="provision remote workdir and Python virtualenv for training")
bootstrap.add_argument("--host", required=True)
bootstrap.add_argument("--user")
bootstrap.add_argument("--port", type=int, default=22)
bootstrap.add_argument("--password-env")
bootstrap.add_argument("--workdir", required=True)
bootstrap.add_argument("--min-python", default="3.11")
bootstrap.add_argument("--python-candidate", action="append", default=[])
bootstrap.add_argument("--venv-name", default=".venv")
bootstrap.add_argument("--recreate-venv", action="store_true")
bootstrap.add_argument("--out", default="outputs/remote-bootstrap")
bootstrap.set_defaults(func=cmd_bootstrap_remote_host)
sync_remote = subparsers.add_parser("sync-remote-workspace", help="copy the current workspace to a remote host workdir")
sync_remote.add_argument("--host", required=True)
sync_remote.add_argument("--user")
sync_remote.add_argument("--port", type=int, default=22)
sync_remote.add_argument("--password-env")
sync_remote.add_argument("--local-root", default=".")
sync_remote.add_argument("--remote-workdir", required=True)
sync_remote.add_argument("--exclude", action="append", default=[])
sync_remote.add_argument("--out", default="outputs/remote-sync")
sync_remote.set_defaults(func=cmd_sync_remote_workspace)
review = subparsers.add_parser("review-claim", help="audit a full SOTA claim bundle across multiple experiment reports")
review.add_argument("--experiment", action="append", required=True, help="experiment.json path; repeatable")
review.add_argument("--config")
review.add_argument("--model-config")
review.add_argument("--out", default="outputs/claim-review")
review.set_defaults(func=cmd_review_claim)
validate = subparsers.add_parser("validate-claim", help="validate whether benchmark evidence supports a SOTA claim")
validate.add_argument("--benchmark-report", required=True, help="benchmark report.json path")
validate.add_argument("--out", default="outputs/validation", help="validation report directory")
validate.add_argument("--config", help="validation gates JSON")
validate.add_argument("--eval-manifest", help="held-out evaluation manifest")
validate.add_argument("--train-manifest", action="append", default=[], help="training manifest to check for leakage; repeatable")
validate.add_argument("--candidate-model-config", help="candidate model card path to record in validation provenance")
validate.add_argument("--fallback-model-config", help="fallback model card path to record in validation provenance")
validate.set_defaults(func=cmd_validate_claim)
return parser
def cmd_prepare_data(args: argparse.Namespace) -> int:
if args.hf:
path = prepare_hf_dataset(
args.source,
args.out,
dataset=args.dataset_name,
split=args.split,
image_field=args.image_field,
text_field=args.text_field,
hf_subset=args.hf_subset,
limit=args.limit,
skip_invalid=args.skip_invalid,
strict_chars=args.strict_chars,
slices=args.slice,
)
else:
path = prepare_local_dataset(
args.source,
args.out,
dataset=args.dataset_name,
split=args.split,
image_field=args.image_field,
text_field=args.text_field,
limit=args.limit,
skip_invalid=args.skip_invalid,
strict_chars=args.strict_chars,
slices=args.slice,
)
print(path.manifest_path)
print(path.summary_json_path)
print(path.summary_md_path)
if path.rejects_path:
print(path.rejects_path)
print(f"prepared={path.sample_count} rejected={path.rejected_count}")
return 0
def cmd_inspect_hf_dataset(args: argparse.Namespace) -> int:
report = inspect_hf_dataset(
args.dataset_id,
args.out,
split=args.split,
hf_subset=args.hf_subset,
image_field=args.image_field,
text_field=args.text_field,
limit=args.limit,
)
print(report.output_json_path)
print(report.output_md_path)
print(f"passed={report.passed} inspected={report.inspected_count}")
return 0 if report.passed else 1
def cmd_audit_manifest(args: argparse.Namespace) -> int:
audit = audit_manifest(
args.manifest,
args.out,
verify_hashes=not args.no_verify_hashes,
require_slices=args.require_slice,
strict_chars=args.strict_chars,
)
print(Path(args.out) / "manifest-audit.json")
print(Path(args.out) / "manifest-audit.md")
print(f"passed={audit.passed} samples={audit.sample_count}")
return 0 if audit.passed else 1
def cmd_split_manifest(args: argparse.Namespace) -> int:
summary = split_manifest(
args.manifest,
args.out,
eval_ratio=args.eval_ratio,
seed=args.seed,
stratify_by=args.stratify_by,
group_by=args.group_by,
)
print(summary.train_manifest)
print(summary.eval_manifest)
print(f"train={summary.train_count} eval={summary.eval_count} leakage_passed={summary.leakage_passed}")
return 0
def cmd_rebalance_manifest(args: argparse.Namespace) -> int:
summary = rebalance_manifest(args.manifest, args.out, slices=args.slice, target_count=args.target_count, seed=args.seed)
out_path = Path(args.out)
print(summary.output_manifest)
print(out_path.with_name(f"{out_path.stem}-rebalance.json"))
print(out_path.with_name(f"{out_path.stem}-rebalance.md"))
print(f"original={summary.original_count} rebalanced={summary.rebalanced_count} target={summary.target_count}")
return 0
def cmd_audit_recognizer_corpus(args: argparse.Namespace) -> int:
audit = audit_recognizer_corpus(
args.train_manifest,
args.eval_manifest,
args.out,
min_train_samples=args.min_train_samples,
min_eval_samples=args.min_eval_samples,
min_train_english=args.min_train_english,
min_train_devanagari=args.min_train_devanagari,
min_train_mixed=args.min_train_mixed,
min_eval_english=args.min_eval_english,
min_eval_devanagari=args.min_eval_devanagari,
min_eval_mixed=args.min_eval_mixed,
min_train_latin_only=args.min_train_latin_only,
min_train_devanagari_only=args.min_train_devanagari_only,
min_eval_latin_only=args.min_eval_latin_only,
min_eval_devanagari_only=args.min_eval_devanagari_only,
min_train_real=args.min_train_real,
min_train_synthetic=args.min_train_synthetic,
)
print(Path(args.out) / "recognizer-corpus-audit.json")
print(Path(args.out) / "recognizer-corpus-audit.md")
print(f"passed={audit.passed} train={audit.train_profile.sample_count} eval={audit.eval_profile.sample_count}")
return 0 if audit.passed else 1
def cmd_build_recognizer_corpus(args: argparse.Namespace) -> int:
summary = build_recognizer_corpus(
args.manifests,
args.out,
target_latin_only=args.target_latin_only,
target_devanagari_only=args.target_devanagari_only,
target_mixed=args.target_mixed,
target_real=args.target_real,
target_synthetic=args.target_synthetic,
seed=args.seed,
)
out_path = Path(args.out)
print(summary.output_manifest)
print(out_path.with_name(f"{out_path.stem}-recognizer-corpus-build.json"))
print(out_path.with_name(f"{out_path.stem}-recognizer-corpus-build.md"))
print(f"source={summary.source_count} output={summary.output_count}")
return 0
def cmd_merge_manifests(args: argparse.Namespace) -> int:
summary = merge_manifests(args.manifests, args.out)
out_path = Path(args.out)
print(summary.output_manifest)
print(out_path.with_name(f"{out_path.stem}-merge.json"))
print(out_path.with_name(f"{out_path.stem}-merge.md"))
print(f"samples={summary.sample_count} inputs={len(summary.input_manifests)} warnings={len(summary.warnings)}")
return 0
def cmd_filter_manifest(args: argparse.Namespace) -> int:
summary = filter_manifest(
args.manifest,
args.out,
sample_ids=args.sample_id,
slices=args.slice,
document_types=args.document_type,
degradations=args.degradation,
limit=args.limit,
)
out_path = Path(args.out)
print(summary.output_manifest)
print(out_path.with_name(f"{out_path.stem}-filter.json"))
print(out_path.with_name(f"{out_path.stem}-filter.md"))
print(f"selected={summary.selected_count} source={summary.source_count}")
return 0
def cmd_materialize_references(args: argparse.Namespace) -> int:
report = materialize_references(args.manifest, args.out, rewritten_manifest_path=args.rewritten_manifest)
print(report.references_dir)
if report.rewritten_manifest:
print(report.rewritten_manifest)
print(report.summary_json_path)
print(report.summary_md_path)
print(f"samples={report.sample_count}")
return 0
def cmd_normalize_manifest_images(args: argparse.Namespace) -> int:
report = normalize_manifest_images(
args.manifest,
args.out,
image_dir_name=args.image_dir_name,
output_manifest_name=args.output_manifest_name,
)
print(report.manifest_path)
print(report.summary_json_path)
print(report.summary_md_path)
print(f"samples={report.sample_count} copied={report.copied_count} converted={report.converted_count}")
return 0
def cmd_create_eval_pack(args: argparse.Namespace) -> int:
summary = create_eval_pack(
args.out,
count_per_template=args.count_per_template,
input_format=args.input_format,
degradations=args.degradation,
seed=args.seed,
font_path=args.font_path,
templates=args.template or None,
variant_offset=args.variant_offset,
)
print(summary.manifest_path)
print(f"samples={summary.sample_count} claim_ready={summary.claim_ready}")
return 0
def cmd_audit_eval_pack(args: argparse.Namespace) -> int:
audit = audit_eval_pack(args.manifest, args.out)
print(Path(args.out) / "eval-pack-audit.json")
print(Path(args.out) / "eval-pack-audit.md")
print(f"passed={audit.passed} claim_ready={audit.claim_ready}")
if not audit.passed or (args.require_claim_ready and not audit.claim_ready):
return 1
return 0
def cmd_extract_crops(args: argparse.Namespace) -> int:
summary = extract_crop_manifest(
args.manifest,
args.out,
crop_types=args.crop_type or None,
split=args.split,
dataset_name=args.dataset_name,
min_text_length=args.min_text_length,
)
print(summary.manifest_path)
print(Path(args.out) / "crop-manifest-summary.json")
print(Path(args.out) / "crop-manifest-summary.md")
print(f"crops={summary.crop_count} skipped={summary.skipped_count}")
return 0
def cmd_train_recognizer(args: argparse.Namespace) -> int:
if args.backend == "hf-vision-encoder-decoder":
if args.failure_review:
assert_recognizer_family_not_stopped(args.failure_review, backend="hf_vision_encoder_decoder", base_model=args.base_model)
path = write_hf_recognizer_recipe(
args.train_manifest,
args.eval_manifest,
args.out,
base_model=args.base_model,
max_target_length=args.max_target_length,
per_device_train_batch_size=args.train_batch_size,
per_device_eval_batch_size=args.eval_batch_size,
learning_rate=args.learning_rate,
num_train_epochs=args.epochs,
run=args.run,
)
else:
path = write_recognizer_recipe(
args.train_manifest,
args.eval_manifest,
args.out,
base_model=args.base_model,
dictionary_path=args.dictionary,
train_batch_size=args.train_batch_size,
eval_batch_size=args.eval_batch_size,
learning_rate=args.learning_rate,
epochs=args.epochs,
failure_review=args.failure_review,
run=args.run,
)
print(path)
return 0
def cmd_export_recognizer(args: argparse.Namespace) -> int:
path = write_recognizer_export_recipe(
args.training_config,
args.checkpoint,
args.out,
inference_dir=args.inference_dir,
paddleocr_dir=args.paddleocr_dir,
run=args.run,
)
print(path)
return 0
def cmd_package_recognizer(args: argparse.Namespace) -> int:
path = package_paddleocr_model(
args.inference_dir,
args.out,
model_id=args.model_id,
dictionary_path=args.dictionary,
base_model=args.base_model,
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
training_summary=args.training_summary,
metrics_report=args.metrics_report,
admission_validation_report=args.admission_validation_report,
)
print(path)
return 0
def cmd_bundle_recognizer_training(args: argparse.Namespace) -> int:
bundle = bundle_recognizer_training(
args.recipe_dir,
args.out,
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
archive_name=args.archive_name,
base_dir=args.base_dir,
require_corpus_audit=args.require_corpus_audit,
min_train_samples=args.min_train_samples,
min_eval_samples=args.min_eval_samples,
min_train_english=args.min_train_english,
min_train_devanagari=args.min_train_devanagari,
min_train_mixed=args.min_train_mixed,
min_eval_english=args.min_eval_english,
min_eval_devanagari=args.min_eval_devanagari,
min_eval_mixed=args.min_eval_mixed,
min_train_latin_only=args.min_train_latin_only,
min_train_devanagari_only=args.min_train_devanagari_only,
min_eval_latin_only=args.min_eval_latin_only,
min_eval_devanagari_only=args.min_eval_devanagari_only,
min_train_real=args.min_train_real,
min_train_synthetic=args.min_train_synthetic,
failure_review=args.failure_review,
)
print(bundle.archive_path)
print(bundle.manifest_path)
print(bundle.readme_path)
print(f"files={bundle.file_count} bytes={bundle.total_bytes}")
return 0
def cmd_package_hf_recognizer(args: argparse.Namespace) -> int:
path = package_hf_recognizer_model(
args.model_dir,
args.out,
model_id=args.model_id,
base_model=args.base_model,
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
training_summary=args.training_summary,
metrics_report=args.metrics_report,
admission_validation_report=args.admission_validation_report,
max_new_tokens=args.max_new_tokens,
)
print(path)
return 0
def cmd_finalize_hf_recognizer_run(args: argparse.Namespace) -> int:
result = finalize_hf_recognizer_run(
args.run_dir,
output_dir=args.out,
model_id=args.model_id,
base_model=args.base_model,
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
training_summary=args.training_summary,
admission_validation_report=args.admission_validation_report,
max_new_tokens=args.max_new_tokens,
)
print(result.model_card_path)
print(result.audit_path)
print(result.report_json_path)
print(result.report_md_path)
print(f"audit_passed={result.audit_passed}")
return 0 if result.audit_passed else 1
def cmd_package_hf_corrector(args: argparse.Namespace) -> int:
path = package_hf_text_corrector_model(
args.model_dir,
args.out,
model_id=args.model_id,
base_model=args.base_model,
base_engine=args.base_engine,
base_engine_kwargs=_parse_key_values(args.base_engine_kwarg),
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
metrics_report=args.metrics_report,
max_new_tokens=args.max_new_tokens,
)
print(path)
return 0
def cmd_generate_correction_pairs(args: argparse.Namespace) -> int:
path = generate_correction_pairs(
args.manifest,
args.out,
engine_name=args.engine,
model_config=args.model_config,
limit=args.limit,
only_errors=args.only_errors,
)
print(path)
return 0
def cmd_train_corrector(args: argparse.Namespace) -> int:
recipe_path = write_corrector_recipe(
args.out,
clean_manifest=args.clean_manifest,
pairs_source=args.pairs_source,
hf_dataset=args.hf_dataset,
hf_split=args.hf_split,
limit=args.limit,
seed=args.seed,
)
if args.backend == "recipe":
print(recipe_path)
return 0
path = write_hf_text_corrector_recipe(
Path(args.out) / "correction_pairs.jsonl",
args.out,
base_model=args.base_model,
max_source_length=args.max_source_length,
max_target_length=args.max_target_length,
per_device_train_batch_size=args.train_batch_size,
per_device_eval_batch_size=args.eval_batch_size,
learning_rate=args.learning_rate,
num_train_epochs=args.epochs,
eval_ratio=args.eval_ratio,
seed=args.seed,
run=args.run,
)
print(path)
return 0
def cmd_create_model_card(args: argparse.Namespace) -> int:
path = write_model_card(
args.out,
model_id=args.model_id,
backend=args.backend,
base_model=args.base_model,
artifact_paths=args.artifact,
backend_kwargs=_parse_key_values([*args.backend_kwarg, *args.paddleocr_kwarg]),
train_manifest=args.train_manifest,
eval_manifest=args.eval_manifest,
metrics_report=args.metrics_report,
admission_validation_report=args.admission_validation_report,
fallback_model_card=args.fallback_model_card,
notes=args.notes,
)
print(path)
return 0
def cmd_audit_model(args: argparse.Namespace) -> int:
audit = audit_model_card(args.model_config, args.out)
print(Path(args.out) / "model-audit.json")
print(Path(args.out) / "model-audit.md")
print(f"passed={audit.passed} model_id={audit.model_id}")
return 0 if audit.passed else 1
def cmd_parse_doc(args: argparse.Namespace) -> int:
document = parse_document(
args.input,
args.out,
engine_name=args.engine,
model_config=args.model_config,
fallback_engine=args.fallback_engine,
fallback_model_config=args.fallback_model_config,
low_confidence_threshold=args.low_confidence_threshold,
fallback_min_quality_score=args.fallback_min_quality_score,
)
print(Path(args.out) / "document.json")
print(Path(args.out) / "document.md")
print(f"pages={len(document.pages)} tables={len(document.tables)} figures={len(document.figures)}")
return 0
def cmd_benchmark(args: argparse.Namespace) -> int:
baselines = [item.strip() for item in args.baselines.split(",") if item.strip()]
inputs = list(args.inputs)
if args.inputs_from_manifest:
inputs.extend(_benchmark_inputs_from_manifest(args.inputs_from_manifest))
if not inputs:
raise OcrTechError("benchmark requires positional inputs or --inputs-from-manifest")
eval_manifest = args.eval_manifest or args.inputs_from_manifest
results = run_benchmark(
inputs,
args.out,
baselines=baselines,
references_dir=args.references_dir,
eval_manifest=eval_manifest,
candidate_model_config=args.candidate_model_config,
fallback_engine=args.fallback_engine,
fallback_model_config=args.fallback_model_config,
low_confidence_threshold=args.low_confidence_threshold,
fallback_min_quality_score=args.fallback_min_quality_score,
resume_existing=args.resume_existing,
sample_timeout_seconds=args.sample_timeout_seconds,
capture_gpu_metrics=args.capture_gpu_metrics,
)
print(Path(args.out) / "report.json")
print(Path(args.out) / "report.md")
print(f"runs={len(results)}")
return 0
def _benchmark_inputs_from_manifest(manifest_path: str | Path) -> list[str]:
manifest = Path(manifest_path)
entries = load_manifest(manifest)
if not entries:
raise OcrTechError(f"benchmark input manifest is empty: {manifest}")
inputs: list[str] = []
for entry in entries:
raw_path = Path(entry.image_path)
if raw_path.is_absolute():
resolved = raw_path
elif raw_path.exists():
resolved = raw_path
else:
resolved = manifest.parent / raw_path
if not resolved.exists():
raise OcrTechError(f"benchmark input does not exist for sample {entry.sample_id}: {resolved}")
if resolved.is_dir():
raise OcrTechError(f"benchmark input is a directory for sample {entry.sample_id}: {resolved}")
inputs.append(str(resolved))
return inputs
def cmd_summarize_benchmark(args: argparse.Namespace) -> int:
summary = summarize_benchmark_report(
args.benchmark_report,
args.out,
candidate=args.candidate,
baselines=args.baseline or None,
metrics=args.metric or None,
)
print(Path(args.out) / "summary.json")
print(Path(args.out) / "summary.md")
print(f"candidate={summary.candidate} paired={len(summary.paired_metrics)}")
return 0
def cmd_rescore_benchmark(args: argparse.Namespace) -> int:
results = rescore_benchmark_report(
args.benchmark_report,
args.out,
references_dir=args.references_dir,
eval_manifest=args.eval_manifest,
)
print(Path(args.out) / "report.json")
print(Path(args.out) / "report.md")
print(f"runs={len(results)}")
return 0
def cmd_derive_table_postprocess_benchmark(args: argparse.Namespace) -> int:
results = derive_table_postprocess_benchmark(
args.benchmark_report,
args.out,
source_baseline=args.source_baseline,
candidate_baseline=args.candidate_baseline,
references_dir=args.references_dir,
eval_manifest=args.eval_manifest,
)
print(Path(args.out) / "report.json")
print(Path(args.out) / "report.md")
print(f"runs={len(results)}")
return 0
def cmd_analyze_table_cells(args: argparse.Namespace) -> int:
analysis = analyze_table_cells(
args.benchmark_report,
args.eval_manifest,
args.out,
candidate=args.candidate,
baselines=args.baseline or None,
top_n=args.top_n,
)
print(Path(args.out) / "table-cell-analysis.json")
print(Path(args.out) / "table-cell-analysis.md")
print(f"systems={len(analysis.systems)} paired={len(analysis.paired)} failures={len(analysis.top_failures)}")
return 0
def cmd_paper_benchmark_table(args: argparse.Namespace) -> int:
display_names: dict[str, str] = {}
for item in args.label:
key, separator, value = str(item).partition("=")
if not separator or not key or not value:
raise OcrTechError(f"invalid --label value {item!r}; expected system=Label")
display_names[key] = value
source_preferences: dict[str, str] = {}
for item in args.source_preference:
key, separator, value = str(item).partition("=")
if not separator or not key or not value:
raise OcrTechError(f"invalid --source-preference value {item!r}; expected system=path")
source_preferences[key] = value
table = export_paper_benchmark_table(
args.summary,
args.out,
slice_name=args.slice,
metrics=args.metric or None,
systems=args.system or None,
display_names=display_names,
source_preferences=source_preferences,
title=args.title,
)
print(Path(args.out) / "paper-table.json")
print(Path(args.out) / "paper-table.md")
print(f"rows={len(table.rows)} slice={table.slice_name}")
return 0
def cmd_benchmark_oracle(args: argparse.Namespace) -> int:
report, summary = build_benchmark_oracle(
args.benchmark_report,
args.out,
metric=args.metric,
systems=args.system or None,
direction=args.direction,
oracle_name=args.oracle_name,
)
print(Path(args.out) / "oracle-analysis.json")
print(Path(args.out) / "oracle-analysis.md")
print(Path(args.out) / "oracle-choices.json")
print(Path(args.out) / "oracle-summary" / "summary.json")
print(f"oracle={report.oracle_name} samples={report.sample_count} paired={len(summary.paired_metrics)}")
return 0
def cmd_benchmark_error_analysis(args: argparse.Namespace) -> int:
analysis = analyze_benchmark_errors(
args.benchmark_report,
args.out,
system=args.system,
baselines=args.baseline or None,
metric=args.metric,
direction=args.direction,
top_n=args.top_n,
)
print(Path(args.out) / "error-analysis.json")
print(Path(args.out) / "error-analysis.md")
print(Path(args.out) / "top-failures.json")
print(f"system={analysis.system} samples={analysis.sample_count} metric={analysis.metric}")
return 0
def cmd_export_failure_manifest(args: argparse.Namespace) -> int:
export = export_failure_manifest(
args.source_manifest,
args.top_failures,
args.out,
split=args.split,
)
print(export.output_manifest)
print(export.summary_path)
print(f"selected={export.selected_count} split={export.split or ''}")
return 0
def cmd_calibrate_quality_router(args: argparse.Namespace) -> int:
calibration, model_path = calibrate_quality_router(
args.experiment_report,
args.out,
model_id=args.model_id,
base_model=args.base_model,
primary_engine=args.primary_engine,
secondary_engine=args.secondary_engine,
primary_engine_kwargs=_parse_key_values(args.primary_engine_kwarg),
secondary_engine_kwargs=_parse_key_values(args.secondary_engine_kwarg),
candidate_baseline=args.candidate_baseline,
primary_baseline=args.primary_baseline,
metric=args.metric,
direction=args.direction,
threshold_start=args.threshold_start,
threshold_end=args.threshold_end,
threshold_step=args.threshold_step,
notes=args.notes,
)
print(Path(args.out) / "calibration.json")
print(Path(args.out) / "calibration.md")
print(model_path)
print(f"selected_threshold={calibration.selected_threshold:.6f}")
return 0
def cmd_calibrate_script_router(args: argparse.Namespace) -> int:
calibration, model_path = calibrate_script_router(
args.experiment_report,
args.out,
model_id=args.model_id,
base_model=args.base_model,
primary_engine=args.primary_engine,
secondary_engine=args.secondary_engine,
primary_engine_kwargs=_parse_key_values(args.primary_engine_kwarg),
secondary_engine_kwargs=_parse_key_values(args.secondary_engine_kwarg),
primary_baseline=args.primary_baseline,
secondary_baseline=args.secondary_baseline,
metric=args.metric,
direction=args.direction,
script=args.script,
threshold_start=args.threshold_start,
threshold_end=args.threshold_end,
threshold_step=args.threshold_step,
routing_granularity=args.routing_granularity,
secondary_structure_backfill=args.secondary_structure_backfill,
notes=args.notes,
)
print(Path(args.out) / "calibration.json")
print(Path(args.out) / "calibration.md")
print(model_path)
print(f"selected_threshold={calibration.selected_threshold:.6f}")
return 0
def cmd_calibrate_tesseract_psm_ensemble(args: argparse.Namespace) -> int:
report, model_path = calibrate_tesseract_psm_ensemble(
args.primary_experiment_report,
args.out,
model_id=args.model_id,
variant_experiment_reports=_parse_labeled_paths(args.variant_experiment),
metric=args.metric,
direction=args.direction,
bias_start=args.bias_start,
bias_end=args.bias_end,
bias_step=args.bias_step,
language=args.language,
selection_margin=args.selection_margin,
notes=args.notes,
)
print(Path(args.out) / "calibration.json")
print(Path(args.out) / "calibration.md")
print(model_path)
print(f"selected_biases={report.selected_biases}")
return 0
def cmd_run_experiment(args: argparse.Namespace) -> int:
baselines = [item.strip() for item in args.baselines.split(",") if item.strip()]
report = run_experiment(
args.eval_manifest,
args.out,
baselines=baselines,
references_dir=args.references_dir,
validation_config=args.validation_config,
candidate_model_config=args.candidate_model_config,
fallback_engine=args.fallback_engine,
fallback_model_config=args.fallback_model_config,
low_confidence_threshold=args.low_confidence_threshold,
fallback_min_quality_score=args.fallback_min_quality_score,
train_manifests=args.train_manifest,
run_validation=not args.skip_validation,
run_preflight=args.preflight,
require_claim_ready_eval_pack=not args.allow_smoke_eval_pack,
require_trained_recognizer=args.require_trained_recognizer,
require_model_admission=args.require_model_admission,
)
print(Path(args.out) / "experiment.json")
print(Path(args.out) / "experiment.md")
print(f"benchmark={report.benchmark_report}")
print(f"validation={report.validation_status or 'not_run'}")
if args.require_validated and report.validation_status != "validated":
return 1
return 0
def cmd_preflight_claim(args: argparse.Namespace) -> int:
baselines = [item.strip() for item in args.baselines.split(",") if item.strip()]
report = run_claim_preflight(
args.eval_manifest,
args.out,
baselines=baselines,
references_dir=args.references_dir,
candidate_model_config=args.candidate_model_config,
fallback_model_config=args.fallback_model_config,
train_manifests=args.train_manifest,
validation_config=args.validation_config,
require_claim_ready_eval_pack=not args.allow_smoke_eval_pack,
require_trained_recognizer=args.require_trained_recognizer,
require_model_admission=args.require_model_admission,
)
print(Path(args.out) / "preflight.json")
print(Path(args.out) / "preflight.md")
print(f"passed={report.passed} samples={report.sample_count}")
return 0 if report.passed else 1
def cmd_audit_remote_host(args: argparse.Namespace) -> int:
min_python = _parse_python_version(args.min_python)
report = audit_remote_host(
args.host,
args.out,
user=args.user,
port=args.port,
password_env=args.password_env,
min_python=min_python,
min_free_gb=args.min_free_gb,
workdir=args.workdir,
require_gpu=args.require_gpu,
require_paddle_training=args.require_paddle_training,
python_candidates=args.python_candidate or DEFAULT_PYTHON_CANDIDATES,
require_commands=args.require_command or None,
optional_commands=args.optional_command or None,
require_paths=args.require_path,
)
print(Path(args.out) / "remote-audit.json")
print(Path(args.out) / "remote-audit.md")
print(f"passed={report.passed} host={report.host}")
return 0 if report.passed else 1
def cmd_bootstrap_remote_host(args: argparse.Namespace) -> int:
min_python = _parse_python_version(args.min_python)
report = bootstrap_remote_host(
args.host,
args.out,
user=args.user,
port=args.port,
password_env=args.password_env,
workdir=args.workdir,
min_python=min_python,
python_candidates=args.python_candidate or DEFAULT_PYTHON_CANDIDATES,
venv_name=args.venv_name,
recreate_venv=args.recreate_venv,
)
print(Path(args.out) / "remote-bootstrap.json")
print(Path(args.out) / "remote-bootstrap.md")
print(f"passed={report.passed} workdir={report.workdir} venv={report.venv_dir}")
return 0 if report.passed else 1
def cmd_sync_remote_workspace(args: argparse.Namespace) -> int:
report = sync_remote_workspace(
args.local_root,
args.out,
host=args.host,
user=args.user,
port=args.port,
password_env=args.password_env,
remote_workdir=args.remote_workdir,
exclude_patterns=args.exclude or None,
)
print(Path(args.out) / "remote-sync.json")
print(Path(args.out) / "remote-sync.md")
print(f"passed={report.passed} remote_workdir={report.remote_workdir}")
return 0 if report.passed else 1
def cmd_review_claim(args: argparse.Namespace) -> int:
report = review_claim(
args.experiment,
args.out,
config_path=args.config,
model_config=args.model_config,
)
print(Path(args.out) / "claim-review.json")
print(Path(args.out) / "claim-review.md")
print(f"passed={report.passed} experiments={len(report.experiments)}")
return 0 if report.passed else 1
def cmd_validate_claim(args: argparse.Namespace) -> int:
report = validate_claim(
args.benchmark_report,
args.out,
config_path=args.config,
eval_manifest=args.eval_manifest,
train_manifests=args.train_manifest,
candidate_model_config=args.candidate_model_config,
fallback_model_config=args.fallback_model_config,
)
print(Path(args.out) / "validation.json")
print(Path(args.out) / "validation.md")
print(f"status={report.claim_status}")
if not report.passed:
return 1
return 0
def cmd_recognizer_admission_decision(args: argparse.Namespace) -> int:
decision = decide_recognizer_admission(args.validation_report, args.out)
print(Path(args.out) / "recognizer-admission-decision.json")
print(Path(args.out) / "recognizer-admission-decision.md")
print(f"decision={decision.decision} status={decision.claim_status}")
return 0 if decision.decision == "admit" else 1
def cmd_recognizer_failure_review(args: argparse.Namespace) -> int:
review = review_recognizer_failures(
args.admission_decision,
args.validation_report,
args.out,
model_cards=args.model_card,
min_rejections_to_stop=args.min_rejections_to_stop,
)
stopped_count = sum(1 for family in review.families if family.recommendation == "stop_family")
print(Path(args.out) / "recognizer-failure-review.json")
print(Path(args.out) / "recognizer-failure-review.md")
print(f"families={len(review.families)} stopped={stopped_count}")
return 1 if stopped_count else 0
def cmd_list_public_benchmarks(args: argparse.Namespace) -> int:
_ = args
for spec in list_public_benchmarks():
print(f"{spec.dataset}\t{spec.title}\tmin_samples={spec.min_samples}\t{spec.url}")
return 0
def cmd_prepare_public_benchmark(args: argparse.Namespace) -> int:
report = prepare_public_benchmark(
args.benchmark,
args.out,
limit=args.limit,
language=args.language,
subset=args.subset,
data_source=args.data_source,
require_tables=args.require_tables,
annotation_path=args.annotation_path,
local_image_root=args.local_image_root,
)
print(report.summary_json_path)
print(report.summary_md_path)
print(f"manifest={report.manifest_path} samples={report.sample_count} benchmark={report.benchmark}")
return 0
def cmd_audit_public_benchmark(args: argparse.Namespace) -> int:
audit = audit_public_benchmark_manifest(
args.manifest,
args.out,
benchmark=args.benchmark,
min_samples=args.min_samples,
require_reference_paths=not args.allow_missing_reference_paths,
)
print(Path(args.out) / "public-benchmark-audit.json")
print(Path(args.out) / "public-benchmark-audit.md")
print(f"passed={audit.passed} samples={audit.sample_count} benchmark={audit.benchmark}")
return 0 if audit.passed else 1
def cmd_audit_gorkhapatra_source(args: argparse.Namespace) -> int:
category_urls = list(args.category_url)
epaper_urls = list(args.epaper_url)
if not args.no_default_urls:
if not category_urls and not args.category_html:
category_urls = list(DEFAULT_GORKHAPATRA_CATEGORY_URLS)
if not epaper_urls and not args.epaper_html:
epaper_urls = [DEFAULT_GORKHAPATRA_EPAPER_URL]
audit = audit_gorkhapatra_source(
args.out,
category_urls=category_urls,
epaper_urls=epaper_urls,
category_html_paths=args.category_html,
epaper_html_paths=args.epaper_html,
download_assets=args.download_assets,
max_article_images=args.max_article_images,
max_epaper_pdfs=args.max_epaper_pdfs,
timeout_seconds=args.timeout_seconds,
)
print(Path(args.out) / "gorkhapatra-source-audit.json")
print(Path(args.out) / "gorkhapatra-source-audit.md")
print(f"articles={audit.article_count} epapers={audit.epaper_count} downloaded={audit.downloaded_count} warnings={len(audit.warnings)}")
return 0
def cmd_prepare_gorkhapatra_pack(args: argparse.Namespace) -> int:
summary = prepare_gorkhapatra_pack(
args.source_audit_json,
args.out,
include_article_images=not args.no_article_images,
include_epaper_pages=not args.no_epaper_pages,
max_article_images=args.max_article_images,
max_epaper_pdfs=args.max_epaper_pdfs,
max_pages_per_pdf=args.max_pages_per_pdf,
split=args.split,
dataset_name=args.dataset_name,
)
print(summary.manifest_path)
print(Path(args.out) / "gorkhapatra-pack.json")
print(Path(args.out) / "gorkhapatra-pack.md")
print(f"samples={summary.sample_count} article_images={summary.article_image_count} epaper_pages={summary.epaper_page_count}")
return 0
def cmd_audit_gorkhapatra_language_pages(args: argparse.Namespace) -> int:
publication_urls = list(args.publication_url)
epaper_urls = list(args.epaper_url)
if not args.no_default_urls:
if not publication_urls and not args.publication_html:
publication_urls = [DEFAULT_NAYA_NEPAL_PUBLICATION_URL]
if not epaper_urls and not args.epaper_html:
epaper_urls = [DEFAULT_GORKHAPATRA_EPAPER_URL]
audit = audit_gorkhapatra_language_pages(
args.out,
publication_urls=publication_urls,
epaper_urls=epaper_urls,
publication_html_paths=args.publication_html,
epaper_html_paths=args.epaper_html,
download_pdfs=args.download_pdfs,
render_pages=args.render_pages,
max_publication_items=args.max_publication_items,
max_epaper_pdfs=args.max_epaper_pdfs,
timeout_seconds=args.timeout_seconds,
)
print(Path(args.out) / "gorkhapatra-language-pages.json")
print(Path(args.out) / "gorkhapatra-language-pages.md")
print(
f"publication_items={audit.publication_item_count} "
f"aligned={audit.aligned_count} language_page_hits={audit.language_page_hit_count} warnings={len(audit.warnings)}"
)
return 0
def cmd_prepare_gorkhapatra_language_page_pack(args: argparse.Namespace) -> int:
summary = prepare_gorkhapatra_language_page_pack(
args.language_page_audit_json,
args.out,
split=args.split,
dataset_name=args.dataset_name,
max_samples=args.max_samples,
)
print(summary.manifest_path)
print(Path(args.out) / "gorkhapatra-language-page-pack.json")
print(Path(args.out) / "gorkhapatra-language-page-pack.md")
print(f"samples={summary.sample_count} copied_pages={summary.copied_page_count} warnings={len(summary.warnings)}")
return 0
def cmd_prepare_gorkhapatra_language_page_review(args: argparse.Namespace) -> int:
summary = prepare_gorkhapatra_language_page_review(
args.language_page_pack_manifest,
args.out,
)
print(summary.review_json_path)
print(summary.review_csv_path)
print(summary.review_md_path)
print(
f"samples={summary.sample_count} pending_review={summary.pending_review_count} "
f"claim_eligible={summary.claim_evidence_eligible_count} warnings={len(summary.warnings)}"
)
return 0
def cmd_audit_language_registry(args: argparse.Namespace) -> int:
audit = audit_language_registry(
args.registry,
args.out,
min_nepal_languages=args.min_nepal_languages,
require_limbu_first=not args.allow_non_limbu_first,
verify_local_paths=not args.no_verify_local_paths,
)
print(Path(args.out) / "language-registry-audit.json")
print(Path(args.out) / "language-registry-audit.md")
print(
"passed="
f"{audit.passed} languages={audit.language_count} "
f"nepal_languages={audit.counted_nepal_language_count} first_targets={','.join(audit.first_target_ids)}"
)
return 0 if audit.passed else 1
def cmd_audit_font_renderability(args: argparse.Namespace) -> int:
audit = audit_font_renderability(
args.registry,
args.out,
primary_only=not args.all_scripts,
min_coverage_ratio=args.min_coverage_ratio,
render_samples=args.render_samples,
)
print(Path(args.out) / "font-renderability-audit.json")
print(Path(args.out) / "font-renderability-audit.md")
print(
"passed="
f"{audit.passed} scripts={audit.script_count} candidates={audit.candidate_count} "
f"rendered={sum(1 for candidate in audit.candidates if candidate.render_status == 'rendered')}"
)
return 0 if audit.passed else 1
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
try:
return int(args.func(args))
except OcrTechError as exc:
print(f"ocrtech: error: {exc}", file=sys.stderr)
return 2
def _parse_key_values(values: list[str]) -> dict[str, object]:
parsed: dict[str, object] = {}
for item in values:
if "=" not in item:
raise OcrTechError(f"expected key=value for --paddleocr-kwarg, got {item!r}")
key, value = item.split("=", 1)
if not key:
raise OcrTechError("paddleocr kwarg key cannot be empty")
parsed[key] = _coerce_scalar(value)
return parsed
def _parse_labeled_paths(values: list[str]) -> dict[str, str]:
parsed: dict[str, str] = {}
for item in values:
if "=" not in item:
raise OcrTechError(f"expected label=path, got {item!r}")
label, path = item.split("=", 1)
if not label or not path:
raise OcrTechError(f"expected non-empty label=path, got {item!r}")
parsed[label] = path
return parsed
def _coerce_scalar(value: str) -> object:
stripped = value.strip()
if stripped.startswith("{") or stripped.startswith("["):
try:
return json.loads(stripped)
except json.JSONDecodeError:
pass
lowered = value.lower()
if lowered == "true":
return True
if lowered == "false":
return False
if lowered == "none":
return None
try:
return int(value)
except ValueError:
try:
return float(value)
except ValueError:
return value
def _parse_python_version(value: str) -> tuple[int, int]:
parts = value.strip().split(".")
if len(parts) != 2:
raise OcrTechError(f"expected MINOR python version like 3.11, got {value!r}")
try:
major = int(parts[0])
minor = int(parts[1])
except ValueError as exc:
raise OcrTechError(f"python version must be numeric, got {value!r}") from exc
if major < 1 or minor < 0:
raise OcrTechError(f"invalid python version: {value!r}")
return major, minor
if __name__ == "__main__":
raise SystemExit(main())
"""Command-line interface for ocrtech."""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
from .admission import assert_recognizer_family_not_stopped, decide_recognizer_admission, review_recognizer_failures
from .benchmark import derive_table_postprocess_benchmark, rescore_benchmark_report, run_benchmark, summarize_benchmark_report
from .calibration import calibrate_quality_router, calibrate_script_router, calibrate_tesseract_psm_ensemble
from .claim_review import review_claim
from .crops import extract_crop_manifest
from .datasets import audit_manifest, audit_recognizer_corpus, build_recognizer_corpus, filter_manifest, merge_manifests, rebalance_manifest, split_manifest
from .error_analysis import analyze_benchmark_errors, export_failure_manifest
from .errors import OcrTechError
from .evalpack import audit_eval_pack, create_eval_pack
from .experiments import run_experiment
from .language_registry import audit_font_renderability, audit_language_registry
from .manifest import inspect_hf_dataset, load_manifest, normalize_manifest_images, prepare_hf_dataset, prepare_local_dataset
from .models import audit_model_card, write_model_card
from .oracle import build_benchmark_oracle
from .paper import export_paper_benchmark_table
from .pipeline import parse_document
from .preflight import run_claim_preflight
from .public_benchmarks import audit_public_benchmark_manifest, list_public_benchmarks, prepare_public_benchmark
from .references import materialize_references
from .remote import DEFAULT_PYTHON_CANDIDATES, audit_remote_host, bootstrap_remote_host, sync_remote_workspace
from .source_audit import (
DEFAULT_GORKHAPATRA_CATEGORY_URLS,
DEFAULT_GORKHAPATRA_EPAPER_URL,
DEFAULT_NAYA_NEPAL_PUBLICATION_URL,
audit_gorkhapatra_language_pages,
audit_gorkhapatra_source,
prepare_gorkhapatra_language_page_review,
prepare_gorkhapatra_language_page_pack,
prepare_gorkhapatra_pack,
)
from .table_analysis import analyze_table_cells
from .training import (
PADDLE_DEVANAGARI_PPOCRV3_PRETRAINED,
bundle_recognizer_training,
finalize_hf_recognizer_run,
generate_correction_pairs,
package_hf_text_corrector_model,
package_hf_recognizer_model,
package_paddleocr_model,
write_corrector_recipe,
write_hf_text_corrector_recipe,
write_hf_recognizer_recipe,
write_recognizer_export_recipe,
write_recognizer_recipe,
)
from .validation import validate_claim
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="ocrtech", description="Nepali + English OCR document parser")
subparsers = parser.add_subparsers(dest="command", required=True)
prepare = subparsers.add_parser("prepare-data", help="download/verify/convert datasets into manifests")
prepare.add_argument("source", help="local CSV/JSONL/directory or Hugging Face dataset id")
prepare.add_argument("--out", default="data/manifests", help="output manifest directory")
prepare.add_argument("--dataset-name", help="manifest dataset name")
prepare.add_argument("--split", default="train", help="dataset split")
prepare.add_argument("--image-field", help="explicit image field")
prepare.add_argument("--text-field", help="explicit text field")
prepare.add_argument("--hf-subset", help="known HF dataset subset/language selector (for example: en)")
prepare.add_argument("--limit", type=int, help="max rows to convert")
prepare.add_argument("--hf", action="store_true", help="load source with Hugging Face datasets")
prepare.add_argument("--skip-invalid", action="store_true", help="skip invalid rows and write a reject report")
prepare.add_argument("--strict-chars", action="store_true", help="reject unsupported dictionary characters")
prepare.add_argument("--slice", action="append", default=[], help="slice label to stamp into manifest metadata; repeatable")
prepare.set_defaults(func=cmd_prepare_data)
inspect_hf = subparsers.add_parser("inspect-hf-dataset", help="inspect a Hugging Face dataset schema before manifest conversion")
inspect_hf.add_argument("dataset_id", help="Hugging Face dataset id")
inspect_hf.add_argument("--out", default="outputs/hf-dataset-inspection")
inspect_hf.add_argument("--split", default="train")
inspect_hf.add_argument("--hf-subset", help="dataset subset/language selector")
inspect_hf.add_argument("--image-field", help="explicit image field")
inspect_hf.add_argument("--text-field", help="explicit text field")
inspect_hf.add_argument("--limit", type=int, default=3)
inspect_hf.set_defaults(func=cmd_inspect_hf_dataset)
audit_manifest_parser = subparsers.add_parser("audit-manifest", help="audit a training or evaluation manifest")
audit_manifest_parser.add_argument("manifest")
audit_manifest_parser.add_argument("--out", default="outputs/manifest-audit")
audit_manifest_parser.add_argument("--no-verify-hashes", action="store_true")
audit_manifest_parser.add_argument("--require-slice", action="append", default=[])
audit_manifest_parser.add_argument("--strict-chars", action="store_true")
audit_manifest_parser.set_defaults(func=cmd_audit_manifest)
split = subparsers.add_parser("split-manifest", help="create deterministic leakage-safe train/eval manifests")
split.add_argument("manifest")
split.add_argument("--out", default="data/splits")
split.add_argument("--eval-ratio", type=float, default=0.15)
split.add_argument("--seed", type=int, default=13)
split.add_argument("--stratify-by", choices=["slices", "dataset", "document_type", "none"], default="slices")