Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.md linguist-detectable=true

AGENTS.md

@@ -0,0 +1,53 @@
+# Agent / tool guidance for mlx-vision
+
+## What this repo is
+Python library **mlx-vision**: DSpark-style speculative decoding for **OCR VLMs on Apple Silicon (MLX)**.
+Counterpart to text-only [mlx-dspark](https://github.com/ARahim3/mlx-dspark). Built on [mlx-vlm](https://github.com/Blaizzy/mlx-vlm).
+
+## When to use
+- Faster local OCR on Mac (M-series) for DeepSeek-OCR-2, GLM-OCR, Unlimited-OCR
+- Speculative decoding: `baseline` | `dspark` | `lookup` | `dflash` | `eagle3` | `mtp` | `auto`
+- PDF page OCR via `pypdfium2` (`pip install 'mlx-vision[pdf]'`)
+
+## Install
+```bash
+pip install mlx-vision
+# from source:
+pip install -e ".[pdf,dev]"
+```
+
+## Quick commands
+```bash
+mlx-vision models
+mlx-vision -m deepseek-ocr-2 -i page.png --mode auto -v
+mlx-vision -m deepseek-ocr-2 -i doc.pdf --page 0 --dpi 200
+mlx-vision bench --image page.png --modes baseline,lookup,dspark
+mlx-vision serve --port 8080
+```
+
+## Python
+```python
+from mlx_vision import ocr
+r = ocr("page.png", model="deepseek-ocr-2", mode="auto")
+```
+
+## Important caveats (do not skip)
+1. **No public OCR DSpark weights yet** — `--mode dspark` uses training-free semi-AR lookup + confidence schedule until drafters are trained (`scripts/train_drafter/`).
+2. DeepSeek-OCR MLX checkpoints trigger Torch remote-code processor load; this package falls back to native MLX processors (`src/mlx_vision/load.py`) — do not “fix” by installing torch unless needed for training.
+3. Unlimited-OCR uses **R-SWA**; draft block size is clamped to the sliding window.
+4. Requires Apple Silicon + MLX (Metal).
+
+## Key paths
+| Path | Role |
+|------|------|
+| `src/mlx_vision/generate.py` | `ocr()` API |
+| `src/mlx_vision/load.py` | Robust model/processor load |
+| `src/mlx_vision/speculative/` | DSpark/DFlash/confidence/lookup |
+| `src/mlx_vision/models/registry.py` | Presets + drafter registry |
+| `src/mlx_vision/pdf.py` | PDF → PNG |
+| `scripts/train_drafter/` | DeepSpec OCR drafter recipe |
+
+## Related
+- GitHub: https://github.com/will702/mlx-vision
+- Hugging Face: https://huggingface.co/will702/mlx-vision
+- Upstream OCR weights: `mlx-community/DeepSeek-OCR-2-*`, `mlx-community/GLM-OCR-*`, `baidu/Unlimited-OCR`

CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+title: "mlx-vision"
+message: "If you use mlx-vision, please cite it as below."
+type: software
+authors:
+  - family-names: "Willson"
+    given-names: "Gregorius"
+    alias: "will702"
+repository-code: "https://github.com/will702/mlx-vision"
+url: "https://huggingface.co/will702/mlx-vision"
+abstract: >-
+  DSpark-style speculative decoding for OCR vision-language models on
+  Apple Silicon via MLX. Speeds up DeepSeek-OCR-2, GLM-OCR, and Unlimited-OCR
+  with lossless target verification when neural drafters are available.
+keywords:
+  - mlx
+  - ocr
+  - speculative-decoding
+  - dspark
+  - apple-silicon
+  - deepseek-ocr
+license: MIT
+version: 0.1.0
+date-released: "2026-07-28"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 faster-inference-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,71 @@
+---
+title: mlx-vision
+emoji: 👁️
+colorFrom: blue
+colorTo: green
+sdk: static
+pinned: false
+license: mit
+tags:
+  - mlx
+  - ocr
+  - apple-silicon
+  - speculative-decoding
+  - dspark
+  - deepseek-ocr
+  - glm-ocr
+  - vision-language-model
+  - region:us
+library_name: mlx-vision
+pipeline_tag: image-to-text
+---
+
+# mlx-vision
+
+**DSpark-style faster OCR on Apple Silicon (MLX).**
+
+Speculative decoding for OCR VLMs — DeepSeek-OCR-2, GLM-OCR, Unlimited-OCR.
+Vision/OCR counterpart to [mlx-dspark](https://github.com/ARahim3/mlx-dspark).
+
+| Resource | Link |
+|----------|------|
+| **Code** | [github.com/will702/mlx-vision](https://github.com/will702/mlx-vision) |
+| **Agents** | [AGENTS.md](https://github.com/will702/mlx-vision/blob/main/AGENTS.md) · [llms.txt](https://github.com/will702/mlx-vision/blob/main/llms.txt) |
+| **Weights used** | [`mlx-community/DeepSeek-OCR-2-8bit`](https://huggingface.co/mlx-community/DeepSeek-OCR-2-8bit), [`GLM-OCR`](https://huggingface.co/mlx-community/GLM-OCR-bf16), [`Unlimited-OCR`](https://huggingface.co/baidu/Unlimited-OCR) |
+
+## Install
+
+```bash
+pip install git+https://github.com/will702/mlx-vision.git
+# with PDF support:
+pip install "mlx-vision[pdf] @ git+https://github.com/will702/mlx-vision.git"
+```
+
+## Quick start
+
+```python
+from mlx_vision import ocr
+
+result = ocr("document.png", model="deepseek-ocr-2", mode="auto")
+print(result.text)
+```
+
+```bash
+mlx-vision -m deepseek-ocr-2 -i page.png --mode dspark -v
+mlx-vision -m deepseek-ocr-2 -i doc.pdf --page 0 --dpi 200
+```
+
+## Modes
+
+- `baseline` — mlx-vlm generate
+- `dspark` / `lookup` — training-free semi-AR draft + confidence schedule (OCR DSpark weights not public yet)
+- `dflash` / `eagle3` / `mtp` — neural speculation via mlx-vlm (`--drafter`)
+- `auto` — best available path
+
+## Cite
+
+See [CITATION.cff](https://github.com/will702/mlx-vision/blob/main/CITATION.cff). Related paper: [DSpark](https://arxiv.org/abs/2607.05147).
+
+## License
+
+MIT

llms.txt

@@ -0,0 +1,30 @@
+# mlx-vision
+
+> DSpark-style speculative decoding for OCR vision-language models on Apple Silicon (MLX).
+
+## Summary
+mlx-vision accelerates local OCR VLMs (DeepSeek-OCR-2, GLM-OCR, Unlimited-OCR) using speculative decoding inspired by DeepSeek DSpark. It wraps mlx-vlm with confidence-scheduled drafting, vision feature cache, PDF rasterization, CLI, and an OpenAI-compatible server.
+
+## Install
+pip install mlx-vision
+
+## CLI
+mlx-vision -m deepseek-ocr-2 -i page.png --mode auto -v
+mlx-vision -m deepseek-ocr-2 -i doc.pdf --page 0
+
+## Python
+from mlx_vision import ocr
+result = ocr("page.png", model="deepseek-ocr-2", mode="auto")
+
+## Modes
+baseline, lookup, dspark (training-free semi-AR until OCR drafters exist), dflash, eagle3, mtp, auto
+
+## Links
+- https://github.com/will702/mlx-vision
+- https://huggingface.co/will702/mlx-vision
+- https://github.com/Blaizzy/mlx-vlm
+- https://github.com/ARahim3/mlx-dspark
+- https://arxiv.org/abs/2607.05147 (DSpark)
+
+## Keywords
+mlx, apple-silicon, ocr, deepseek-ocr, glm-ocr, unlimited-ocr, speculative-decoding, dspark, dflash, vision-language-model, metal, faster-inference