Model card
Browse files
README.md
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: mit
|
| 3 |
+
library_name: picacho
|
| 4 |
+
tags:
|
| 5 |
+
- email
|
| 6 |
+
- date-parsing
|
| 7 |
+
- natural-language-time
|
| 8 |
+
- rrule
|
| 9 |
+
- multilingual
|
| 10 |
+
---
|
| 11 |
+
|
| 12 |
+
# Epoch TBS: the date and time model
|
| 13 |
+
|
| 14 |
+
The model behind **Settings → Local AI → Understand typed dates**. Where
|
| 15 |
+
Picacho asks when (Snooze, Send Later), a field takes a time typed in words,
|
| 16 |
+
typos and all, in 37 languages, and sets the calendar and clock to it:
|
| 17 |
+
|
| 18 |
+
| Typed | Read as (from Sunday, Nov 15, 14:20) |
|
| 19 |
+
| --- | --- |
|
| 20 |
+
| `tmrw at 6`, `remind me to call mom tomorow at 6 pls` | Mon, Nov 16, 18:00 |
|
| 21 |
+
| `next fri 3pm`, `Wensday mornin` | Fri, Nov 20, 15:00 · Wed, Nov 18, 8:00 |
|
| 22 |
+
| `the monday in three weeks` | Mon, Nov 30, 8:00 |
|
| 23 |
+
| `start of next week at 7am` | Mon, Nov 16, 7:00 |
|
| 24 |
+
| `in 4 hours at the top of the hour` | 19:00 |
|
| 25 |
+
| `overmorrow at noon`, `in a fortnight` | Tue, Nov 17, 12:00 · Sun, Nov 29, 14:20 |
|
| 26 |
+
| `friday after next`, `a week from friday`, `the first monday of next month` | Nov 27 · Nov 27 · Dec 7 |
|
| 27 |
+
| `this time tomorrow`, `end of next month`, `mid next month` | Nov 16, 14:20 · Dec 31, 17:00 · Dec 15 |
|
| 28 |
+
| `every other monday @ 9:30am` | Mon, Nov 16, 9:30, and `FREQ=WEEKLY;INTERVAL=2;BYDAY=MO;BYHOUR=9;BYMINUTE=30` |
|
| 29 |
+
| `Erinnere mich übermorgen um 18:30 Uhr` | Tue, Nov 17, 18:30 |
|
| 30 |
+
| `rappelle-moi vendredi prochain à 18h30` | Fri, Nov 20, 18:30 |
|
| 31 |
+
| `recuérdame pasado mañana a las 6 de la tarde` | Tue, Nov 17, 18:00 |
|
| 32 |
+
| `明天下午6点半提醒我`, `来週の金曜日の午後3時`, `내일 오후 6시 30분` | Nov 16, 18:30 · Nov 20, 15:00 · Nov 16, 18:30 |
|
| 33 |
+
| `कल शाम ६ बजे`, `غدا الساعة ٦ مساء`, `พรุ่งนี้ 6 โมงเย็น` | Mon, Nov 16, 18:00 |
|
| 34 |
+
| `через 2 часа`, `2 saat sonra` | 16:20 |
|
| 35 |
+
| `may i ask a question`, `I sat down with the team on the 2nd floor` | nothing |
|
| 36 |
+
|
| 37 |
+
Nothing ships inside the app. Turning the feature on downloads one file from
|
| 38 |
+
[pinaltech/epoch-tbs](https://huggingface.co/pinaltech/epoch-tbs) (in the
|
| 39 |
+
[Picacho Models](https://huggingface.co/collections/pinaltech/picacho-models-6af95b1ea617ddc3325ee964)
|
| 40 |
+
collection), checks its size and SHA-256 against the values built into the
|
| 41 |
+
app (`WHEN` in `src/manage/local_ai/mod.rs`), and keeps it in the data
|
| 42 |
+
directory under `models/`. Turning the feature (or Local AI) off, or
|
| 43 |
+
deleting the model in Settings, deletes it. The model file isn't kept in
|
| 44 |
+
git.
|
| 45 |
+
|
| 46 |
+
| File | Used on | Runtime |
|
| 47 |
+
| --- | --- | --- |
|
| 48 |
+
| `tbs-v1.bin` | every platform | Picacho's own (`NativeTagger` in `src/manage/local_ai/runtime.rs`) |
|
| 49 |
+
|
| 50 |
+
It runs on every keystroke on any CPU: a few thousand multiply-adds per
|
| 51 |
+
token, less than one Core ML call would cost, so there is no Core ML
|
| 52 |
+
version.
|
| 53 |
+
|
| 54 |
+
## Languages
|
| 55 |
+
|
| 56 |
+
English, Spanish, German, French, Portuguese, Italian, Dutch, Swedish,
|
| 57 |
+
Polish, Japanese, Chinese (simplified and traditional), Korean, Russian,
|
| 58 |
+
Ukrainian, Turkish, Arabic, Persian, Hebrew, Hindi (and Hindi in Latin
|
| 59 |
+
letters), Bengali, Indonesian, Malay, Vietnamese, Thai, Greek, Czech,
|
| 60 |
+
Slovak, Danish, Norwegian, Finnish, Romanian, Hungarian, Catalan, Croatian,
|
| 61 |
+
Bulgarian, Tagalog and Swahili, the same as
|
| 62 |
+
[Veil OTP](https://huggingface.co/pinaltech/veil-otp), with times in ASCII,
|
| 63 |
+
fullwidth, Arabic-Indic, Persian, Devanagari, Bengali and Thai digits.
|
| 64 |
+
|
| 65 |
+
## How it works
|
| 66 |
+
|
| 67 |
+
Two steps, so the model does the reading and never the arithmetic.
|
| 68 |
+
|
| 69 |
+
1. **The model labels tokens.** Text is split into lowercase runs of
|
| 70 |
+
letters (with the vowel signs written on them), runs of digits in any of
|
| 71 |
+
the scripts above (read as ASCII digits), single characters of scripts
|
| 72 |
+
written without spaces (Chinese, Japanese, Thai), and `: / - . , @ +`
|
| 73 |
+
(`6pm` is `6`, `pm`; `明天6点` is `明`, `天`, `6`, `点`). For each token
|
| 74 |
+
the model says what it means (`features.LABELS`, 104 labels): `TOMORROW`,
|
| 75 |
+
`OVERMORROW`, `FRI`, `NOV`, `U_HOUR`, `U_FORTNIGHT`, `PM`, `NUM`, `NEXT`,
|
| 76 |
+
`START`, `TOP`, `MONTH_MARK` (the 月 of 11月), `W20` (twenty, twentieth)...
|
| 77 |
+
or `O`, no part of a time. Features: the token, its first and last three
|
| 78 |
+
letters, its letter trigrams, its *skeleton* (first letter and consonants
|
| 79 |
+
without repeats, so `tomorrow`, `tommorow` and `tmrw` are all `tmrw`),
|
| 80 |
+
digit count and value bucket, whether it touches its neighbours (`2nite`,
|
| 81 |
+
`6pm`, `18h30`), and the three tokens on each side. Hashed into 16,384
|
| 82 |
+
slots → 32 hidden units (ReLU) → softmax. The embedding is stored as
|
| 83 |
+
8-bit integers with a scale per row.
|
| 84 |
+
2. **Rules work out the moment** (`src/manage/local_ai/when.rs`) from the
|
| 85 |
+
labels and the current local time. They read meanings, not words, so one
|
| 86 |
+
set serves every language and word order ("vendredi prochain" and "next
|
| 87 |
+
friday", "3 giorni fa" and "il y a 3 jours", "下午6点" and "6pm"):
|
| 88 |
+
- A day without a time is at 8:00, as Picacho's own quick choices;
|
| 89 |
+
morning 8:00, afternoon 14:00, evening 19:00, night and tonight 20:00,
|
| 90 |
+
the end of a day, week, month or year 17:00.
|
| 91 |
+
- A bare hour on a named day is in the afternoon up to 6 and the morning
|
| 92 |
+
from 7 (`tomorrow at 6` is 18:00, `friday at 9` is 9:00); a time alone
|
| 93 |
+
is its next time (`at 3` at 14:20 is 15:00, `at 2` is 2:00 tomorrow).
|
| 94 |
+
- `friday` and `this friday` are the coming Friday (today, while the
|
| 95 |
+
time is still to come); `next friday` is the first Friday after today;
|
| 96 |
+
`friday next week`, `下周五` and `the monday in three weeks` are that
|
| 97 |
+
day in that week; `friday after next` is a week after next Friday.
|
| 98 |
+
- `next week` is next Monday, `next month` the 1st; `start`, `middle`
|
| 99 |
+
and `end` of a week are Monday, Wednesday and Friday, of a month the
|
| 100 |
+
1st, the 15th and the last day; said of this one, they are the next
|
| 101 |
+
such day.
|
| 102 |
+
- A date without a year is this year, or next year once it has passed.
|
| 103 |
+
A date in numbers follows the computer's region (`3/4` is March 4 in
|
| 104 |
+
the US, 3 April in the UK), unless a number can't be a month; dates
|
| 105 |
+
with dots (`21.11.`) put the day first.
|
| 106 |
+
- `in 3 days`, `2 weeks from now`, `3 days ago`, `in a fortnight` count
|
| 107 |
+
from now; `in 3 days at 5pm` takes the day and sets the time; `a week
|
| 108 |
+
from friday` and `2 weeks from tomorrow` count from that day; `at the
|
| 109 |
+
top of the hour` moves to the next full hour; `this time tomorrow`
|
| 110 |
+
keeps the time it is now.
|
| 111 |
+
- Repeating times (`every`, `daily`, `weekly`, `every other`, `every 2
|
| 112 |
+
weeks`, `every fortnight`, `weekdays`, `毎週月曜日`) give an RRULE
|
| 113 |
+
(RFC 5545) and their first time. Snooze and Send Later happen once, so
|
| 114 |
+
they use the first time.
|
| 115 |
+
- Text with nothing that anchors a time (`at home`, `6 apples`, `the
|
| 116 |
+
second one`) gives nothing.
|
| 117 |
+
|
| 118 |
+
`features.py` is the reference for the tokens and features; the app builds
|
| 119 |
+
the same, and `parity.json` (tokens, features, vectors, labels and
|
| 120 |
+
probabilities for texts in many languages and scripts) is checked by `cargo
|
| 121 |
+
test matches_the_training_code`.
|
| 122 |
+
|
| 123 |
+
## Training data
|
| 124 |
+
|
| 125 |
+
`data.py` and `languages.py` write the text; nothing in it is real. Every
|
| 126 |
+
text is different (repeats are dropped), and about three in four have a
|
| 127 |
+
time in them:
|
| 128 |
+
|
| 129 |
+
- **English** (about two in five texts), rendered from building blocks in
|
| 130 |
+
many orders, often inside other words (`remind me to pay rent ... pls`,
|
| 131 |
+
`pay the 6 invoices ...`): relative days (`overmorrow`), weekdays,
|
| 132 |
+
month-day and numeric dates, clock times in digits and words, `half
|
| 133 |
+
past`/`quarter to`/`quarter after`, parts of the day, lengths of time
|
| 134 |
+
(`fortnight`, `1h30`, `an hour and a half`), weeks from now (`the monday
|
| 135 |
+
in three weeks`, `friday next week`, `the week after next`), the start,
|
| 136 |
+
middle and end of periods, the nth weekday of a month, days counted from
|
| 137 |
+
a day (`a week from friday`), `this time tomorrow`, `first thing monday`,
|
| 138 |
+
`at the top of the hour`, repeating times, `now`/`later`.
|
| 139 |
+
- **36 other languages**, each with its own words for every meaning
|
| 140 |
+
(including inflected forms, abbreviations and the spellings people type
|
| 141 |
+
without accents) and its own word order: "next" before or after
|
| 142 |
+
(`nächsten Freitag`, `vendredi prochain`, `jumat depan`), "in" and "ago"
|
| 143 |
+
as prefix or postfix (`dans 2 heures`, `2 saat sonra`, `il y a 3 jours`,
|
| 144 |
+
`3日前`), clock styles (`18h30`, `a las 6 y media`, `6点半`, `साढ़े 6 बजे`,
|
| 145 |
+
`6 โมงเย็น`), dates (`21. November`, `21 de noviembre`, `11月21日`,
|
| 146 |
+
`11월 21일`, `ngày 21 tháng 11`), and Swahili's unit before the count.
|
| 147 |
+
- **Texts without a time**, many with words that look like part of one:
|
| 148 |
+
`may i`, `sat down`, `the sun is out`, `the second draft`, `room 204`,
|
| 149 |
+
`6 apples`, `3-2 score`, `9 to 5 job`, `1st place`, `good morning`,
|
| 150 |
+
`guten Morgen`, `buenas noches`, `หน้า 21` (page 21; หน้า is also "next").
|
| 151 |
+
- **Untidy typing**: common misspellings and abbreviations of every word,
|
| 152 |
+
random slips (a letter dropped, doubled, swapped or a neighbouring key),
|
| 153 |
+
accents left off, all lowercase or all capitals, missing spaces (`6pm`,
|
| 154 |
+
`@6`, `1h30`), and broken grammar (`in 2 hour`, `6 tomorow`, `fri 3pm`).
|
| 155 |
+
|
| 156 |
+
## Training
|
| 157 |
+
|
| 158 |
+
```sh
|
| 159 |
+
python3 train.py # numpy only: tbs-v1.bin, parity.json, eval.json
|
| 160 |
+
```
|
| 161 |
+
|
| 162 |
+
It takes about 25 minutes on a laptop CPU (`--final-only` trains just the published model) and is deterministic. The
|
| 163 |
+
spellings, the surrounding wording and the texts without a time are split
|
| 164 |
+
in two: a model trained on one half is measured on the other, then the
|
| 165 |
+
published model learns from everything.
|
| 166 |
+
|
| 167 |
+
| Measured on | Time tokens right | Texts exactly right | Texts without a time left alone |
|
| 168 |
+
| --- | --- | --- | --- |
|
| 169 |
+
| Wording and spellings seen in training | 99.2% | 97.4% | 98.6% |
|
| 170 |
+
| Held-out wording and spellings | 94.1% | 67.5% | 53.5% |
|
| 171 |
+
| Published model, fresh texts (8-bit) | 99.2% | 97.3% | 98.0% |
|
| 172 |
+
|
| 173 |
+
The held-out row is the honest figure for spellings and sentences the model
|
| 174 |
+
has never seen (measured before Thai, Vietnamese, Indonesian, Swedish and
|
| 175 |
+
Ukrainian were given more of the data); many of its misses are labels the
|
| 176 |
+
rules ignore anyway. What matters is the moment: on `eval.json` (4,000 fresh
|
| 177 |
+
texts from the held-out wording, in every language) the published model's
|
| 178 |
+
labels give the same moment and rule as the true labels for **98.6%** of
|
| 179 |
+
texts (98.4% of those with a time). By language:
|
| 180 |
+
|
| 181 |
+
| | | | | | | | |
|
| 182 |
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
| 183 |
+
| en 98.5% | de 99.3% | es 98.5% | fr 98.4% | pt 99.1% | it 100% | nl 100% | sv 100% |
|
| 184 |
+
| da 100% | no 100% | pl 100% | ru 100% | uk 100% | cs 96.3% | sk 97.0% | hr 95.8% |
|
| 185 |
+
| bg 97.4% | ro 100% | hu 96.3% | fi 90.0% | el 96.8% | tr 100% | ar 100% | fa 100% |
|
| 186 |
+
| he 100% | hi 100% | hi (Latin) 98.4% | bn 100% | id 97.6% | ms 100% | vi 92.2% | th 96.6% |
|
| 187 |
+
| ja 100% | zh 100% | zh-Hant 100% | ko 100% | tl 96.6% | sw 100% | ca 100% | |
|
| 188 |
+
|
| 189 |
+
Smaller languages have 20–60 texts each, so their figures move a few points
|
| 190 |
+
between runs; the wording is synthetic, and real typing will have
|
| 191 |
+
phrasings the templates don't cover. Storing the embedding in 8 bits costs
|
| 192 |
+
nothing measurable. The file is 604 KB: 16,384 rows of 32 weights.
|
| 193 |
+
|
| 194 |
+
## Publishing a new version
|
| 195 |
+
|
| 196 |
+
1. Retrain, then update the size and digest `train.py` prints in `WHEN` in
|
| 197 |
+
`src/manage/local_ai/mod.rs`. Bump the version in the file name when the
|
| 198 |
+
features or labels change.
|
| 199 |
+
2. Upload it before releasing the app that names it:
|
| 200 |
+
`hf upload pinaltech/epoch-tbs models/tbs/tbs-v1.bin tbs-v1.bin`, and
|
| 201 |
+
this README as the model card:
|
| 202 |
+
`hf upload pinaltech/epoch-tbs models/tbs/README.md README.md`.
|
| 203 |
+
3. `cargo test the_published_models_are_the_ones_the_app_expects` checks
|
| 204 |
+
the uploaded file (delete `target/test-models` first).
|