Metadata-Version: 2.3
Name: pyt-crf
Version: 0.1.1
Summary: A modern linear-chain CRF (Conditional Random Field) layer for PyTorch
Author: id4thomas
Author-email: id4thomas <id2thomas@gmail.com>
Requires-Dist: torch>=2.10
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
# 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

```python
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`](examples/conll2003) — NER fine-tuning on
  [tner/conll2003](https://huggingface.co/datasets/tner/conll2003) with a
  Gemma3-based backbone + CRF head.

## Changelog

- [0.1.0](docs/changelogs/0_1_0.md) — initial release; full list of differences from pytorch-crf.

## Acknowledgements

- This package mostly follows implementation of [kmkurn/pytorch-crf](https://github.com/kmkurn/pytorch-crf).

