Metadata-Version: 2.4
Name: pyhighlights
Version: 0.1.0
Summary: A simple library implementing Select-Then-Predict (SPP) models.
Author-email: Federico Ruggeri <federico.ruggeri6@unibo.it>
License-Expression: MIT
Project-URL: Homepage, https://github.com/federicoruggeri/pyhighlights
Project-URL: Documentation, https://federicoruggeri.github.io/pyhighlights/
Project-URL: Source, https://github.com/federicoruggeri/pyhighlights
Project-URL: Issues, https://github.com/federicoruggeri/pyhighlights/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cinnamon-core<3,>=2.0.0
Requires-Dist: lightning>=2.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: torchmetrics>=1.0.0
Provides-Extra: transformers
Requires-Dist: transformers>=4.0.0; extra == "transformers"
Provides-Extra: dev
Requires-Dist: nox>=2024.3.2; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.15.20; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Dynamic: license-file

# pyhighlights

[![Tests](https://github.com/federicoruggeri/pyhighlights/actions/workflows/ci.yml/badge.svg)](https://github.com/federicoruggeri/pyhighlights/actions/workflows/ci.yml)
[![Documentation](https://github.com/federicoruggeri/pyhighlights/actions/workflows/docs.yml/badge.svg)](https://federicoruggeri.github.io/pyhighlights/)
[![PyPI](https://img.shields.io/pypi/v/pyhighlights)](https://pypi.org/project/pyhighlights/)

Research library for highlight-based explainable AI models.

[Documentation](https://federicoruggeri.github.io/pyhighlights/) · [Contributing](CONTRIBUTING.md)

## Installation

```bash
pip install pyhighlights
```

Use `pip install "pyhighlights[transformers]"` for Transformer backends.

## GRU folded rationalization

```python
from pathlib import Path

import pyhighlights
from cinnamon.registry import Registry
from pyhighlights.configurations.spp import (
    GRU_FR,
    GRU_GRAT,
    GRU_MCD,
    GRU_MGR,
    TRANSFORMER_FR,
)

Registry.build(directory=Path(pyhighlights.__file__).parent)
fr = Registry.from_key(GRU_FR)
mgr = Registry.from_key(GRU_MGR)
mcd = Registry.from_key(GRU_MCD)
grat = Registry.from_key(GRU_GRAT)
transformer_fr = Registry.from_key(TRANSFORMER_FR)  # needs pyhighlights[transformers]
```

GRU and Transformer implementations conform to same backbone interface; model
classes contain rationalization logic only.

## Highlight data

```python
from torch.utils.data import DataLoader
from pyhighlights.components import (
    HighlightCollator,
    HighlightDataset,
    HighlightExample,
    VocabularyTokenizer,
)

examples = HighlightDataset([
    HighlightExample(0, ["great", "stay"], label=1, highlights=[1, 0]),
    HighlightExample(1, ["bad"], label=0),  # unlabeled highlights become -1
])
collator = HighlightCollator(VocabularyTokenizer({"great": 1, "stay": 2, "bad": 3}))
batch = next(iter(DataLoader(examples, batch_size=2, collate_fn=collator)))
```

`HuggingFaceTokenizer` expands word highlights across subtokens and requires
`pyhighlights[transformers]`.
