typeling 0.1.0__tar.gz

typeling-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

typeling-0.1.0/NOTICE

@@ -0,0 +1,46 @@
+Typeling
+Copyright 2026 The Typeling Authors
+
+The source code is licensed under the Apache License, Version 2.0; see LICENSE.
+
+The model file typeling/en.bin consists of n-gram probabilities (pruned and quantized)
+computed from the datasets below. It is licensed under the Open Data Commons Attribution
+License (ODC-By) v1.0 (https://opendatacommons.org/licenses/by/1-0/). Please retain the
+following attributions when redistributing or using the model:
+
+- FineWeb (HuggingFaceFW/fineweb), Hugging Face — ODC-By 1.0; use is also subject to the
+  Common Crawl Terms of Use
+  https://huggingface.co/datasets/HuggingFaceFW/fineweb
+- SODA (allenai/soda), Kim et al. 2022, "SODA: Million-scale Dialogue Distillation with Social
+  Commonsense Contextualization" — CC BY 4.0
+  https://huggingface.co/datasets/allenai/soda
+- WildChat-1M (allenai/WildChat-1M), Zhao et al. 2024, "WildChat: 1M ChatGPT Interaction Logs in
+  the Wild" — ODC-By 1.0
+  https://huggingface.co/datasets/allenai/WildChat-1M
+- OpenAssistant Conversations Release 2 (OpenAssistant/oasst2), LAION — Apache License 2.0
+  https://huggingface.co/datasets/OpenAssistant/oasst2
+- Ubuntu IRC logs (https://irclogs.ubuntu.com), released into the Public Domain, as packaged by
+  the Common Pile v0.1 (common-pile/ubuntu_irc_filtered), Kandpal et al. 2025
+  https://huggingface.co/datasets/common-pile/ubuntu_irc_filtered
+
+The language model Typeling-25M (https://huggingface.co/ScarletKc/Typeling-25M), used by
+typeling/lm.py and distributed separately, is licensed under the Apache License, Version 2.0. It
+is SupraLabs/Supra2-Medium-Base (Apache License 2.0,
+https://huggingface.co/SupraLabs/Supra2-Medium-Base) further trained on the datasets above.
+
+The words that the model never suggests by default are taken from the List of Dirty, Naughty,
+Obscene, and Otherwise Bad Words — CC BY 4.0
+  https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words
+
+Likely misspellings are identified with word lists generated from the English Speller Database
+(ESDB, formerly SCOWL), https://github.com/en-wl/wordlist, under the following notice:
+
+  Copyright 2000-2026 by Kevin Atkinson
+
+  Permission to use, copy, modify, distribute, and sell any part of the English
+  Speller Database (ESDB, previously known as SCOWLv2), or word lists
+  created from it, is hereby granted without fee, provided that the above
+  copyright notice appears in all copies and that both the above copyright
+  notice and this notice appear in supporting documentation.  Kevin Atkinson
+  makes no representations about the suitability of this database for any
+  purpose.  It is provided "as is" without express or implied warranty.

typeling-0.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: typeling
+Version: 0.1.0
+Summary: Offline English typing prediction: completes the current word, predicts the next one and fixes typos; a pure-Python n-gram kernel and an optional small language model.
+Author: scarletkc
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/scarletkc/typeling
+Project-URL: Source, https://github.com/scarletkc/typeling
+Project-URL: Issues, https://github.com/scarletkc/typeling/issues
+Keywords: autocomplete,word prediction,next-word prediction,language model,kneser-ney,n-gram,typo correction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: lm
+Requires-Dist: torch>=2.7; extra == "lm"
+Requires-Dist: transformers>=5; extra == "lm"
+Dynamic: license-file
+
+# Typeling
+
+Offline English typing prediction: completes the word being typed, predicts the next word and fixes typos.
+
+The `typeling` package has two predictors with the same interface:
+
+- `typeling.Predictor`: a dependency-free n-gram kernel in pure Python with a bundled 5 MB model.
+- `typeling.lm.LMPredictor`: the typing decoder for [Typeling-25M](https://huggingface.co/ScarletKc/Typeling-25M),
+  a 25M-parameter transformer language model trained for typing, with typo repair (optional extra
+  `typeling[lm]`: PyTorch and Transformers).
+
+Training and evaluation of the language model are in `lm/`; see [docs/model-plan.md](docs/model-plan.md) for the plan,
+the experiments and their results.
+
+## Features
+
+- **Offline and private.** No network access at runtime (the language model is downloaded once); what the user types
+  never leaves the machine.
+- **Pure Python, no dependencies.** The n-gram kernel uses only the standard library (Python 3.13+).
+- **Small and fast.** The bundled n-gram model is at most 5 MB, loads in milliseconds and answers a keystroke in tens
+  of microseconds; the language model answers in tens of milliseconds on a laptop CPU.
+- **Completion and prediction.** Completes the current word (`Let me kn` → `ow`) and predicts the next one after a
+  space (`Thank you so ` → `much`), as ghost text or as a bar of candidates.
+- **Typo repair.** With the language model, mistyped words are corrected from keyboard errors (`See you tomm` →
+  *tomorrow*, `What do you thnik` → *think*).
+- **Natural output.** Handles contractions such as *I'm* and *don't* and restores casing (*I*, *English*, sentence
+  starts, ALL-CAPS input).
+- **Learns locally.** Adapts to the user's own words and phrases and stores them in a local JSON file.
+- **Unobtrusive.** Ghost text is shown only above a confidence threshold, offensive words are not suggested by
+  default, and common misspellings found in real typing (*recieve*, *definately*) are never suggested.
+- **Permissively licensed data.** The model is built only from openly licensed corpora (ODC-By, CC BY, Apache-2.0).
+
+## Quick start
+
+```bash
+pip install typeling            # n-gram kernel, no dependencies
+pip install "typeling[lm]"      # plus the language model decoder (PyTorch, Transformers)
+```
+
+### Python API
+
+```python
+from typeling import Predictor
+
+p = Predictor()
+p.suggest("Let me kn")         # 'ow'    ghost text to display after the cursor
+p.suggest("Thank you so ")     # 'much'  after a space, the next word is predicted
+p.suggest("Hello,")            # ''      nothing is shown when no confident suggestion exists
+p.topk("I'll see you ", 3)     # [(word, probability), ...] best full words, ignoring the display thresholds
+
+p = Predictor(user="path/to/user.json")   # enable persistent learning
+p.learn("Our project is called Zorblaxa.")
+p.suggest("I love Zorb")       # 'laxa'  learned words are suggested too
+p.save()                       # write the user model back to user.json
+```
+
+`suggest(text)` and `topk(text, k)` take the text before the cursor. `Predictor` also accepts `model` (path to an
+alternative model file) and the keyword-only options `next_threshold` (default 0.3), `complete_threshold` (0.3),
+`cache_weight` (0.1), `allow_blocked` (False) and `use_context` (True).
+
+With the language model:
+
+```python
+from typeling.lm import LMPredictor
+
+p = LMPredictor()                    # downloads ScarletKc/Typeling-25M once; or a repo id / local directory
+p.topk("See you tomm", 3)            # [('tomorrow', ...), ...]  corrections are candidates too
+p.suggest("Let me kn")               # 'ow'    ghost text only extends what was typed
+p.topk("I'm going to ", 5)           # the top 3 are exact, further candidates are best effort
+```
+
+`LMPredictor(model, user)` takes the same user model file as `Predictor`, with the same `learn()` and `save()`. It
+also accepts `device` (`"cpu"` or `"cuda"`, default: CUDA if available), `typo_weight` (default 0.003, 0 turns typo
+repair off), `ngram_weight` (0.1, share of the n-gram model in the probabilities), `context_chars` (1000),
+`beam` (8), `allow_blocked` and the display thresholds.
+
+### Terminal demo
+
+```bash
+python -m typeling                  # or: typeling
+python -m typeling --lm             # use Typeling-25M (needs typeling[lm]); --lm DIR for a local model
+python -m typeling --no-learn       # do not learn or save your words
+python -m typeling --bench          # measure per-keystroke latency
+echo "I wan" | python -m typeling   # pipe mode: prints "I wan[t]"
+```
+
+The line shows the best suggestion as grey ghost text; the bar below it shows the top candidates.
+
+| Key | Action |
+|---|---|
+| Tab / Right | accept the highlighted candidate (the first one by default; it replaces a mistyped word) |
+| Up / Down | move the highlight in the candidate bar |
+| Esc | hide the suggestions |
+| Ctrl+W | delete the previous word |
+| Enter | new line (the finished line is learned unless `--no-learn` is given) |
+| Ctrl+C | quit |
+
+Learned words are stored in `~/.typeling/user.json` (used by both models) and saved on exit.
+
+## How it works
+
+- **Tokenizer** (`text.py`): words (with inner apostrophes), numbers, sentence boundaries, commas and other
+  punctuation. Training and runtime share the same rules.
+- **Language model** (`model.py`): an interpolated modified Kneser-Ney trigram model over a 60,000-word vocabulary,
+  pruned with the weighted-difference criterion (Seymore & Rosenfeld) to fit a 5 MB budget, with probabilities
+  quantized to one byte. Words are stored alphabetically, so all completions of a prefix form one contiguous id
+  range. The binary format is documented at the top of `model.py`.
+- **Scoring** (`predictor.py`): the n-gram probability is mixed with a document cache (words used earlier in the same
+  text) and the user model (`user.py`, unigram and bigram counts of what the user typed), whose weight grows as more
+  text is learned.
+- **Display**: a next-word prediction is shown only if its probability is at least `next_threshold`; a completion
+  only if its probability given the typed prefix is at least `complete_threshold`.
+- **Spelling filter**: the chat corpora contain real typos, so at build time every vocabulary word that is missing
+  from a speller dictionary (and from a short list of internet slang such as *lol*, *idk*, *tbh*), is usually written
+  in lowercase, and is one edit (two for words of 8+ letters) away from a dictionary word at least 20 times as common
+  is marked as a misspelling. Such words still serve as context but are never suggested.
+
+## Evaluation
+
+`bench/eval.py` simulates typing the held-out dev split of each corpus (created by `uv run training/build.py fetch`)
+and reports how much the suggestions help. For each word it "types" 0, 1, 2, ... letters; when the top suggestion is
+the target word and passes the display threshold, the simulated user accepts it with one keystroke (ghost text);
+with a candidate bar, the user picks the target with one keystroke as soon as it is among the top 3. `lm/eval.py`
+runs the same simulation on the language model, and `--typos` repeats it with every word mistyped.
+
+```bash
+python bench/eval.py                                                # dev split, all sources
+python bench/eval.py --limit 2000 --sources soda fineweb --no-save   # quick run
+```
+
+| Option | Meaning |
+|---|---|
+| `--limit N` | at most N target words per source (default 20000, 0 = no limit) |
+| `--sources ...` | corpora to evaluate (default: soda wildchat oasst2 irc fineweb) |
+| `--model PATH` | evaluate another model file |
+| `--no-context` | ablation: ignore the context (typed letters and word frequency only) |
+| `--learn` | call `learn()` after each segment to simulate user learning |
+| `--cache W` | override the cache weight |
+| `--grid` | also print KSR / precision for a grid of display thresholds |
+| `--final` | use the sealed test split (final comparisons only) |
+| `--note TEXT` | note stored with the results |
+| `--no-save` | do not append the results to `bench/results.jsonl` |
+
+| Metric | Definition |
+|---|---|
+| KSR | keystroke savings rate with ghost text: 1 − keystrokes used / letters in the target words |
+| Precision | share of displayed suggestions that were accepted |
+| Shown | suggestions displayed per word |
+| KSR@3 | keystroke savings rate with a bar of the top 3 candidates, always shown |
+| acc@i | share of words whose top candidate is correct after typing i letters (acc@0 = next-word accuracy) |
+| top3@i | share of words among the top 3 candidates after typing i letters |
+| OOV | share of words missing from the model vocabulary |
+
+Results are reported per source and pooled into *chat* (SODA, WildChat, oasst2), *casual* (Ubuntu IRC) and
+*writing* (FineWeb).
+
+## Results
+
+**Typeling-25M against the n-gram kernel**, on the sealed test split (2,000 words per source; KSR with ghost text /
+KSR@3 with a bar of 3 candidates):
+
+| Domain | n-gram, bundled 5 MB | n-gram, unpruned 23 MB | Typeling-25M |
+|---|---|---|---|
+| chat (SODA, WildChat, oasst2) | 31.6% / 48.8% | 34.1% / 50.6% | **43.1% / 58.0%** |
+| casual (Ubuntu IRC) | 22.7% / 38.9% | 24.4% / 40.4% | **29.8% / 46.8%** |
+| writing (FineWeb) | 22.3% / 40.6% | 23.9% / 41.5% | **32.4% / 49.9%** |
+
+With every word of 3+ letters mistyped, chat KSR drops from 32.1% to 22.7% with the n-gram kernel and from 44.5% to
+40.1% with Typeling-25M, which repairs the errors (86% of the mistyped words end correct, against 48%). Next-word
+accuracy, typo results per domain, latency and training details are in the
+[model card](https://huggingface.co/ScarletKc/Typeling-25M) and [docs/model-plan.md](docs/model-plan.md).
+
+**The n-gram kernel** on the dev split, bundled 5.00 MB model, default thresholds (next word 0.3, completion 0.3),
+20,000 target words per source (oasst2: all 9,251), measured with `python bench/eval.py`:
+
+| Domain | Source | KSR | Precision | Shown | KSR@3 | acc@0 | top3@0 | top3@1 | top3@2 | OOV |
+|---|---|---|---|---|---|---|---|---|---|---|
+| chat | SODA | 37.3% | 58.3% | 1.44 | 54.5% | 28.6% | 46.6% | 80.8% | 89.6% | 0.3% |
+| chat | WildChat | 30.3% | 47.8% | 1.59 | 46.7% | 21.3% | 32.4% | 59.4% | 69.5% | 2.0% |
+| chat | oasst2 | 26.2% | 46.4% | 1.62 | 44.3% | 18.1% | 30.3% | 61.3% | 72.4% | 1.3% |
+| casual | Ubuntu IRC | 22.8% | 43.8% | 1.58 | 39.6% | 13.8% | 24.5% | 54.9% | 69.6% | 1.7% |
+| writing | FineWeb | 23.1% | 43.2% | 1.68 | 41.7% | 14.3% | 23.8% | 51.1% | 64.4% | 2.9% |
+| **chat** | pooled | **32.1%** | **51.5%** | 1.54 | **49.1%** | | | | | |
+| **casual** | pooled | **22.8%** | **43.8%** | 1.58 | **39.6%** | | | | | |
+| **writing** | pooled | **23.1%** | **43.2%** | 1.68 | **41.7%** | | | | | |
+
+- **Context matters.** With `--no-context` (typed letters and word frequency only), KSR with every suggestion shown
+  drops to 15.3% (chat), 13.8% (casual) and 14.4% (writing), and next-word accuracy to about 2%.
+- **Thresholds trade savings for precision.** Lowering both thresholds to 0.15 raises chat KSR to 34.9% at 41%
+  precision; raising them to 0.5 gives 27.9% at 65%. `python bench/eval.py --grid` prints the full grid.
+- **Speed.** A query takes 41–115 µs on average (p99 under 0.7 ms on long FineWeb documents) in pure Python on a
+  laptop CPU; the model loads in under 50 ms. Typeling-25M takes 23–25 ms on chat and 33 ms on long text (PyTorch,
+  4 CPU threads).
+
+## Building the model
+
+The build script is a [uv](https://docs.astral.sh/uv/) script; its dependencies (numpy, pyarrow, huggingface_hub)
+are installed automatically into an isolated environment.
+
+```bash
+uv run training/build.py fetch    # download and clean the corpora into data/corpus/
+uv run training/build.py model    # count, prune and export typeling/en.bin (about 30 s)
+uv run training/build.py          # both steps
+```
+
+`fetch` skips sources that are already downloaded and accepts `--sources`. `model` accepts `--out PATH` (default
+`typeling/en.bin`), `--budget BYTES` (default 5e6), `--min-count N` (drop n-grams seen fewer than N times,
+default 2) and `--workers N` (default 8).
+
+Each corpus is cleaned (emails, URLs and phone numbers are removed; chat sources keep only turns that look typed by a
+person), and about 1% is held out as the dev split and 1% as the test split by content hash.
+
+| Corpus | Dataset | License | Used for |
+|---|---|---|---|
+| FineWeb | [HuggingFaceFW/fineweb](https://huggingface.co/datasets/HuggingFaceFW/fineweb) | ODC-By 1.0 | writing |
+| SODA | [allenai/soda](https://huggingface.co/datasets/allenai/soda) | CC BY 4.0 | everyday dialogue (generated by InstructGPT) |
+| WildChat-1M | [allenai/WildChat-1M](https://huggingface.co/datasets/allenai/WildChat-1M) | ODC-By 1.0 | real user-typed turns (first 7.5M training words) |
+| OpenAssistant oasst2 | [OpenAssistant/oasst2](https://huggingface.co/datasets/OpenAssistant/oasst2) | Apache-2.0 | real user-typed turns |
+| Ubuntu IRC | [common-pile/ubuntu_irc_filtered](https://huggingface.co/datasets/common-pile/ubuntu_irc_filtered) | Public Domain | informal internet chat (messages that look like commands or code are dropped) |
+
+The bundled model was built from 55M tokens: FineWeb 18.5M words, SODA 16.3M, WildChat 7.5M, Ubuntu IRC 4.4M and
+oasst2 0.4M.
+
+The [LDNOOBW](https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words) English word list
+(CC BY 4.0) is used only to mark offensive words, and the American, British and Canadian word lists of the
+[English Speller Database](https://github.com/en-wl/wordlist) (ESDB, formerly SCOWL; MIT-like license) only to
+detect misspellings.
+
+## Project layout
+
+```text
+typeling/              runtime package (standard library only, except lm.py)
+  predictor.py         public API: Predictor
+  model.py             binary model format and n-gram scoring
+  text.py              tokenizer shared by training and runtime
+  user.py              local user model
+  keyboard.py          QWERTY typing-error model
+  lm.py                language model decoder: LMPredictor (typeling[lm])
+  demo.py              terminal demo (python -m typeling)
+  en.bin               bundled model
+training/build.py      corpus download and n-gram model build
+bench/eval.py          typing-simulation benchmark
+tests/                 unit tests (python -m unittest discover tests)
+lm/                    Typeling-25M: data, training, typo experiments and benchmark (PyTorch, uv scripts)
+docs/model-plan.md     plan and results for Typeling-25M
+```
+
+## License
+
+The code is licensed under the [Apache License 2.0](LICENSE). The bundled model `typeling/en.bin` is licensed
+under the [Open Data Commons Attribution License (ODC-By) 1.0](https://opendatacommons.org/licenses/by/1-0/), and
+Typeling-25M under the Apache License 2.0; see [NOTICE](NOTICE) for the required attributions.