ocr-tech-k2 / src /ocrtech /cli.py
prosperious's picture
Add 195 files (runs/hf-recognizer-mixed-v2-full/finalized/package/artifacts/model/model.safetensors ...)
1ef1de7 verified
Raw History Blame Contribute Delete
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")