Skip to content

Commit ad9295f

Browse files
ronaldtseronaldtse
committed
docs: phonological layer page + about/ecosystem; secryst replaces rababa in history
1 parent 1d6c9db commit ad9295f

4 files changed

Lines changed: 138 additions & 5 deletions

File tree

‎src/layouts/Base.astro‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ const currentPath = Astro.url.pathname
115115
<li><a href="/maps">Map catalogue</a></li>
116116
<li><a href="/authorities">Authorities</a></li>
117117
<li><a href="/docs">Documentation</a></li>
118+
<li><a href="/docs/phonological-layer">Phonological layer</a></li>
118119
</ul>
119120
</div>
120121
<div class="footer-col">
@@ -124,6 +125,8 @@ const currentPath = Astro.url.pathname
124125
<li><a href="https://www.npmjs.com/package/interscript-ts" rel="noreferrer">TypeScript package</a></li>
125126
<li><a href="https://github.com/interscript/maps" rel="noreferrer">Map corpus</a></li>
126127
<li><a href="https://github.com/interscript/interscript-ruby" rel="noreferrer">Ruby source</a></li>
128+
<li><a href="https://www.secryst.org" rel="noreferrer">secryst crystals</a></li>
129+
<li><a href="https://github.com/interscript/interscript-ml" rel="noreferrer">interscript-ml contract</a></li>
127130
</ul>
128131
</div>
129132
<div class="footer-col">

‎src/pages/about.astro‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,44 @@ import Base from "../layouts/Base.astro"
3333
<h2>History</h2>
3434
<p>
3535
Interscript was started at Ribose in 2019 as a Ruby library and
36-
has since grown to include a TypeScript runtime, a research-grade
37-
neural diacritizer (rababa), and a public reference site. The map
38-
corpus now exceeds 300 systems.
36+
has since grown to include TypeScript and Python engines, a public
37+
reference site, and an optional phonological layer —
38+
<a href="/docs/phonological-layer">interscript-ml</a> (the
39+
contract and model zoo) run by the
40+
<a href="https://www.secryst.org">secryst</a> crystal family
41+
(Ruby · Python · TypeScript). The map corpus now exceeds 300
42+
systems.
3943
</p>
4044
</section>
4145

46+
<section>
47+
<h2>The ecosystem</h2>
48+
<p>
49+
Interscript is deliberately layered. The core is deterministic
50+
maps and engines. When a map needs undiacritized text vocalized
51+
first, it dispatches to an optional crystal:
52+
</p>
53+
<ul>
54+
<li><strong>Maps + engines</strong> —
55+
<code>interscript-ruby</code>, <code>interscript-ts</code>,
56+
<code>interscript-py</code> — pure deterministic conversion.</li>
57+
<li><strong>Contract + zoo</strong> —
58+
<a href="https://github.com/interscript/interscript-ml">interscript-ml</a>
59+
— the <code>models.yaml</code> index, IMF&nbsp;v1 model format,
60+
and golden sets.</li>
61+
<li><strong>Crystals</strong> —
62+
<a href="https://www.secryst.org">secryst</a>
63+
(<code>gem secryst</code> · <code>pip install secryst</code> ·
64+
<code>npm i secryst</code>) — local ONNX inference implementing
65+
the contract. A crystal has no interscript dependency; an engine
66+
without a crystal simply cannot execute maps that declare a
67+
vocalization step.</li>
68+
<li><strong>Training</strong> —
69+
<a href="https://github.com/interscript/interscript-ml-train">interscript-ml-train</a>
70+
— teachers whose students enter the zoo.</li>
71+
</ul>
72+
</section>
73+
4274
<section>
4375
<h2>Team</h2>
4476
<p>

‎src/pages/docs/index.astro‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,11 @@ const docs = renderAsciiDocDir("src/content/docs")
1111
<section class="quickstart">
1212
<h2>Getting started</h2>
1313
<p>
14-
Interscript runs in Ruby and TypeScript. Both consume the same
15-
authority-backed maps.
14+
Interscript runs in Ruby, TypeScript, and Python. All consume the
15+
same authority-backed maps. An optional
16+
<a href="/docs/phonological-layer">phonological layer</a>
17+
(secryst crystals + the interscript-ml contract) recovers vowels
18+
and phonemes when a map needs vocalized input.
1619
</p>
1720
<div class="runtime-tiles">
1821
<div class="tile">
@@ -29,6 +32,12 @@ interscript -s bgnpcgn-ukr-Cyrl-Latn-2019 &lt;&lt;&lt; "Антон"
2932
transliterate("bgnpcgn-ukr-Cyrl-Latn-2019", "Антон")
3033
// => "Anton"</code></pre>
3134
</div>
35+
<div class="tile">
36+
<h3>Phonological layer</h3>
37+
<pre><code>gem install secryst
38+
# or: pip install secryst / npm i secryst</code></pre>
39+
<a href="/docs/phonological-layer">How vocalization fits →</a>
40+
</div>
3241
</div>
3342
</section>
3443

‎src/pages/docs/phonological-layer.astro‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
import Base from "../../layouts/Base.astro"
3+
---
4+
5+
<Base
6+
title="Phonological layer — Interscript"
7+
description="How Interscript maps optionally use secryst crystals and the interscript-ml contract to vocalize undiacritized input before transliteration."
8+
>
9+
<h1>Phonological layer</h1>
10+
11+
<p class="lede">
12+
Many writing systems underdetermine pronunciation. Undiacritized Arabic,
13+
nikud-less Hebrew, and unsegmented Thai cannot be transliterated
14+
unambiguously until the hidden vowels or phonemes are restored. That
15+
restoration is the <strong>phonological layer</strong> — optional,
16+
independent of the core map engine, and run by the
17+
<a href="https://www.secryst.org">secryst</a> crystal family against the
18+
<a href="https://github.com/interscript/interscript-ml">interscript-ml</a>
19+
contract.
20+
</p>
21+
22+
<section>
23+
<h2>How the pieces fit</h2>
24+
<pre class="diagram"><code>map (deterministic) ──secryst()──► crystal (ONNX)
25+
│
26+
▼
27+
interscript-ml contract
28+
models.yaml · IMF v1 · goldens</code></pre>
29+
<ul>
30+
<li><strong>interscript engines</strong> stay pure. A map that needs
31+
vocalization declares a <code>secryst</code> (or future
32+
<code>vocalize</code>) step; without a crystal installed, that map
33+
simply cannot run that step.</li>
34+
<li><strong>secryst crystals</strong>
35+
(<code>gem secryst</code> · <code>pip install secryst</code> ·
36+
<code>npm i secryst</code> resolve a model id through
37+
<code>models.yaml</code>, download a sha256-verified IMF&nbsp;v1 zip,
38+
cache it under <code>~/.cache/secryst</code>, and run greedy ONNX
39+
inference locally. No cloud, no telemetry.</li>
40+
<li><strong>interscript-ml</strong> is the contract only: the index,
41+
the format, the golden sets, and the model zoo. It depends on
42+
nothing. Crystals depend only on it.</li>
43+
<li><strong>interscript-ml-train</strong> produces the teachers whose
44+
distilled students enter the zoo.</li>
45+
</ul>
46+
</section>
47+
48+
<section>
49+
<h2>Environment</h2>
50+
<table>
51+
<thead><tr><th>Variable</th><th>Meaning</th><th>Default</th></tr></thead>
52+
<tbody>
53+
<tr><td><code>SECRYST_INDEX</code></td><td>Index URL or path</td>
54+
<td>interscript-ml <code>models.yaml</code> on GitHub</td></tr>
55+
<tr><td><code>SECRYST_CACHE</code></td><td>Artifact cache</td>
56+
<td><code>~/.cache/secryst</code></td></tr>
57+
</tbody>
58+
</table>
59+
</section>
60+
61+
<section>
62+
<h2>Further reading</h2>
63+
<ul>
64+
<li><a href="https://www.secryst.org">secryst.org</a> — crystal primer, API reference, model zoo</li>
65+
<li><a href="https://www.secryst.org/spec.html">IMF v1 specification</a> — the normative contract text</li>
66+
<li><a href="https://github.com/interscript/interscript-ml/blob/main/SPEC.md">interscript-ml/SPEC.md</a> — canonical source of that text</li>
67+
<li><a href="https://github.com/interscript/interscript-ml-train">interscript-ml-train</a> — teachers</li>
68+
</ul>
69+
</section>
70+
</Base>
71+
72+
<style>
73+
.lede { font-size: 1.1rem; line-height: 1.7; max-width: 70ch; }
74+
section { margin: 2.2rem 0; }
75+
h2 { font-size: 1.35rem; margin-bottom: 0.6rem; }
76+
p, li { line-height: 1.7; max-width: 70ch; }
77+
a { color: var(--color-brand); }
78+
code { font-size: 0.9em; }
79+
.diagram {
80+
background: var(--color-surface, #f4f4f5);
81+
border: 1px solid var(--color-border, #e4e4e7);
82+
border-radius: 8px;
83+
padding: 1rem 1.2rem;
84+
overflow-x: auto;
85+
font-size: 0.85rem;
86+
}
87+
table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.95rem; }
88+
th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--color-border, #e4e4e7); }
89+
</style>

0 commit comments

Comments
 (0)