A ~144k-parameter transformer tags each token with a semantic role; a deterministic compiler builds a typed schedule; an exact calendar resolver with a bundled IANA timezone database produces the dates. The fuzzy part is learned, the arithmetic is code — wrong labels reject with a diagnostic, never a silently wrong date.

[!WARNING] Pre-release software. Before v1, APIs and JSON shapes may change, and the model's vocabulary coverage is still growing (see known limitations).

---

🚀 Quick Start

npm / TypeScript:

npm install @magicbeansai/what-time

import { parse } from "@magicbeansai/what-time";

const result = await parse("har hafte Tuesday ko gym", {
  reference: new Date().toISOString(),
  timeZone: "Asia/Kolkata",
  limit: 3,
});
// result.occurrences: [{ start: "2026-09-15T00:00:00+05:30", allDay: true }, ...]

CLI (agents welcome):

rust/target/release/what-time "call mom on sunday evening" \
  -r 2026-09-13T10:00:00Z -t Asia/Kolkata
# 2026-09-13T17:00:00+05:30 → 2026-09-13T21:00:00+05:30

echo "कल शाम को आठ बजे" | what-time -j -r 2026-09-13T10:00:00Z -t Asia/Kolkata
# exit 0, full JSON on stdout — 1 parsed / 1 nothing found / 2 bad invocation

Zero-install playground: open rust/site/what-time.html — one self-contained file (wasm inlined) that runs the full trilingual model offline, straight from disk.

---

✨ What it does

---

🏗️ How it works

"call mom on sunday evening"
   │  tokenizer (UTF-16 features; Devanagari conjuncts stay whole)
   ▼
 [neural tagger]  mom→O  sunday→WEEKDAY  evening→DAYPART      ~1 ms
   │  deterministic compiler
   ▼
 schedule: weekday[SU] + day-part evening (typed JSON, no dates yet)
   │  exact resolver (jiff + bundled tzdb, Asia/Kolkata)
   ▼
 2026-09-13T17:00:00+05:30 → 2026-09-13T21:00:00+05:30

1. Tokenization — one scan emits sparse feature rows (character shape, hashes, digit buckets) over UTF-16 units.
2. The model — a two-block, four-head transformer encoder (int8-quantized, ~144k parameters) classifies each token into one of 35 semantic roles plus a clause-boundary score. Trained on generated structural supervision plus gate-checked LLM-authored English/Hindi/Hinglish corpora.
3. Compilation — roles compile into a typed Schedule: date anchors, clocks, ranges, recurrences, durations. The compiler never consults the reference date.
4. Resolution — the resolver applies timezone and DST rules to produce occurrences and RFC 5545 rules.

Full details: MODEL_CARD.md — training data, metrics, and known limitations.

---

📁 Repository layout

---

🛠️ Development

cargo test --manifest-path rust/Cargo.toml    # full suite + gold corpora + parity gates
cargo build --release -p what-time --example featurize   # required before training
cd packages/training && pnpm train            # retrain + export weights
rust/site/build.sh                            # rebuild wasm + static playground
cargo run --release -p what-time --example bench-bulk --features gpu -- 10000  # GPU bulk bench

• To release: follow RELEASING.md — tag-driven, gated, with the one-time npm org setup documented.
• Python is always invoked through uv inside packages/training.
• The Rust toolchain lives at ~/.cargo/bin when not on PATH.
• Weights and parity fixtures move together via the training export; the test suite fails closed if predictions shift. Do not hand-edit them.

---

🤖 Using it from agents

The CLI is designed for programmatic use:

what-time "<phrase>" -j -r <ISO instant> -t <IANA zone> -l <limit>

Exit codes: 0 parsed · 1 no schedule found · 2 bad invocation. JSON mode prints occurrences, rrules, diagnostics, and timings — the same shape the npm package returns. Pipe phrases on stdin when quoting gets hairy (including Devanagari).

---

⚠️ Honest limitations

• Trained phrasing, not all phrasing. Rare vocabulary can mislabel (current known gaps: तारीख/tareekh, roz, Devanagari numerals, for N mins). Known gaps return diagnostics rather than wrong dates, and each is queued for the next corpus batch.
• कल / kal (yesterday or tomorrow) resolves to tomorrow unless a past-tense cue appears — a documented default, not a guess.
• Real-user accuracy is unmeasured. In-distribution scores are excellent (gold corpora 526/526, LLM held-out 0.999) but generated corpora share training families.
• GPU mode pays only in bulk. Single phrases are fastest on CPU (~1 ms); the GPU path activates at ≥64 phrases per call.
• Not for high-stakes scheduling — legal, medical, or billing dates need verified input.

---

📄 License

MIT. This project derives from an MIT-licensed predecessor; the original copyright notice is retained in LICENSE as the license requires.