anaksor-ocr 0.1.0__tar.gz

anaksor_ocr-0.1.0/.github/workflows/README.md

@@ -0,0 +1,18 @@
+# CI and release workflows (to activate)
+
+These are the repository's workflows. They live here because the app that pushed this
+branch may not write to `.github/workflows/`. To turn them on:
+
+```bash
+git mv .github/workflows-pending .github/workflows
+git rm .github/workflows/README.md
+git commit -m "ci: enable workflows" && git push
+```
+
+- `ci.yml`: tests (Python 3.11 to 3.13, CPU torch), ruff, lock check, pip-audit of the
+  locked and of the lowest allowed dependencies (weekly as well), wheel build and a clean
+  install of it.
+- `release.yml`: on a `vX.Y.Z` tag, audit, build, and publish to PyPI with trusted publishing.
+- `web.yml`: lint, typecheck, build, browser smoke test and dependency scan of the website
+  (`web/`, on Bun); on `master`, the deploy to the server behind ocr.sokhengdin.dev
+  (`web/deploy/README.md`: the `production` environment and its secrets).

anaksor_ocr-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+weights/
+*.pth
+*.safetensors
+.tmp/

anaksor_ocr-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release, extracted from the Alpha-OCR project that serves https://ocr.sokhengdin.dev.
+
+- `anaksor.OCR`: detection (DBNet, RepViT) and recognition (SVTRv2, CTC) of Khmer text,
+  reading order with columns, receipts and paragraphs, long lines read in stitched windows.
+- PDF input (`anaksor-ocr[pdf]`), searchable PDF and Word export (`anaksor-ocr[docx]`).
+- `anaksor` command line.
+- Weights as `.safetensors`, downloaded on first use and checksum-verified.
+- Line crop margin 0.22 / 0.20 of the line height for the v3 recogniser.
+- Default models: recognition v4 (SVTRv2-B, crop margin 0.16 / 0.10) and detection v3,
+  published at https://huggingface.co/Sokheng/anaksor-ocr (tag `rec-v4-det-v3`). The v2 / v3
+  specs stay bundled (`"det-repvit-db-v2"`, `"rec-svtrv2-v3"`); their weights aren't published.
+- Weights are only downloaded when the spec pins their SHA-256 (`ANAKSOR_ALLOW_UNVERIFIED=1`
+  for your own unhashed uploads). They come from the release's Hub commit (`5c9f76c`, the
+  repo's `_latest` files there), not `main`; `ANAKSOR_HF_REVISION` picks another.
+- Own implementation of the networks (`anaksor.nets`: RepViT + DBNet, SVTRv2 with RCTC and
+  SMTR heads), the DB box extraction and the CTC / SMTR decoding; no vendored OpenOCR code.
+- `[export]` needs `onnx>=1.22` (earlier releases have the external-data path traversal and
+  shape-inference advisories fixed in 1.21 / 1.22).
+  Checkpoints trained in Alpha-OCR (`.pth` or converted `.safetensors`) load unchanged, and
+  the outputs match the training-time implementation (golden tests in `tests/data`).
+- CPPD recognisers (`CPPDDecoder`); long lines without CTC positions are joined on the
+  overlap of their windows' texts.
+- `tools/spec_from_config.py`: a spec from any Alpha-OCR training config (rec v2/v3/v4,
+  CPPD, det v2/v3), so its `best.pth` loads directly.
+- Two backends: ONNX Runtime (default install, no PyTorch) and PyTorch (`[torch]`), chosen
+  with `backend=` / `--backend`; same boxes and text. `tools/export_onnx.py` exports the
+  detector and the CTC / CPPD recognisers with dynamic shapes, checked against PyTorch.
+  Specs name the graph in `weights.onnx` (+ `onnx_sha256`).
+- Batch norms and RepViT's re-parameterisable branches are folded into single convolutions
+  when a model loads (`fuse=True`): same output, detection about 2.5x faster on CPU.

anaksor_ocr-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

anaksor_ocr-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+anaksor-ocr
+Copyright 2026 Sokheng Din
+
+The networks in src/anaksor/nets are written for anaksor from the papers they implement
+(DBNet, RepViT, SVTRv2, SMTR, CPPD; see README.md). Their layer layout and tensor names follow
+the OpenOCR implementations (https://github.com/Topdu/OpenOCR, Apache License 2.0) that
+the released models were trained with, so those checkpoints load unchanged.

anaksor_ocr-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: anaksor-ocr
+Version: 0.1.0
+Summary: Khmer OCR: photos, scans and PDFs to Khmer text, with layout, searchable PDF and Word export
+Project-URL: Homepage, https://ocr.sokhengdin.dev
+Project-URL: Documentation, https://sokhengdin.github.io/anaksor-ocr/
+Project-URL: Repository, https://github.com/SokhengDin/anaksor-ocr
+Project-URL: Issues, https://github.com/SokhengDin/anaksor-ocr/issues
+Author: Sokheng Din
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cambodia,document-ai,khmer,ocr,pdf,text-detection,text-recognition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnxruntime>=1.20
+Requires-Dist: opencv-python-headless>=4.10.0.84
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: pyclipper>=1.3.0.post6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: shapely>=2.0.6
+Provides-Extra: all
+Requires-Dist: pypdfium2>=4.30; extra == 'all'
+Requires-Dist: python-docx>=1.1.2; extra == 'all'
+Requires-Dist: safetensors>=0.4.5; extra == 'all'
+Requires-Dist: torch>=2.13; extra == 'all'
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.1.2; extra == 'docx'
+Provides-Extra: export
+Requires-Dist: onnx>=1.22; extra == 'export'
+Requires-Dist: onnxscript>=0.2; extra == 'export'
+Requires-Dist: safetensors>=0.4.5; extra == 'export'
+Requires-Dist: torch>=2.13; extra == 'export'
+Provides-Extra: pdf
+Requires-Dist: pypdfium2>=4.30; extra == 'pdf'
+Provides-Extra: torch
+Requires-Dist: safetensors>=0.4.5; extra == 'torch'
+Requires-Dist: torch>=2.13; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# anaksor-ocr
+
+**អានអក្សរ**: Khmer OCR for photos, scans and PDFs. It finds the text lines, reads them,
+puts them in reading order (columns, receipts, paragraphs) and exports plain text, JSON, a
+searchable PDF or a Word file.
+
+Website, with a live demo and the documentation in Khmer and English:
+**[ocr.sokhengdin.dev](https://ocr.sokhengdin.dev)**.
+
+| | |
+|---|---|
+| Detection | DBNet with a RepViT backbone, trained on KhmerST photos and synthetic pages |
+| Recognition | SVTRv2 with a CTC head, trained on public Khmer datasets and synthetic lines |
+| Layout | deskew, column detection, line growing, paragraphs, long lines read in stitched windows |
+| Runs on | ONNX Runtime (CPU, CUDA) by default; PyTorch (CPU, CUDA, Apple MPS) with `[torch]` |
+
+## Install
+
+```bash
+pip install anaksor-ocr             # images, ONNX Runtime backend (no PyTorch)
+pip install "anaksor-ocr[torch]"    # + PyTorch backend: CUDA / Apple MPS, SMTR head, .pth weights
+pip install "anaksor-ocr[all]"      # PyTorch + PDF input + Word export
+```
+
+Python 3.11+. For a specific CUDA build of PyTorch, install `torch` from
+[pytorch.org](https://pytorch.org/get-started/locally/) first; for ONNX Runtime on CUDA,
+`pip install onnxruntime-gpu`. The weights (about 95 MB for ONNX Runtime, 113 MB for PyTorch) download to `~/.cache/anaksor`
+on first use.
+
+### Backends
+
+| | `onnx` (default install) | `torch` (`[torch]`) |
+|---|---|---|
+| Install | no PyTorch (with CUDA, PyTorch is several GB) | PyTorch |
+| Devices | CPU; CUDA with `onnxruntime-gpu` | CPU, CUDA, Apple MPS |
+| Weights | exported `.onnx` graphs | `.safetensors`, `.pth` checkpoints |
+| Heads | CTC, CPPD | CTC, SMTR (`decoder="gtc"` / `"auto"`), CPPD |
+
+`backend="auto"` (also `--backend` on the command line) uses PyTorch when it is installed,
+else ONNX Runtime; an `.onnx` weights file always runs in ONNX Runtime. Both give the same
+boxes and text. On PyTorch the batch norms are folded into the convolutions when a model
+loads (`fuse=True`): same output, detection about 2.5x faster on CPU.
+
+On CPU the two are close; PyTorch is a little faster (6 bench pages, rec v3: 79 s and
+0.7 GB peak memory on PyTorch, 99 s and 0.9 GB on ONNX Runtime). ONNX Runtime's gain is the
+install. Wide crops are recognised in smaller batches on both, as attention memory grows
+with the square of the width.
+
+## Command line
+
+```bash
+anaksor photo.jpg                       # text to stdout
+anaksor scan.pdf -o scan.docx           # Word, layout rebuilt
+anaksor scan.pdf -o scan-searchable.pdf # page images + selectable text
+anaksor *.jpg -o out/ -f json           # one JSON per image
+anaksor scan.pdf --pages 1-3,7 --device cuda
+anaksor --fetch-models                  # download the weights ahead of time
+```
+
+## Python
+
+```python
+import anaksor
+
+ocr = anaksor.OCR()                       # backend and device picked automatically, see Backends
+result = ocr("page.jpg")
+print(result["text"])                     # reading order; paragraphs split by blank lines
+
+for line in result["lines"]:              # text, box, quads, parts, rec_score, det_score, block
+    print(line["rec_score"], line["text"])
+
+pages = ocr.read("scan.pdf", keep_images=True)        # one result per page
+open("scan.pdf", "wb").write(anaksor.export.to_pdf(pages))
+open("scan.docx", "wb").write(anaksor.export.to_docx(pages))
+```
+
+`ocr(image)` takes a path, bytes, a PIL image or an RGB numpy array. Useful options:
+
+| Option | Default | Effect |
+|---|---|---|
+| `pad_y`, `pad_x` | 0.16, 0.10 | margin around each line before reading, as a fraction of its height |
+| `min_rec_score` | 0.5 | drop lines read with less confidence |
+| `unclip_ratio` | 1.5 | how much detected boxes are grown (bigger joins more) |
+| `scales` | `(1.0,)` | extra detection scales, e.g. `(1.0, 1.6)` for small text |
+
+The detector and recogniser can be used on their own: `anaksor.Detector().detect(img)` and
+`anaksor.Recognizer().recognize([crop, ...])`.
+
+## Accuracy and limitations
+
+| Part | Evaluated on | Result |
+|---|---|---|
+| Detection v3 | KhmerST validation photos | precision 0.75, recall 0.79 |
+| Detection v3 | HierText validation: English on photos | precision 0.76, recall 0.69 |
+| Detection v3 | synthetic pages | precision 0.998, recall 0.998 |
+| Recognition v4 | 3,878 real validation lines: Khmer, Latin and mixed | 86.7% exactly right, 1.38% character error |
+| Recognition v4 | the 2,497 Khmer-only lines among them | 90.1% exactly right, 0.73% character error |
+
+KhmerST labels only some of the text in each photo; for detection, unlabelled text found by
+another detector counts as "don't care", which flatters precision a little.
+
+- Printed Khmer, documents, receipts and signs read best.
+- English and other Latin text on photos is weaker: the detector can miss it on signs, and the
+  recogniser has seen little real English.
+- Handwriting and decorative lettering are weak. Check each line's `rec_score`, or use
+  `--highlight-low` for Word output.
+
+Training data and its licences are listed in the model card on
+[Hugging Face](https://huggingface.co/Sokheng/anaksor-ocr).
+
+## Weights
+
+Each model has two files: an ONNX graph (`.onnx`, used by the onnx backend) and PyTorch
+weights (`.safetensors`, used by the torch backend). Only the files the chosen backend needs
+are fetched, from the first of: an explicit `det_weights=` / `rec_weights=` path,
+`$ANAKSOR_WEIGHTS_DIR`, then the cache (`$ANAKSOR_HOME`, default `~/.cache/anaksor`), which
+is filled from the Hugging Face repo `Sokheng/anaksor-ocr` and checked against the
+SHA-256 in the model spec before it is used; a file whose spec has no SHA-256 is not
+downloaded at all. Neither format can run code when loaded. Files come from the Hub commit
+of the release the package was built for (rec v4 + det v3, `5c9f76c`), not from `main`,
+where the `_latest` files move on with each release; `ANAKSOR_HF_REVISION` picks another. Offline machines: copy
+the two files for your backend into `$ANAKSOR_WEIGHTS_DIR` (`anaksor --fetch-models`
+downloads them ahead of time).
+
+### Other models
+
+Models trained with OpenOCR-style configs (the format these models were trained with) run
+with a spec made from the training config. The tools are in the repository, not the
+installed package, so run them from a clone:
+
+```bash
+git clone https://github.com/SokhengDin/anaksor-ocr && cd anaksor-ocr
+python tools/spec_from_config.py path/to/svtrv2_cppd_khmer.yml --out specs/
+```
+
+```python
+rec = anaksor.Recognizer("specs/rec-svtrv2-cppd-khmer.yml", weights="best.pth")
+ocr = anaksor.OCR(recognizer=rec)
+```
+
+For the onnx backend, export the weights (needs `[export]`); the spec already names the
+`.onnx` file, so only the printed SHA-256 goes into `weights.onnx_sha256`:
+
+```bash
+python tools/export_onnx.py --rec best.pth --rec-spec specs/rec-svtrv2-cppd-khmer.yml --out onnx/
+```
+
+Supported: detection RepViT + DBNet; recognition SVTRv2 (any size) with RCTC + SMTR heads
+(`GTCDecoder`, also with the training-only count head), RCTC alone, or CPPD. The `.pth`
+checkpoints load as they are (no code runs: `weights_only`); `tools/convert_weights.py`
+turns them into `.safetensors`. A CPPD head has no per-column output, so lines wider than
+its input are read in overlapping windows joined where their texts overlap, instead of by
+CTC character positions.
+
+## Security
+
+Image inputs are decoded only as JPEG, PNG, WEBP, BMP or TIFF, weights are loaded without
+running code, and dependency floors exclude versions with known vulnerabilities (checked with
+`pip-audit` in CI). See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+uv venv && uv pip install torch --index-url https://download.pytorch.org/whl/cpu
+uv pip install -e ".[all]" pytest ruff pip-audit onnx onnxscript
+pytest                                    # no weights or network needed
+ANAKSOR_TEST_WEIGHTS=/path/to/weights pytest -m weights
+ruff check src tests tools && ruff format --check src tests tools
+```
+
+The website (landing page, demo, documentation) is a Next.js app in `web/`, see
+[web/README.md](web/README.md).
+
+Layout of the package:
+
+| Module | Role |
+|---|---|
+| `ocr.py` | `OCR`: detect, crop, recognise, lay out |
+| `detector.py`, `recognizer.py` | the two models |
+| `layout.py` | reading order: XY-cut columns, lines, paragraphs |
+| `longline.py` | lines wider than the recogniser's input: windows stitched by CTC positions (CPPD: by text overlap) |
+| `geometry.py` | box maths and crops |
+| `text.py` | Khmer normalisation and the recognition charset |
+| `inputs.py` | images (format allowlist) and PDF pages |
+| `export/` | searchable PDF and Word |
+| `models.py` | model specs, weights download, checksum and safe loading |
+| `runtime.py` | where the networks run: PyTorch or ONNX Runtime |
+| `onnx_export.py` | ONNX export (fused, dynamic shapes, checked against PyTorch) |
+| `nets/` | the networks: RepViT + DBNet, SVTRv2 with RCTC, SMTR or CPPD heads; `fuse.py` folds batch norms |
+| `db_boxes.py` | text boxes from the detector's probability map |
+| `decoding.py` | charsets, CTC, SMTR and CPPD decoding |
+
+### Releasing
+
+1. CI: move `.github/workflows-pending/` to `.github/workflows/` (see the README there).
+2. Weights: `python tools/convert_weights.py best.pth` for each model, then
+   `python tools/export_onnx.py --det ... --rec ...`; upload the `.safetensors` and `.onnx`
+   files to the Hugging Face repo and put the printed SHA-256s into `src/anaksor/data/*.yml`
+   (`weights.sha256`, `weights.onnx_sha256`). Add a model card to the Hugging Face repo:
+   training data, its licences, and the evaluation results above.
+3. Bump `version` in `pyproject.toml`, update `CHANGELOG.md`, then tag `vX.Y.Z`.
+   The release workflow audits the dependencies, builds, and publishes to PyPI through
+   trusted publishing.
+
+## Credits and licence
+
+Apache-2.0. The networks are implemented from their papers, with the layer layout and
+tensor names of the [OpenOCR](https://github.com/Topdu/OpenOCR) implementations the models
+were trained with (see [NOTICE](NOTICE)).
+
+- DBNet: Liao et al., *Real-time Scene Text Detection with Differentiable Binarization*, AAAI 2020
+- RepViT: Wang et al., *RepViT: Revisiting Mobile CNN From ViT Perspective*, CVPR 2024
+- SVTRv2: Du et al., *SVTRv2: CTC Beats Encoder-Decoder Models in Scene Text Recognition*, ICCV 2025
+- SMTR: Du et al., *Out of Length Text Recognition with Sub-String Matching*, AAAI 2025
+- CPPD: Du et al., *Context Perception Parallel Decoder for Scene Text Recognition*, TPAMI 2025