Clarify IndicOCR usage and stage loading

Document page parsing and standalone stage inference. Correct model metadata, license links, and validation scope.

README.md

@@ -3,36 +3,69 @@ language:
 - en
 - as
 - bn
+- brx
+- doi
+- gu
 - hi
+- kn
+- ks
+- kok
+- mai
+- ml
+- mni
 - mr
+- ne
+- or
+- pa
+- sa
+- sat
+- sd
 - ta
 - te
+- ur
 tags:
 - mlx
 - ocr
 - document-parsing
+- layout-analysis
+- reading-order
 - indic
 library_name: mlx-vlm
 pipeline_tag: image-text-to-text
 license: other
 license_name: indic-open-model-license-1.0
-license_link: LICENSE
+license_link: LICENSE.md
 base_model: bodhan-ai/indic-ocr
 ---
 
-# indic-ocr-mlx
+# IndicOCR (MLX)
 
-MLX port of [bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
-(multilingual document parsing for English and 22 Indian languages).
-Same two-stage layout as upstream:
+Built with IndicOCR from Bodhan AI / AI4Bharat.
 
-| Stage | Dir | Model | Format |
-|-------|-----|-------|--------|
-| IndicDocLayout | `weights/layout` | PP-DocLayoutV3/RT-DETR, 37 classes + reading order | float32 |
-| IndicBlockOCR | `weights/ocr` | Qwen3.5-0.8B | bf16, not quantized |
+MLX conversion of [bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
+for document parsing on Apple Silicon. A page image becomes reading-ordered
+Markdown and per-block JSON, with equations in LaTeX and tables in HTML by default.
+
+This repository contains two models:
+
+| Stage | Directory | Model | Weights |
+|---|---|---|---|
+| Layout detection and reading order | `weights/layout` | IndicDocLayout: PP-DocLayoutV3 fine-tune, 37 classes, about 33M parameters | float32, 133 MB |
+| Block transcription | `weights/ocr` | IndicBlockOCR: Qwen3.5-0.8B fine-tune | BF16, 1.7 GB, not quantized |
+
+## Usage
+
+Use an [mlx-vlm](https://github.com/Blaizzy/mlx-vlm) checkout that includes
+`indic_ocr` and `pp_doclayout_v3` support. From that checkout:
+
+```sh
+python -m pip install -e .
+```
+
+Replace `page.png` with a document image:
 
 ```python
-from mlx_vlm.models.indic_ocr.pipeline import IndicOCRParser
+from mlx_vlm.models.indic_ocr import IndicOCRParser
 
 with IndicOCRParser.from_pretrained("HashNuke/indic-ocr-mlx") as parser:
     page = parser.parse("page.png")
@@ -41,16 +74,55 @@ print(page.markdown)
 page.save("page.json")
 ```
 
-Stages also load standalone with standard tooling:
+The pipeline detects and cleans the layout, resolves nested equations, and
+transcribes eligible blocks using greedy decoding. Skipped regions remain in
+the JSON with empty text. Closing the parser releases its model references.
+
+`page.save` writes the image name, dimensions, and block records; Markdown is
+available separately as `page.markdown`. Each block has a zero-based `order`,
+`label`, `type`, pixel-coordinate `bbox_xyxy` (`[x0, y0, x1, y1]`), confidence,
+and text.
+
+## Load individual stages
+
+The repository root is a two-stage wrapper, not a standalone OCR model.
+Download the repository and pass its local stage directories to the loaders:
 
 ```python
 from pathlib import Path
+
+from huggingface_hub import snapshot_download
 from mlx_vlm import load
 from mlx_vlm.utils import load_model
 
-layout = load_model(Path("HashNuke/indic-ocr-mlx/weights/layout"))
-ocr, processor = load("HashNuke/indic-ocr-mlx/weights/ocr")
+root = Path(snapshot_download("HashNuke/indic-ocr-mlx"))
+layout = load_model(root / "weights/layout")
+layout.eval()
+ocr, processor = load(str(root / "weights/ocr"))
 ```
 
-Original weights: `bodhan-ai/indic-ocr` (gated, Indic Open Model License
-v1.0). Port code: `mlx_vlm/models/indic_ocr` in mlx-vlm.
+Do not pass `HashNuke/indic-ocr-mlx/weights/ocr` as a repository ID.
+For stage-specific examples, see the
+[layout README](https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/weights/layout/README.md)
+and [OCR README](https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/weights/ocr/README.md).
+
+## Languages and validation
+
+Upstream reports printed-text support for English and 22 Indian languages.
+Handwriting support covers English and 12 Indian languages; it does not cover
+every printed-text language. See the
+[upstream language coverage](https://huggingface.co/bodhan-ai/indic-ocr#supported-languages)
+for details.
+
+Greedy BF16 OCR matched fresh PyTorch transcriptions on an English title, an
+equation, and a Telugu line. Complete page parsing was checked on an English
+paper and annotated Telugu/Hindi gallery panels. A controlled table produced
+HTML with the expected rows and cell values. These are sample-level checks,
+not accuracy measurements across all supported languages; the gallery panels
+retain annotation text and handwriting quality varies.
+
+## License
+
+The source weights are distributed under the
+[Indic Open Model License v1.0](https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/LICENSE.md).
+This conversion does not change the upstream license.

weights/layout/README.md

@@ -1,26 +1,48 @@
 ---
-language:
-- en
 tags:
 - mlx
 - object-detection
 - document-layout
+- reading-order
 library_name: mlx-vlm
+license: other
+license_name: indic-open-model-license-1.0
+license_link: https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/LICENSE.md
+base_model: bodhan-ai/indic-ocr
 ---
 
-# indic-layout-mlx (layout stage, float32)
+# IndicDocLayout (MLX)
 
-MLX conversion of the **IndicDocLayout** stage of
-[bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
-(`weights/layout`, PP-DocLayoutV3/RT-DETR 33M, 37 classes + reading order).
+Built with IndicDocLayout from Bodhan AI / AI4Bharat.
+
+The layout stage of [IndicOCR (MLX)](https://huggingface.co/HashNuke/indic-ocr-mlx):
+a 37-class PP-DocLayoutV3 fine-tune that predicts document regions and reading
+order. The weights are float32, about 33M parameters (133 MB).
+
+Use an mlx-vlm checkout with `pp_doclayout_v3` support. This example downloads
+only the layout stage; it does not load the OCR model.
 
 ```python
 from pathlib import Path
+
+from huggingface_hub import snapshot_download
 from mlx_vlm.utils import load_model
-model = load_model(Path("HashNuke/indic-layout-mlx"))
+
+root = Path(snapshot_download(
+    "HashNuke/indic-ocr-mlx", allow_patterns=["weights/layout/*"]
+))
+model = load_model(root / "weights/layout")
 model.eval()
-print(model.detect("page.png", conf=0.5))
+records = model.detect("page.png", conf=0.5)
+for record in sorted(records, key=lambda item: item["reading_order"]):
+    print(record)
 ```
 
-Original model: `bodhan-ai/indic-ocr` (gated, Indic Open Model License v1.0).
-Converted with `mlx_vlm.models.indic_ocr.convert_layout --dtype float32`.
+Replace `page.png` with an image path. Records contain `bbox` in
+`[y0, x0, y1, x1]` order, normalized to 0–1000, plus `label`, one-based
+`reading_order`, and `score`. The detector does not transcribe text.
+
+This fine-tune is distinct from the stock 25-class
+[PP-DocLayout V3 (MLX)](https://huggingface.co/HashNuke/pp-doclayout-v3-mlx).
+The source weights are from [bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
+under the [Indic Open Model License v1.0](https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/LICENSE.md).

weights/ocr/README.md

@@ -1,41 +1,59 @@
 ---
-language:
-- en
-- as
-- bn
-- hi
-- mr
-- ta
-- te
 tags:
 - mlx
 - ocr
 - indic
 library_name: mlx-vlm
 pipeline_tag: image-text-to-text
+license: other
+license_name: indic-open-model-license-1.0
+license_link: https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/LICENSE.md
+base_model: bodhan-ai/indic-ocr
 ---
 
-# indic-ocr-mlx (OCR stage, bf16)
+# IndicBlockOCR (MLX)
 
-MLX conversion of the **IndicBlockOCR** stage of
-[bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
-(`weights/ocr`, Qwen3.5-0.8B, bf16, **not quantized**).
+Built with IndicBlockOCR from Bodhan AI / AI4Bharat.
 
-Use with `mlx-vlm` `indic_ocr` model support
-(`mlx_vlm/models/indic_ocr`):
+The recognition stage of [IndicOCR (MLX)](https://huggingface.co/HashNuke/indic-ocr-mlx):
+a Qwen3.5-0.8B fine-tune for transcribing text, equations, and tables from
+cropped document regions. The weights are BF16 (1.7 GB), not quantized.
+
+Use an mlx-vlm checkout with `indic_ocr` support. Replace `crop.png` with an
+image of a text region, not a complete multi-region page:
 
 ```python
-from mlx_vlm import load
-from mlx_vlm.models.indic_ocr.pipeline import IndicOCRParser
-from mlx_vlm.utils import load_model
 from pathlib import Path
 
-layout = load_model(Path("HashNuke/indic-layout-mlx"))
-ocr, processor = load("HashNuke/indic-ocr-mlx")
-page = IndicOCRParser(layout, ocr, processor).parse("page.png")
-print(page.markdown)
+from huggingface_hub import snapshot_download
+from PIL import Image
+from mlx_vlm import generate, load
+from mlx_vlm.models.indic_ocr.processing_indic_ocr import area_clamp, prompt_for
+from mlx_vlm.prompt_utils import apply_chat_template
+
+root = Path(snapshot_download(
+    "HashNuke/indic-ocr-mlx", allow_patterns=["weights/ocr/*"]
+))
+model, processor = load(str(root / "weights/ocr"))
+with Image.open("crop.png") as image:
+    crop = area_clamp(image.convert("RGB"))
+prompt = apply_chat_template(
+    processor, model.config, prompt_for("Text"), num_images=1
+)
+result = generate(
+    model, processor, prompt, [crop],
+    max_tokens=2048, temperature=0.0, verbose=False,
+)
+print(result.text)
 ```
 
-Original model: `bodhan-ai/indic-ocr` (gated, Indic Open Model License v1.0).
-Converted with `mlx_vlm.convert --dtype bfloat16`; `config.json`
-`model_type` rewritten to `indic_ocr`.
+Use `prompt_for("Equation")` for LaTeX or `prompt_for("Table")` for HTML
+tables. Greedy decoding (`temperature=0.0`) matches the default page pipeline.
+
+The repository root is a two-stage wrapper: `load("HashNuke/indic-ocr-mlx")`
+does not load this OCR stage. Use the local `weights/ocr` path above, or
+`IndicOCRParser.from_pretrained("HashNuke/indic-ocr-mlx")` for complete pages,
+as shown in the [main model card](https://huggingface.co/HashNuke/indic-ocr-mlx).
+
+The source weights are from [bodhan-ai/indic-ocr](https://huggingface.co/bodhan-ai/indic-ocr)
+under the [Indic Open Model License v1.0](https://huggingface.co/HashNuke/indic-ocr-mlx/blob/main/LICENSE.md).