File size: 5,106 Bytes
003358f 69c05ab 003358f 69c05ab 003358f 69c05ab | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 | ---
language:
- en
license: agpl-3.0
library_name: transformers
base_model: google/bert_uncased_L-2_H-128_A-2
tags:
- cron
- schedules
- text-to-cron
- structured-prediction
- custom-code
model-index:
- name: Cronformer
results:
- task:
type: text-to-cron
name: Natural Language to Cron
dataset:
type: cronformer-broad-fixture
name: Cronformer broad schedule fixture
metrics:
- type: accuracy
name: Full broad top-1 accuracy
value: 0.9961
- type: accuracy
name: Full broad top-2 accuracy
value: 0.9981
- type: accuracy
name: Full broad top-3 accuracy
value: 0.9981
---
# Cronformer
Cronformer is a compact model for converting short English schedule requests
into standard five-field cron expressions:
```text
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`.
```python
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:
```text
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:
```text
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.
|