farsit 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Salehi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# farsit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Accurate Persian → Finglish transliteration. No AI, no dictionary, zero deps. Slugs included.**
+
+> موتور دقیق تبدیل متن فارسی به فینگلیش (حروف لاتین)؛ بدون هوش مصنوعی، بدون فرهنگ لغت و بدون وابستگی. اسلاگ URL هم دارد. کاملاً آفلاین و الگوریتمی؛ خروجی هرگز `x` ندارد (خ=kh، ش=sh، چ=ch، ژ=zh، ق/غ=gh).
+
+`farsit` reads Persian the way people pronounce it, filling in the short vowels Persian script leaves out, and writes it in everyday Finglish. Runs offline in the browser or Node: ESM + CJS, fully typed, ~147 KB gzip including the model.
+
+```ts
+import { transliterate, slugify, explain } from 'farsit';
+
+transliterate('استقامت در اصفهان');   // "esteghamat dar esfahan"
+slugify('آموزش برنامه‌نویسی ۱۴۰۳');    // "amuzesh-barnamenevisi-1403"
+transliterate('پارچه های زیبا');       // "parche haye ziba"   (phrase ezafe)
+transliterate('نسبتا');                // "nesbatan"            (implicit tanvin)
+explain('استقامت');                    // per-letter trace of every decision
+```
+
+## Use cases
+
+- **URL slugs** for Persian titles (`slugify`)
+- **Usernames and email addresses** from Persian names
+- **Latin filenames** for uploads and exports
+- **Latin-only form fields and tickets** (banking, travel, legacy systems)
+- **Search matching** for users who type in Finglish
+- **Pronunciation hints** for learners and TTS (`explain` shows every decision)
+
+## Install
+
+```sh
+npm install farsit
+```
+
+## API
+
+### `transliterate(text, options?) → string`
+| option | default | |
+|---|---|---|
+| `ezafe` | `true` | Add the ezafe vowel to a word ending in the glide ی (‌های، درختای، خانه‌ی) when another content word follows in the same phrase: `پارچه‌های زیبا` → `parchehaye ziba`. It is skipped at the end of a phrase, before punctuation, conjunctions, prepositions or the copula, and before verb-shaped words. |
+| `longU` | `'u'` | `'oo'` spells long /u/ as `oo` (`noor`). |
+| `layers` | all on | `{ diacritics, morphology, wazn }`: switch individual layers off. |
+| `beam` | `8` | Viterbi beam width. |
+
+### `slugify(text, options?) → string`
+Takes all the options above, plus `separator` (`'-'`), `lowercase` (`true`), `maxLength` (cuts at a word boundary) and `keepDigits` (`true`; Persian and Arabic digits become ASCII).
+
+### `explain(text, options?) → Explanation`
+Returns the normalised input, the output, and for each token its segments, the wazn match, tanvin and ezafe flags, and the per-letter labels with the constraints that produced them.
+
+Also exported: `normalize` (Arabic → Persian letters, digits, ZWNJ cleanup) and `WAZNS`.
+
+## How it works
+
+1. **Normalisation**: unify Arabic/Persian letters, digits and ZWNJ.
+2. **Diacritics**: any harakat present become hard constraints.
+3. **Morphology**: an affix table learned from the training data splits ZWNJ compounds (‌ها، می‌، ‌ترین …).
+4. **Wazn**: Arabic morphological templates (تفعیل، مفعول، افتعال …). Each pattern ships only if it helped on the dev split, with its own score margin and a confidence gate.
+5. **Tanvin**: a structural rule for a word ending in bare ا (نسبتا nesbatan, صراحتا sarahatan).
+6. **Model**: a compact graphone 4-gram trie LM plus a letter-context model, decoded with a Viterbi beam.
+7. **Phrase ezafe**, then rendering to Finglish.
+
+The only fixed pronunciations are 30 closed-class function words (`src/function-words.ts`: و، از، به، که …). There are no lists of names, places or content words. The model is trained on the HomoRich G2P corpus (CC0-1.0).
+
+## Results
+
+Measured on a held-out test split of 4,367 words whose stems never appear in training:
+
+| | |
+|---|---|
+| exact match (cleaned refs) | **67.6 %** · 72.5 % frequency-weighted |
+| exact match (raw HomoRich refs) | 59.2 % · 65.3 % weighted |
+| hand-written slug cases | 99 / 110 |
+| speed (Node, Apple Silicon) | ~20 µs per unique word (~49k words/s); ~110–125k words/s on running text |
+| load | import ~2 ms, first call ~16–17 ms |
+| size | 147 KB gzip / 129 KB brotli (whole library + model) |
+
+See [bench/RESULTS.md](bench/RESULTS.md) for the full numbers, the ablations and a head-to-head against other npm packages.
+
+## Development
+
+`npm test` · `npm run build` · `npm run size` (150 KB gzip budget) · `npm run eval` · `npm run bench` · `npm run train` · `npm run demo` (http://localhost:5180) · `npx tsx tools/regress.ts` (diffs every output against `bench/baseline.json`)
+
+## License
+
+MIT