pyt-crf 0.1.1

A modern linear-chain CRF (Conditional Random Field) layer for PyTorch

pyt-crf

A modern linear-chain CRF (Conditional Random Field) layer for PyTorch.

• forward() returns the negative log-likelihood directly (ready for .backward())
• decode() runs batched Viterbi decoding
• Batch-first (batch, seq_len, num_tags) by default

Requirements

• Python >= 3.12
• PyTorch >= 2.10

Build

conda activate py312

# build sdist + wheel into dist/ (uses the uv_build backend)
uv build

# or, without uv:
pip install build
python -m build

Install

# from the built wheel
pip install dist/pyt_crf-0.1.0-py3-none-any.whl

# or editable, for development
pip install -e .

Quick usage

import torch
from pyt_crf import CRF

crf = CRF(num_tags=5)
emissions = torch.randn(2, 7, 5)          # (batch, seq_len, num_tags)
tags = torch.randint(5, (2, 7))           # (batch, seq_len)
mask = torch.ones(2, 7, dtype=torch.bool) # True = real token, False = padding

loss = crf(emissions, tags, mask)  # scalar NLL loss
loss.backward()

best_paths = crf.decode(emissions, mask)  # List[List[int]]

[!WARNING] Run the CRF in float32. The forward/Viterbi recursions accumulate logsumexp/max scores over the whole sequence, which is numerically unstable in bf16/fp16. Keep the CRF parameters in fp32 and cast emissions before the layer — crf(emissions.float(), ...) — even when the backbone runs in bf16/autocast.

Examples

• examples/conll2003 — NER fine-tuning on tner/conll2003 with a Gemma3-based backbone + CRF head.

Changelog

• 0.1.0 — initial release; full list of differences from pytorch-crf.

Acknowledgements

• This package mostly follows implementation of kmkurn/pytorch-crf.