From 8d77c41ea4f41e319951adb252be8c396a8cbdc1 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 20 Aug 2026 16:19:10 +0800 Subject: [PATCH] docs: phonological layer page + about/ecosystem; secryst replaces rababa in history --- src/layouts/Base.astro | 3 + src/pages/about.astro | 38 ++++++++++- src/pages/docs/index.astro | 13 +++- src/pages/docs/phonological-layer.astro | 89 +++++++++++++++++++++++++ 4 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 src/pages/docs/phonological-layer.astro diff --git a/src/layouts/Base.astro b/src/layouts/Base.astro index 774e9a7..cbe801a 100644 --- a/src/layouts/Base.astro +++ b/src/layouts/Base.astro @@ -115,6 +115,7 @@ const currentPath = Astro.url.pathname
  • Map catalogue
  • Authorities
  • Documentation
    • +
  • Phonological layer
    • @@ -124,6 +125,8 @@ const currentPath = Astro.url.pathname
  • TypeScript package
  • Map corpus
  • Ruby source
    • +
  • secryst crystals
    • +
  • interscript-ml contract
    • diff --git a/src/pages/about.astro b/src/pages/about.astro index 107b4a5..f6cb320 100644 --- a/src/pages/about.astro +++ b/src/pages/about.astro @@ -33,12 +33,44 @@ import Base from "../layouts/Base.astro"

    History

    Interscript was started at Ribose in 2019 as a Ruby library and - has since grown to include a TypeScript runtime, a research-grade - neural diacritizer (rababa), and a public reference site. The map - corpus now exceeds 300 systems. + has since grown to include TypeScript and Python engines, a public + reference site, and an optional phonological layer — + interscript-ml (the + contract and model zoo) run by the + secryst crystal family + (Ruby · Python · TypeScript). The map corpus now exceeds 300 + systems.

    +
    +

    The ecosystem

    +

    + Interscript is deliberately layered. The core is deterministic + maps and engines. When a map needs undiacritized text vocalized + first, it dispatches to an optional crystal: +

    +
      +
    • Maps + engines — + interscript-ruby, interscript-ts, + interscript-py — pure deterministic conversion.
      • +
    • Contract + zoo — + interscript-ml + — the models.yaml index, IMF v1 model format, + and golden sets.
      • +
    • Crystals — + secryst + (gem secryst · pip install secryst · + npm i secryst) — local ONNX inference implementing + the contract. A crystal has no interscript dependency; an engine + without a crystal simply cannot execute maps that declare a + vocalization step.
      • +
    • Training — + interscript-ml-train + — teachers whose students enter the zoo.
      • +
    +
    +

    Team

    diff --git a/src/pages/docs/index.astro b/src/pages/docs/index.astro index 74e81b1..f420584 100644 --- a/src/pages/docs/index.astro +++ b/src/pages/docs/index.astro @@ -11,8 +11,11 @@ const docs = renderAsciiDocDir("src/content/docs")

    Getting started

    - Interscript runs in Ruby and TypeScript. Both consume the same - authority-backed maps. + Interscript runs in Ruby, TypeScript, and Python. All consume the + same authority-backed maps. An optional + phonological layer + (secryst crystals + the interscript-ml contract) recovers vowels + and phonemes when a map needs vocalized input.

    @@ -29,6 +32,12 @@ interscript -s bgnpcgn-ukr-Cyrl-Latn-2019 <<< "Антон" transliterate("bgnpcgn-ukr-Cyrl-Latn-2019", "Антон") // => "Anton"
    +
    +

    Phonological layer

    + 
    gem install secryst
+# or: pip install secryst / npm i secryst
    + How vocalization fits → +
    diff --git a/src/pages/docs/phonological-layer.astro b/src/pages/docs/phonological-layer.astro new file mode 100644 index 0000000..d522dc4 --- /dev/null +++ b/src/pages/docs/phonological-layer.astro @@ -0,0 +1,89 @@ +--- +import Base from "../../layouts/Base.astro" +--- + + +

    Phonological layer

    + +

    + Many writing systems underdetermine pronunciation. Undiacritized Arabic, + nikud-less Hebrew, and unsegmented Thai cannot be transliterated + unambiguously until the hidden vowels or phonemes are restored. That + restoration is the phonological layer — optional, + independent of the core map engine, and run by the + secryst crystal family against the + interscript-ml + contract. +

    + +
    +

    How the pieces fit

    + 
    map (deterministic) ──secryst()──► crystal (ONNX)
+                                      │
+                                      ▼
+                            interscript-ml contract
+                            models.yaml · IMF v1 · goldens
    +
      +
    • interscript engines stay pure. A map that needs + vocalization declares a secryst (or future + vocalize) step; without a crystal installed, that map + simply cannot run that step.
      • +
    • secryst crystals + (gem secryst · pip install secryst · + npm i secryst resolve a model id through + models.yaml, download a sha256-verified IMF v1 zip, + cache it under ~/.cache/secryst, and run greedy ONNX + inference locally. No cloud, no telemetry.
      • +
    • interscript-ml is the contract only: the index, + the format, the golden sets, and the model zoo. It depends on + nothing. Crystals depend only on it.
      • +
    • interscript-ml-train produces the teachers whose + distilled students enter the zoo.
      • +
    +
    + +
    +

    Environment

    + + + + + + + + +
    VariableMeaningDefault
    SECRYST_INDEXIndex URL or pathinterscript-ml models.yaml on GitHub
    SECRYST_CACHEArtifact cache~/.cache/secryst
    +
    + +
    +

    Further reading

    + +
    + + +