TickoGrey commited on
Commit
dd60531
·
verified ·
1 Parent(s): bb42ee6

Model card

Browse files
Files changed (1) hide show
  1. README.md +204 -0
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).