feat(hf): Hugging Face org mirror pipeline - riboseinc/<id>

- model_card.py: models.yaml entry -> HF README (frontmatter, metrics
  table with provenance, curated benchmark block wrapper) - TDD, 8 tests
- publish_hf.py: per-id CLI (assembled zip + generated card ->
  riboseinc/<id>), dry-run mode, HF_TOKEN from env, classes.json side
  path for plane artifacts
- cards/ara-diac-2.0.md: the flagship curated block (SadeedDiac-25
  leaderboard, architecture, provenance)

User actions to go live: fine-grained HF token (write to the model
repos) as the HF_TOKEN secret on this repo, then
python3 scripts/publish_hf.py --id ara-diac-2.0 --zip <assembled>

Author: Ronald Tse

cards/ara-diac-2.0.md

@@ -0,0 +1,27 @@
+## Benchmark
+
+SadeedDiac-25 — full 1,200-paragraph set, Misraj's evaluator, zero
+skipped examples, greedy decode (protocol-matched published numbers
+only):
+
+| system | Total DER | kind |
+|---|---|---|
+| Claude-3.7-Sonnet | 1.39% | frontier LLM |
+| **ara-diac-2.0 (this model)** | **2.29%** | dedicated, 580M |
+| GLM-5.2 | 2.69% | frontier LLM |
+| Gemini-Flash-2.0 | 3.19% | frontier LLM |
+| GPT-4 | 3.86% | frontier LLM |
+| Sadeed-1.5B | 7.29% | leaderboard baseline |
+
+Word-final iʿrāb endings (the hardest component): 1.33% DER.
+Out-of-domain generalization (WikiNews-2024 multi-reference):
+17.38 WER / 11.83 DER.
+
+## Architecture
+
+ByT5-large-class seq2seq transformer (580M parameters), byte-level
+input/output (no tokenizer — id = byte + 3). Trained on classical and
+modern Arabic running text with a news-domain adaptation stage over a
+morphology-auxiliary curriculum. The canonical distribution is the
+Secryst IMF artifact (sha256-verified, parity-gated against the
+PyTorch reference); this repository mirrors those exact bytes.

scripts/model_card.py

@@ -0,0 +1,103 @@
+"""HF model-card generator: a models.yaml entry becomes the README.md
+model card for riboseinc/<id> (the org mirror of the index id).
+
+Curated benchmark/prose blocks live in cards/<id>.md and are wrapped
+by render_card; entries without a curated block get the metrics table
+alone. The index remains the single source of truth for numbers.
+"""
+
+from __future__ import annotations
+
+HF_ORG = "riboseinc"
+
+_LANG_BY_PREFIX = {
+    "ara": "ar", "heb": "he", "fas": "fa", "tha": "th", "urd": "ur",
+    "khm": "km",
+}
+
+_GIB = 1024 ** 3
+
+
+def hf_repo_for(model_id: str) -> str:
+    return f"{HF_ORG}/{model_id}"
+
+
+def _fmt_size(size: int | None) -> str:
+    if not size:
+        return ""
+    return f"{size / _GIB:.2f} GiB"
+
+
+def render_card(model_id: str, entry: dict, variants: list[str],
+                body: str = "", org: str = HF_ORG) -> str:
+    lang = _LANG_BY_PREFIX.get(model_id.split("-")[0], "multilingual")
+    lic = str(entry.get("license", "BSD-3-Clause")).lower()
+    size = _fmt_size(entry.get("size"))
+    lines = [
+        "---",
+        "license: " + lic,
+        "language: " + lang,
+        "inference: false",
+        "tags:",
+        "  - secryst",
+        "  - transliteration",
+    ]
+    task = entry.get("task", "")
+    if task == "diacritization":
+        lines.append("  - diacritization")
+    elif task == "g2p":
+        lines.append("  - grapheme-to-phoneme")
+    lines += [
+        "  - onnx",
+        "  - byt5",
+        "---",
+        "",
+        f"# {model_id}",
+        "",
+        f"Part of the [Secryst](https://secryst.github.io) phonological-layer "
+        f"family — a dedicated model for **{task}** ({lang.upper()}), distributed "
+        f"as a Secryst IMF artifact and loadable through any Secryst crystal:",
+        "",
+        "```python",
+        "from secryst import Model",
+        f"Model.load(\"{model_id}\")",
+        "```",
+        "",
+    ]
+    if size:
+        lines += [f"- Artifact: `{entry.get('filename', '')}` ({size})"]
+    if variants:
+        lines += ["- Precision variants: " + ", ".join(f"`{v}`" for v in variants)]
+    metrics = entry.get("metrics") or []
+    if metrics:
+        lines += [
+            "",
+            "## Measured quality",
+            "",
+            "Full evaluation sets, zero skipped examples, the benchmark's own evaluator. "
+            "Provenance for every number is the results record of the training project.",
+            "",
+            "| metric | value | provenance |",
+            "|---|---|---|",
+        ]
+        for m in metrics:
+            prov = m.get("source", "")
+            lines.append(f"| {m['name']} | {m['value']} | {prov} |")
+    if body:
+        lines += ["", body]
+    lines += [
+        "",
+        "## License",
+        "",
+        lic.upper(),
+        "",
+        "## Provenance",
+        "",
+        "Trained in the [Secryst training monorepo](https://github.com/secryst/secryst-train) "
+        "and published through the [interscript-ml](https://github.com/interscript/interscript-ml) "
+        "distribution contract (models.yaml index, sha256-verified release assets, "
+        "parity-gated artifacts). The canonical download channel is GitHub Releases; "
+        f"this repository is the Hugging Face mirror of the same bytes, pinned to the "
+        f"index revision.",
+    ]
+    return "\n".join(lines) + "\n"

scripts/publish_hf.py

@@ -0,0 +1,91 @@
+"""Publish a models.yaml entry to the Hugging Face org mirror.
+
+One command, both channels: the GitHub Releases asset stays the
+runtime channel; this adds the HF mirror (riboseinc/<id>) with a
+generated model card.
+
+Usage:
+    python3 scripts/publish_hf.py --id ara-diac-2.0 --zip /path/to/ara-diac-2.0-fp32.zip --dry-run
+    python3 scripts/publish_hf.py --id ara-diac-2.0 --zip /path/...   # uploads; needs HF_TOKEN
+
+--zip accepts the assembled zip (parts reassembled: cat *.part-* > zip).
+Variant ids (e.g. ara-diac-2.0-int8) are separate repos: run once per id.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from model_card import hf_repo_for, render_card  # noqa: E402
+
+INDEX = "models.yaml"
+CARDS_DIR = Path(__file__).resolve().parent.parent / "cards"
+
+
+def load_entry(model_id: str) -> dict:
+    index = yaml.safe_load(Path(INDEX).read_text(encoding="utf-8"))["models"]
+    entry = index.get(model_id)
+    if not entry:
+        raise SystemExit(f"{model_id} not in {INDEX}")
+    return entry
+
+
+def variants_of(model_id: str, index: dict) -> list[str]:
+    return [k for k in index if k != model_id and k.startswith(model_id + "-")]
+
+
+def curated_body(model_id: str) -> str:
+    card = CARDS_DIR / f"{model_id}.md"
+    return card.read_text(encoding="utf-8") if card.exists() else ""
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--id", required=True)
+    ap.add_argument("--zip", required=True, type=Path)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    index = yaml.safe_load(Path(INDEX).read_text(encoding="utf-8"))["models"]
+    entry = load_entry(args.id)
+    repo = hf_repo_for(args.id)
+    card = render_card(args.id, entry, variants_of(args.id, index),
+                       body=curated_body(args.id))
+    zipped = args.zip.read_bytes()
+
+    print(f"repo:      {repo}")
+    print(f"artifact:  {args.zip} ({len(zipped)} bytes; index sha256 "
+          f"{entry.get('sha256', '?')[:16]}…)")
+    print(f"card:      {len(card)} chars, {len(card.splitlines())} lines")
+    if args.dry_run:
+        print(card)
+        print("[dry-run] no upload performed")
+        return
+
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        raise SystemExit("HF_TOKEN not set (fine-grained, write-scoped to the repo)")
+    from huggingface_hub import HfApi
+
+    api = HfApi(token=token)
+    api.create_repo(repo, repo_type="model", private=False, exist_ok=True)
+    api.upload_file(path_or_fileobj=card.encode("utf-8"),
+                    path_in_repo="README.md", repo_id=repo, repo_type="model")
+    api.upload_file(path_or_fileobj=str(args.zip),
+                    path_in_repo=entry.get("filename", args.zip.name),
+                    repo_id=repo, repo_type="model")
+    classes = args.zip.with_name("classes.json")
+    if classes.exists():  # plane artifacts carry the class inventory
+        api.upload_file(path_or_fileobj=str(classes),
+                        path_in_repo="classes.json", repo_id=repo, repo_type="model")
+    print(f"uploaded https://huggingface.co/{repo}")
+
+
+if __name__ == "__main__":
+    main()

tests/test_model_card.py

@@ -0,0 +1,69 @@
+"""Tests for the HF model-card generator (models.yaml -> README.md)."""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+from model_card import hf_repo_for, render_card
+
+ENTRY = {
+    "task": "diacritization",
+    "precision": "fp32",
+    "filename": "ara-diac-2.0-fp32.zip",
+    "size": 2780299051,
+    "metrics": [
+        {"name": "der_total_greedy", "value": 2.2864,
+         "source": "rababa/docs/RESULTS.md#r7-verdict"},
+        {"name": "der_morph_greedy", "value": 1.3343,
+         "source": "rababa/docs/RESULTS.md#r7-verdict"},
+    ],
+    "license": "BSD-3-Clause",
+}
+VARIANTS = ["ara-diac-2.0-int8"]
+
+
+class TestHfRepo(unittest.TestCase):
+    def test_repo_is_org_plus_index_id(self):
+        self.assertEqual(hf_repo_for("ara-diac-2.0"), "riboseinc/ara-diac-2.0")
+
+    def test_variant_ids_keep_their_own_repo(self):
+        self.assertEqual(hf_repo_for("ara-diac-small-2.1-int8"),
+                         "riboseinc/ara-diac-small-2.1-int8")
+
+
+class TestRenderCard(unittest.TestCase):
+    def test_frontmatter_fields(self):
+        card = render_card("ara-diac-2.0", ENTRY, VARIANTS, body="## Benchmark\n\n2.29% DER.")
+        self.assertIn("license: bsd-3-clause", card)
+        self.assertIn("language: ar", card)
+        self.assertIn("inference: false", card)
+        self.assertIn("secryst", card)
+
+    def test_metrics_table_with_provenance(self):
+        card = render_card("ara-diac-2.0", ENTRY, VARIANTS, body="")
+        self.assertIn("| der_total_greedy | 2.2864 |", card)
+        self.assertIn("rababa/docs/RESULTS.md#r7-verdict", card)
+
+    def test_task_and_size(self):
+        card = render_card("ara-diac-2.0", ENTRY, VARIANTS, body="")
+        self.assertIn("diacritization", card)
+        self.assertIn("2.59 GiB", card)
+
+    def test_variants_listed(self):
+        card = render_card("ara-diac-2.0", ENTRY, VARIANTS, body="")
+        self.assertIn("ara-diac-2.0-int8", card)
+
+    def test_body_included(self):
+        card = render_card("ara-diac-2.0", ENTRY, VARIANTS, body="## Benchmark\n\n2.29% DER.")
+        self.assertIn("## Benchmark", card)
+        self.assertIn("2.29% DER.", card)
+
+    def test_language_mapping_per_task_language(self):
+        card = render_card("tha-g2p-base-1.0", {**ENTRY, "task": "g2p"}, [], body="")
+        self.assertIn("language: th", card)
+
+
+if __name__ == "__main__":
+    unittest.main()