README.md

---
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.