---
library_name: coreml
license: openrail
base_model: Reza2kn/Bina-0.1-Koochik
base_model_relation: quantized
pipeline_tag: image-to-text
tags:
  - coreml
  - apple-silicon
  - ocr
  - persian
  - qwen3_5
  - surya-ocr
---

# Bina 0.1 CoreML — بینا ۰.۱ برای CoreML

This is the fixed-512 CoreML runtime for
[`Reza2kn/Bina-0.1-Koochik`](https://huggingface.co/Reza2kn/Bina-0.1-Koochik),
the merged BF16 Persian OCR baseline.

## Precision: BF16 source, mixed CoreML runtime

This is **not** labeled as a literal BF16 CoreML model. Core ML Tools 9.0 does
not expose BF16 as an ML Program compute precision. The parity-qualified build
uses:

- vision encoder: CoreML **FP32**;
- language prefill: CoreML **FP16**;
- autoregressive decode step: CoreML **FP16**;
- host token embeddings and M-RoPE tables: **FP32**.

An all-FP16 attempt was rejected because FP16 vision changed the first greedy
token. Keeping vision in FP32 restored exact greedy transcripts while retaining
FP16 for the two large language graphs.

## Parity evidence

All comparisons use deterministic greedy decoding, EOS token `2`, the same
BF16 source checkpoint, and the exact Bina transcription prompt:

```text
OCR this image. Return only the exact text visible in the image, preserving Persian, numbers, line breaks, and punctuation. Do not explain.
```

| Gate | Result |
| --- | ---: |
| Synthetic compiled CoreML canary | 22/22 tokens exact through EOS |
| Two real Persian pages | 128/128 checked tokens exact (64-token cap per page) |
| Real Persian line crop, Python-hosted CoreML | 25/25 tokens and text exact through EOS |
| Same Persian crop, native Swift host | 25/25 tokens and text exact through EOS |

The native crop transcript is exactly:

```text
گزارش سالانه دیتاک -۱۴۰۲
```

Receipts are under [`validation/`](validation/). The Swift receipt exercises
the actual CoreML packages, FP32 host assets, cache updates, baked M-RoPE tables,
Fuse tokenizer decoding, and EOS stopping without loading the PyTorch model.

## Runtime contract

This release intentionally has one static shape:

- centered white `512 × 512` RGB canvas;
- `pixel_values`: `[1024, 1536]`, Float32;
- 256 merged image tokens;
- prompt length: 416 tokens;
- M-RoPE delta: `-240` (baked into the native decode tables);
- cache length: 1024;
- maximum generated length before the cache boundary: 608 tokens.

The qualified preprocessing path is PIL RGB + LANCZOS aspect-fit into the
centered white canvas, followed by the checked-in processor. The Swift
`generate(pixelValues:)` path is parity-qualified. The convenience Swift
`generate(image:)` path uses CoreGraphics and is **not** claimed to be
pixel-identical to PIL.

This is not yet the six-aspect-bucket Bina/Flax runtime and is not a drop-in
replacement for every dynamic Surya page shape. Use this release only for the
fixed-512 contract above.

## Files

- `surya_vision_fp32.mlpackage` — Bina-specific vision encoder.
- `surya_prefill_fp16_seq416_cache1024.mlpackage` — language prefill and initial cache.
- `surya_decode_step_fp16_cache1024.mlpackage` — one autoregressive decode step.
- `native_assets/` — FP32 token embedding, prompt embeddings, M-RoPE tables,
  tokenizer vocabulary, constants, and a synthetic canary tensor.
- `native/SuryaCoreMLRuntime/` — Swift Package for macOS 14+ / iOS 17+.
- `processor/` — exact tokenizer and processor configuration.
- `scripts/` — conversion, fixture preparation, and parity validators.

The internal `Surya` names reflect the upstream architecture; all three graphs
contain the Bina 0.1 fine-tuned weights.

## Native smoke test

Clone with Git LFS, then run the release build from the repository root:

```bash
git lfs install
git lfs pull

cd native/SuryaCoreMLRuntime
swift run -c release surya-coreml-smoke \
  --model-dir ../.. \
  --pixel-values-fp32 ../../native_assets/canary_pixel_values_fp32.bin \
  --max-tokens 64
```

Expected token IDs:

```text
2009 2046 2054 2047 2041 2035 2037 1979 136 1072 2020 2047 2052 2033 2044 1979 1982 55 1992 13 13 2
```

Expected text:

```text
Invoice 123<br/>Total $42.00
```

To prepare an exact fixed-512 tensor for another image:

```bash
python scripts/prepare_bina_coreml_fixtures.py \
  --runtime-script scripts/export_surya_coreml_runtime.py \
  --image /path/to/image.png \
  --output-dir prepared
```

Then pass `prepared/<stem>.pixel_values_fp32.bin` to the Swift executable.

## Source provenance

- source model: `Reza2kn/Bina-0.1-Koochik`;
- source revision: `9b5812be94e3e015142da22a4b61b34aad5d2c02`;
- source `model.safetensors` SHA-256:
  `2193be4ef3d2366438121a15b7a1dea2bb85b24f83145e5a39bfa1f387891ada`;
- source `config.json` SHA-256:
  `e0de22be177070f206106c184d062176fcda591d9114068c42489ffc550488de`;
- architecture: `Qwen3_5ForConditionalGeneration`;
- conversion host: Apple M2, macOS 26.5.1;
- toolchain: Python 3.11.11, PyTorch 2.12.0, Transformers 5.13.1,
  Core ML Tools 9.0, Xcode 26.5.

Package and native-asset hashes are recorded in
[`coreml_runtime_manifest.json`](coreml_runtime_manifest.json).

## خلاصه فارسی

این مخزن نسخهٔ CoreML مدل بینا ۰.۱ است. وزن مبدأ BF16 است، اما چون CoreML
خروجی محاسباتی BF16 ارائه نمی‌کند، انکودر تصویر با FP32 و بخش زبانی با FP16
تبدیل شده است. در آزمون واقعی فارسی، خروجی CoreML و مدل اصلی BF16 تا توکن EOS
کاملاً یکسان بود؛ همین آزمون با میزبان Swift نیز ۲۵ از ۲۵ توکن و متن دقیقاً
یکسان داد. این نسخه فعلاً فقط قرارداد ثابت ۵۱۲×۵۱۲ را پشتیبانی می‌کند.

## License

This derivative follows the source model's OpenRAIL license. Review the source
and upstream Surya OCR 2 terms before redistribution or deployment.