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, a 25M-parameter transformer language model trained for typing, with typo repair (optional extratypeling[lm]: PyTorch and Transformers).
Training and evaluation of the language model are in lm/; see 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
pip install typeling # n-gram kernel, no dependencies
pip install "typeling[lm]" # plus the language model decoder (PyTorch, Transformers)
Python API
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:
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
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 ofmodel.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 leastcomplete_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.
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 and 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 --gridprints 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 script; its dependencies (numpy, pyarrow, huggingface_hub) are installed automatically into an isolated environment.
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 | ODC-By 1.0 | writing |
| SODA | allenai/soda | CC BY 4.0 | everyday dialogue (generated by InstructGPT) |
| WildChat-1M | allenai/WildChat-1M | ODC-By 1.0 | real user-typed turns (first 7.5M training words) |
| OpenAssistant oasst2 | OpenAssistant/oasst2 | Apache-2.0 | real user-typed turns |
| Ubuntu IRC | 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 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 (ESDB, formerly SCOWL; MIT-like license) only to detect misspellings.
Project layout
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. The bundled model typeling/en.bin is licensed
under the Open Data Commons Attribution License (ODC-By) 1.0, and
Typeling-25M under the Apache License 2.0; see NOTICE for the required attributions.
Metadata
Release files for typeling 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| typeling-0.1.0.tar.gz | 3.3 MB | With provenance | Details for typeling-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| typeling-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for typeling-0.1.0-py3-none-any.whl |
Total release size: 6.5 MB
Release files / typeling-0.1.0.tar.gz
| Download URL | typeling-0.1.0.tar.gz |
|---|---|
| Size | 3.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5442ee89d6168bc04c560216e41227275359fac87cd31ae18108b248c3c1229d
|
|
BLAKE2b-256 checksum How to use checksums |
e7826d01410e951a04dc50ce0641b17e5ac72f7917ef6b4a685760e6da8fa9cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / typeling-0.1.0-py3-none-any.whl
| Download URL | typeling-0.1.0-py3-none-any.whl |
|---|---|
| Size | 3.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
43d8f529c35e9f18f7f1c5eaa985fc773ee4d4f189267be91a0ff08a307a234e
|
|
BLAKE2b-256 checksum How to use checksums |
168fd0940516ec730696072611c647fbd5bf1cf885da94583582691825e5dd1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for typeling 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for typeling-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.