Cronformer

Cronformer is a compact model for converting short English schedule requests into standard five-field cron expressions:

every night at 5pm on tuesdays and wednesdays -> 0 17 * * 2,3

The model is not a text generator. It uses a small BERT encoder and a structured decoder that predicts the cron fields directly: minute, hour, day-of-month, month, and day-of-week.

Quick Start

This repository contains custom Transformers model code. Loading the model requires trust_remote_code=True.

import importlib.util

import torch
from huggingface_hub import hf_hub_download
from transformers import AutoModel, AutoTokenizer

repo_id = "impalasys/cronformer"

model = AutoModel.from_pretrained(repo_id, trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained(repo_id)

cron_py = hf_hub_download(repo_id, "cron.py")
spec = importlib.util.spec_from_file_location("cronformer_release_cron", cron_py)
cron_module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(cron_module)

inputs = tokenizer(
    "every night at 5pm on tuesdays and wednesdays",
    return_tensors="pt",
    max_length=128,
    truncation=True,
    padding="max_length",
)

with torch.no_grad():
    output = model(**inputs)

cron = cron_module.logits_to_cron(output)[0].to_vixie_cron()
print(cron)

Expected output:

0 17 * * 2,3

Architecture

Cronformer is an encoder-only structured prediction model for cron expressions. It does not decode cron as text. Instead, it predicts the cron schema directly.

The model has three main parts:

1. A compact BERT encoder, google/bert_uncased_L-2_H-128_A-2, encodes the input prompt.
2. Five learned field queries attend over the prompt representation, one for each cron field: minute, hour, day-of-month, month, and day-of-week.
3. Learned slot queries specialize each field state into cron decisions such as wildcard/value/list/range/step pattern, selected values, ranges, step sizes, nth weekday, and last-day offsets.

The output is a structured CronOutput object. The bundled cron.py helper turns those logits into a five-field Vixie-style cron string:

minute hour day-of-month month day-of-week

Cronformer does not predict seconds, years, timezone rules, holiday calendars, or execution history.

Version

This is the initial public Cronformer release.

• Version: v0.1.0
• Architecture: field-query Cronformer
• Base encoder: google/bert_uncased_L-2_H-128_A-2
• Parameters: 6,334,826
• Weight file size: 25,368,616 bytes (24.19 MiB)
• Maximum input length: 128 tokens
• License: AGPL-3.0

Evaluation

The released checkpoint was selected from internal Cronformer development as the best current all-around checkpoint for this architecture. The evaluation suites below are project-specific schedule fixtures, not public benchmark datasets.

Suite	Top-1	Top-2	Top-3
Sampled broad schedule fixture	99.50%	100.00%	100.00%
Hard language fixture	100.00%	100.00%	100.00%
Human-authored JSONL fixture	100.00%	100.00%	100.00%
Manual smoke prompts	100.00%	100.00%	100.00%
Full broad schedule fixture	99.61%	99.81%	99.81%

Known top-1 misses on the full broad fixture:

• late evening at 11 PM daily
• every 30 minutes from 9 to 5 on Monday through Friday

For ambiguous business-hour language, showing top-k candidates or confirming the cron expression with the user is recommended.

Intended Use

Cronformer is intended for schedule-authoring interfaces, developer tools, and automation products that need a small local model to propose cron expressions from concise English prompts.

Good fits:

• Suggesting cron expressions in a UI.
• Ranking or displaying multiple candidate schedules.
• Local/offline cron assistance where a large LLM is unnecessary.

Poor fits:

• Legal, medical, financial, or safety-critical scheduling without review.
• Calendar-aware scheduling involving holidays, timezones, daylight saving time, or business-specific blackout windows.
• Natural-language requests that require external state or temporal context.

Limitations

• English-only training/evaluation.
• Five-field cron only.
• Ambiguous prompts may have multiple valid cron interpretations.
• The model can produce syntactically valid but semantically wrong cron strings.
• Evaluation was performed on internal Cronformer fixtures.