Blame for README.md

---
language:
- fa
license: other
license_name: bina-0.4-rizeh
license_link: https://huggingface.co/Reza2kn/Bina-0.4-Rizeh/blob/51b8c314b0552b1884c1f0e28016cb12a143f637/README.md
base_model: Reza2kn/Bina-0.4-Rizeh
base_model_relation: quantized
pipeline_tag: image-to-text
tags:
- bina
- ocr
- int4
- coreml
---

# Bina0.4 Rizeh — CoreML-INT4

Quantized CTC reader components and experimental line-detector conversions of [the final release](https://huggingface.co/Reza2kn/Bina-0.4-Rizeh/tree/51b8c314b0552b1884c1f0e28016cb12a143f637), pinned at `51b8c314b0552b1884c1f0e28016cb12a143f637`. All five readers are included: body95k, short labels, printed, numeric/math and degraded scans. Original pipeline code and nonconverted dependencies remain in the source repository.

These are mixed-weight4-bit artifacts. They are not an all-INT4 document pipeline. The reference Python pipeline also uses Surya layout/order, native detector paths, table machinery and small admission/ordering models. No Sherpa-ONNX OCR support is claimed.

## Measured reader parity

Fresh uncompressed PyTorch2.10 CUDA baselines were generated for each published checkpoint. Each target uses the same300 frozen internal development crops (50 each: English, handwriting, mixed, newspaper, printed, synthetic). No text normalization is applied to parity. At least98% character parity is required in every bucket; exact-line agreement is reported separately in VALIDATION.json. These are development canaries, not held-out accuracy or full-page certification.

| Runtime | Reader components | Lowest bucket character parity |
|---|---:|---:|
| coreml-w4-block16 | 5/5 | 98.466% |

Mac timings were collected during concurrent conversion/browser work and are not controlled speed rankings. Linux CPU/CUDA results are host-specific; native Windows is untested. LiteRT was tested on Linux CPU, without an Android test device. Apple validation used an M2 Mac; iOS hardware was not tested.

## Page-pipeline limitation

The public release demo matched the original text in a small ONNX page test, and exact reader-cache reuse avoided recognition calls on its repeat. A broader public handwritten-table sample exposed a failure: the pure-W4 pipeline changed the output substantially even though line canaries passed. Therefore this bundle does **not** pass the full-page98% transcription gate and is not a drop-in fully qualified4-bit replacement for the production pipeline. Detector mask IoU is not transcription parity.

The experimental Python adapter preserves upstream crop geometry, routing and decoding. It also partitions an upstream geometry-reread cache by actual backend/weight hash, preventing cross-model cache reuse. Its optional image-only safety route uses original FP32 readers on color-separated handwritten pages, before OCR, avoiding a trial quantized pass. That route is mixed-precision and requires separate full-pipeline qualification. It does not make the pure-W4 model pass.

## Line-level use

Install requirements.txt, then run `python inference.py line.png --role body`. This expects one text line or an explicit line box through `Recognizer.read_line`; it does not detect or assemble a whole document. Persistent sessions and bounded exact-input caching are included. Widths are never squashed or truncated.

Inputs are64px-high float32 ink maps with aspect preserved, black=1/paper=0,20% vertical and30% horizontal margins measured in original line height. True widths retain masking semantics. CTC blank is0 and nonblank indices map to vocab.json. Persian visual-to-logical conversion follows the original rtl.py.

Core ML ML Program packages require iOS18/macOS15 or later. Inputs: pixels float32 `[B,1,64,W]`, widths int32 `[B]`; batch1..8 and width8..8192. Use CPU_AND_GPU. W4/block16 applies to compatible large weights, retaining floating operations where required. GPU-only/ANE placement is not claimed.

## Experimental detectors

Three detector roles are included under experimental-detectors/: combined main detector1000, rule-C line guard500 and the printed detector/head. Their procedural-dev heatmaps were compared against their original FP32 models. Their full geometry/table/transcription impact is unqualified. Do not replace the production detectors based on mask IoU alone.

## Provenance and licensing

Quantization did not alter the source repository. The aggregate model.safetensors was verified tensor-for-tensor against the published native core checkpoints. Each component records its exact source checkpoint SHA256 in quantization_config.json. MANIFEST.json hashes the shipped artifacts. No private calibration images, benchmark fixtures, or private prediction texts are shipped.

Original recognizer weights/code remain under the source release CC BY-NC4.0 terms; Surya-derived detector/layout components retain their upstream Surya model terms. These conversions grant no additional rights. Retain the original Bina/Indra/Surya attribution. See the source release model card for details.