sklearn-crfsuite

sklearn-crfsuite wraps python-crfsuite bindings to the CRFsuite C library behind a scikit-learn compatible CRF estimator, so sequence labeling tasks like named entity recognition and part-of-speech tagging can be trained and evaluated with the same fit/predict/score interface, cross-validation utilities, and GridSearchCV/Pipeline integration developers already use for other scikit-learn models.

It supports five CRFsuite training algorithms (L-BFGS, SGD with L2, Averaged Perceptron, Passive Aggressive, AROW), exposes post-fit inspection attributes for feature weights and transitions, and includes token-level and sequence-level metrics (flat_f1_score, flat_classification_report, sequence_accuracy_score) built on top of sklearn.metrics for evaluating tagger performance.

What You Get

• A scikit-learn compatible CRF estimator with fit/predict/predict_marginals and score methods
• Support for five CRFsuite training algorithms selectable via a single algorithm parameter
• Automatic on-disk model file handling that makes trained CRF models picklable with joblib
• Token-level and sequence-level evaluation metrics (flat_f1_score, flat_classification_report, sequence_accuracy_score)
• Post-fit introspection attributes exposing learned state and transition feature weights

Common Use Cases

• Named entity recognition on tokenized text using per-token feature dictionaries
• Part-of-speech tagging pipelines that need cross-validation and hyperparameter search via GridSearchCV
• Sequence labeling tasks such as chunking or slot filling where a discriminative CRF outperforms simpler classifiers
• Benchmarking CRF taggers with sklearn-standard classification reports at the token level

Under The Hood

Architecture The package is a thin wrapper (sklearn_crfsuite/estimator.py) around python-crfsuite (pycrfsuite bindings to the CRFsuite C library). The CRF class extends a BaseEstimator compatibility shim (compat.py) and implements fit/predict per scikit-learn conventions. Model persistence is handled via FileResource (_fileresource.py), which manages a temp or user-specified on-disk crfsuite model file so pickling works despite the underlying C-level Tagger object not being directly picklable. Training is delegated to LinePerIterationTrainer (trainer.py), a subclass of pycrfsuite.Trainer that parses verbose training logs for progress tracking. metrics.py wraps sklearn.metrics functions behind a decorator that flattens per-token label sequences (lists of lists) into flat lists via utils.flatten, so any sklearn classification metric applies at the token level, alongside a standalone sequence_accuracy_score for whole-sequence exact match. scorers.py exposes these as sklearn-compatible scorer callables. The whole package is essentially one adapter class plus a metrics module, so the CRF class’s predict output shape is a load-bearing contract for everything else.

Tech Stack A Python package built with legacy setuptools (setup.py, no pyproject.toml) originally targeting Python 2.7 and 3.4-3.6 per its classifiers, though still actively used against modern Python via the python-crfsuite bindings. Runtime dependencies are python-crfsuite>=0.8.3 (Cython bindings to the CRFsuite C library), tqdm>=2.0 for training progress bars, six for Python 2/3 compatibility shims, and tabulate. scikit-learn itself is kept as an optional dependency, needed only for metrics.py and scorers.py, keeping the core estimator lightweight. Testing runs through pytest and tox (tox.ini) with legacy Travis CI (.travis.yml) and codecov coverage reporting. Documentation is built with Sphinx (docs/conf.py) and hosted on Read the Docs, including a CoNLL2002 Jupyter notebook tutorial.

Code Quality The test suite (tests/test_crf.py, test_metrics.py, conftest.py) is compact but parametrizes across all five training algorithms, verifying pickle round-trips, model_filename persistence, cross-validation compatibility via cross_val_score, and post-fit attribute exposure. Error handling is minimal: fit() raises a plain ValueError only when X_dev/y_dev are mismatched, and FileResource.del deliberately swallows exceptions during cleanup, prioritizing robustness over surfacing failures. There are no type hints, no linter or formatter configuration, and CI still runs on the now-deprecated Travis platform, reflecting a project whose tooling has not kept pace with its recent (2023) compatibility fixes for scikit-learn’s clone() API.

API Design The core value proposition is exposing CRF sequence labeling entirely through the fit(X, y)/predict(X) contract scikit-learn users already know, including compatibility with GridSearchCV, cross_val_score, and Pipeline via a proper get_params/set_params-compatible estimator, despite the underlying CRFsuite library having a very different C-style stateful Trainer/Tagger API. Getting started requires minimal boilerplate: build per-token feature dicts, call fit(X, y), call predict(X); the model_filename/keep_tempfiles pairing hides on-disk crfsuite model file management behind ordinary pickling. Naming mirrors sklearn’s trailing-underscore convention for post-fit attributes (classes_, state_features_, transition_features_), which feels immediately familiar to sklearn users, though docstrings expose around twenty raw CRFsuite hyperparameters with only Sphinx-level documentation and a single tutorial notebook as a worked example.