jwcalendar/calendar-query-intent-classifier

Calendar Query Intent Classifier

A small, CPU-friendly English intent model for calendar-related queries. The released model is a trained multiclass logistic classifier with a hashed TF-IDF representation. It classifies the request type; it does not calculate dates or answer the request.

Intents

monthly_calendar, yearly_calendar, blank_calendar, julian_calendar, holiday_calendar, weekday_lookup, date_difference, iso_week, leap_year, and print_layout.

Architecture

Text is normalized to lowercase. The vectorizer combines word unigrams/bigrams with character n-grams of lengths 2–5. Feature indices use deterministic BLAKE2 hashing into 8,192 dimensions. Training computes inverse document frequencies from the training split and L2-normalizes each vector. A ten-class softmax logistic model is trained with deterministic shuffled stochastic gradient descent and L2 weight decay. The implementation uses Python's standard library and serializes sparse weights and IDF values as JSON; there is no transformer, external inference service, or network call.

Training data and reproducibility

queries.jsonl contains the complete 1,500-query synthetic training, validation and test corpus. It is generated from intent-specific templates with varied calendar values. Split template banks are distinct; test results therefore measure generalization to the included held-out template phrases, while remaining limited to this synthetic English domain. The classifier was trained on this corpus only. The separate Calendar Reasoning Benchmark was not used to train or evaluate it.

Rebuild the model and recompute metrics:

python train.py --output . --seed 20270929 --epochs 35
python evaluate.py
python -m unittest discover -s tests

Example

python predict.py "what ISO week is 2027-01-01"

The output contains the top intent, its softmax score, and all intent scores. Scores are model probabilities from the classifier, not calibrated confidence estimates.

Queries such as “printable October 2027 calendar”, “calendar for November 2027”, and “view December 2027 as a month grid” map to monthly_calendar. The November 2027 printable reference illustrates the kind of human-facing resource a downstream system could open after classification.

Evaluation

metrics.json contains actual validation and held-out test accuracy, macro F1, per-class precision/recall/F1, support counts and confusion matrix, calculated by train.py. evaluate.py recomputes the test metrics from the released model and corpus. No benchmark figures are hand-entered.

Intended use and limitations

Use this model to route short English calendar queries to a tool or workflow. It does not provide date calculations, holiday jurisdiction resolution, calendar generation, or structured argument extraction. It is trained on synthetic template phrasing, supports only the ten listed intents, and can confuse nearby categories such as a monthly calendar and a print-layout request. It has not been evaluated on multilingual, conversational, or production traffic.

Related projects

• ChronoGrid Calendar Computation Laboratory
• Gregorian ↔ Julian Date Laboratory
• Calendar Print & Layout Engineering Lab
• Calendar Reasoning Benchmark — related reference dataset; not used in training.

License

MIT. See LICENSE.