From 1837bae36dd01da7ad2942e155423b17e72b9313 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Mon, 19 Oct 2026 11:49:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20models=20ready=20to=20use=20=E2=80=94?= =?UTF-8?q?=20registry-generated=20catalog,=20per-runtime=20quick=20start,?= =?UTF-8?q?=20honest=20crystal=20status?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 016b6007..428db64a 100644 --- a/README.md +++ b/README.md @@ -60,25 +60,79 @@ Dependency directions, stated once: with `pip install secryst` and nothing else. - **Engines depend on crystals only optionally.** An engine without a crystal simply cannot execute maps that declare a vocalization step. -- **Training is owned by secryst.** Teachers live in - [secryst/secryst-train](https://github.com/secryst/secryst-train) — - the crystal family's own product. This repo publishes their distilled - students through the export gate; it does not train anything. +- **Training is config-driven and lives here.** Recipes + corpora + the + `isxml` spine (below) train and gate every model in this repo; + teachers live in the train monorepos. This repo publishes the + distilled students through the export gate. + +## Models ready to use (index-v12) + +Every entry below is a shipped, sha256-verified IMF v1 artifact on this +repo's GitHub Releases, listed in `models.yaml` and the published +`index-v12`, mirrored to Hugging Face (`Interscript/`), and gated by +torch↔artifact parity in the runtime's decode mode. Metrics are quoted +from `models.yaml` (protocol + anchor recorded per metric; row-mean +CER unless stated). + +| model | task | size | headline metric | +|---|---|---|---| +| `ara-diac-2.0` | Arabic diacritization | 2.78 GB fp32 | SadeedDiac-25 DER **2.29%** (beats GLM-5.2 2.69); WikiNews-2024 17.38 WER | +| `ara-diac-news-1.1` | Arabic news register | 2.16 GB fp32 | WikiNews multiref 8.85 WER | +| `ara-diac-small-2.1` | Arabic, fast tier | 1.42 GB fp32 | fullset DER 4.57 (teacher 2.29) | +| `ara-diac-plane-large-1.0` | Arabic, int8 fast tier | 0.87 GB int8 | DER 2.74 / WER 8.61 | +| `urd-diac-base-1.0` | Urdu diacritization | 1.35 GB fp16 | CER **3.57%** | +| `urd-diac-1.0` | Urdu, small tier | 1.42 GB fp32 | CER 3.74% | +| `urd-g2p-base-1.0` | Urdu G2P | 2.16 GB fp32 | CER 15.65% — **RESEARCH-ONLY** (non-commercial data) | +| `fas-diac-base-1.0` | Persian diacritization | 0.71 GB fp16 | CER **0.603%** row-mean / 0.777% corpus, 82.3% word-acc (CC0 data) | +| `fas-g2p-1.0` | Persian G2P | 2.78 GB fp32 | CER 1.6% | +| `tha-g2p-base-1.0` | Thai G2P | 2.78 GB fp32 | teacher PER 1.25% | +| `tha-g2p-small-1.0` | Thai G2P, int8 | 0.26 GB int8 | PER 2.85% (beam-4 12.06%) | +| `khm-latn-1.0` | Khmer → Latin | 1.42 GB fp32 | CER 27.42% / EM 59.66% | +| `heb-diac-plane-2.0` | Hebrew nikud, int8 | 0.42 GB int8 | DER 8.18% | +| `heb-diac-1.1` | Hebrew nikud, fp32 | 2.78 GB fp32 | DER 16.44% | + +Quantized variants (int8/int4/fp16) ship as assets of their base +model's release. Hebrew remains data-supply-limited: newer lanes are +blocked upstream, not on models. + +### Using a model today + +Artifacts are plain public downloads; any IMF v1 runtime works +(single-row greedy decode: ids = byte + 3 with trailing EOS — +`conformance/CONFORMANCE.md`). The reference python loader is +`runtime/src/interscript_ml` (conformance-proven). + +Point a crystal's index at the current release and resolve by id: + +```sh +export SECRYST_INDEX="https://github.com/interscript/interscript-models/releases/download/index-v12/models-index.yaml" # python crystal +export INTERSCRIPT_ML_INDEX="$SECRYST_INDEX" # ruby gem (archived: override is required) +``` + +```python +from interscript_ml import Model # reference runtime (this repo) +m = Model.load("urd-diac-base-1.0") # resolves via the index, verifies sha256 +print(m.translate("کلیدهای پرکینزمانند")) +``` + +Release pins move per index tag (v11: urd-diac-base; v12: urd-g2p-base, +fas-diac-base). Crystal releases re-pin on their own cadence — until +then the env override above is the supported path. ## Repositories | repo | role | |---|---| -| [interscript/interscript-models](https://github.com/interscript/interscript-models) | this — contract + zoo | -| [secryst/secryst](https://github.com/secryst/secryst) | Ruby crystal (the original, est. 2020) | -| [secryst/secryst-py](https://github.com/secryst/secryst-py) | Python crystal — reference, owns golden generation | -| [secryst/secryst-ts](https://github.com/secryst/secryst-ts) | TypeScript crystal (npm `secryst`) | -| [secryst/secryst.github.io](https://www.secryst.org) | the crystals' documentation site | -| [secryst/secryst-train](https://github.com/secryst/secryst-train) | training monorepo — **secryst-owned teachers** | +| [interscript/interscript-models](https://github.com/interscript/interscript-models) | this — contract + zoo + isxml framework | +| [interscript/interscript](https://github.com/interscript/interscript) | ISC map DSL (the transliteration contract) | +| [interscript/interscript-ruby](https://github.com/interscript/interscript-ruby) | Ruby ISC gem (maps; the ML-model crystal is archived, see below) | +| [interscript/interscript-py](https://github.com/interscript/interscript-py) | Python crystal — live | +| [secryst/secryst](https://github.com/secryst/secryst) · [secryst/secryst-py](https://github.com/secryst/secryst-py) · [secryst/secryst-ts](https://github.com/secryst/secryst-ts) | **archived** original crystals (est. 2020; the ML ruby gem's default index URL is dead — override `INTERSCRIPT_ML_INDEX`) | | [interscript/interscript-train](https://github.com/interscript/interscript-train) · [rababa-farsi](https://github.com/interscript/rababa-farsi) · [rababa-urdu](https://github.com/interscript/rababa-urdu) | archived origins of the train monorepo (full history merged there) | -`runtime/` in this repo is the **frozen origin** of the Python crystal — -kept for provenance; live code and releases are in secryst-py. +`runtime/` in this repo is the conformance-proven **reference IMF +runtime** — the executable definition of the artifact contract, and the +source of the frozen conformance fixtures. ## Contributing a language or a technique (the isxml framework)