Metadata-Version: 2.4
Name: ir_axioms
Version: 1.1.1
Summary: Axiomatic constraints for information retrieval and retrieval-augmented generation.
Author-email: Jan Heinrich Merker <heinrich.merker@uni-jena.de>, Alexander Bondarenko <alexander.bondarenko@uni-jena.de>, Maik Fröbe <maik.froebe@uni-jena.de>, Benno Stein <benno.stein@uni-weimar.de>, Michael Völske <michael.voelske@uni-weimar.de>, Matthias Hagen <matthias.hagen@uni-jena.de>, Martin Potthast <martin.potthast@uni-kassel.de>
Project-URL: Homepage, https://github.com/webis-de/ir_axioms
Project-URL: Bug Tracker, https://github.com/webis-de/ir_axioms/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types~=0.7.0
Requires-Dist: cached-property~=2.0
Requires-Dist: cyclopts<5,>=3
Requires-Dist: fasttext~=0.9.3
Requires-Dist: frozendict~=2.4
Requires-Dist: huggingface-hub[hf_xet]<1.2.0,>=0.30.1
Requires-Dist: injector~=0.22.0
Requires-Dist: ir-datasets~=0.5.9
Requires-Dist: joblib~=1.4
Requires-Dist: language-tool-python<4.0,>=2.8
Requires-Dist: more-itertools~=10.5
Requires-Dist: negspacy~=1.0
Requires-Dist: nltk~=3.9
Requires-Dist: numpy~=1.26
Requires-Dist: pandas~=2.2
Requires-Dist: python-dotenv~=1.0
Requires-Dist: rouge-score~=0.1.2
Requires-Dist: scikit-learn~=1.4
Requires-Dist: spacy~=3.7
Requires-Dist: targer-api~=1.1
Requires-Dist: textacy~=0.13.0
Requires-Dist: tqdm~=4.67
Requires-Dist: trectools~=0.0.49
Provides-Extra: tests
Requires-Dist: bandit[toml]~=1.8; extra == "tests"
Requires-Dist: mypy~=1.13; extra == "tests"
Requires-Dist: pytest<10.0,>=8.3; extra == "tests"
Requires-Dist: pytest-cov~=6.0; extra == "tests"
Requires-Dist: ruff<0.15.0,>=0.12.7; extra == "tests"
Requires-Dist: types-tqdm~=4.66; extra == "tests"
Provides-Extra: experiments
Requires-Dist: cappr[hf]~=0.9.6; extra == "experiments"
Requires-Dist: ir-measures<0.5.0,>=0.3.6; extra == "experiments"
Requires-Dist: jupyter~=1.1; extra == "experiments"
Requires-Dist: lightgbm~=4.5; extra == "experiments"
Requires-Dist: ragas~=0.3.0; extra == "experiments"
Requires-Dist: ray[data,default]~=2.48; extra == "experiments"
Requires-Dist: seaborn~=0.13.2; extra == "experiments"
Requires-Dist: transformers~=4.48; extra == "experiments"
Requires-Dist: typing-extensions~=4.12; extra == "experiments"
Requires-Dist: xgboost<4.0,>=2.1; extra == "experiments"
Provides-Extra: pyserini
Requires-Dist: pyserini<2.0,>=0.43; extra == "pyserini"
Provides-Extra: pyterrier
Requires-Dist: python-terrier~=0.13.0; extra == "pyterrier"
Provides-Extra: keybert
Requires-Dist: keybert<0.10.0,>=0.8.5; extra == "keybert"
Provides-Extra: sbert
Requires-Dist: sentence-transformers<6.0,>=4.0; extra == "sbert"
Dynamic: license-file

[![CI status](https://img.shields.io/github/actions/workflow/status/webis-de/ir_axioms/ci.yml?branch=main&style=flat-square)](https://github.com/webis-de/ir_axioms/actions/workflows/ci.yml)
[![Code coverage](https://img.shields.io/codecov/c/github/webis-de/ir_axioms?style=flat-square)](https://codecov.io/github/webis-de/ir_axioms/)
[![Maintenance](https://img.shields.io/maintenance/yes/2025?style=flat-square)](https://github.com/webis-de/ir_axioms/graphs/contributors)  
[![PyPI version](https://img.shields.io/pypi/v/ir-axioms?style=flat-square)](https://pypi.org/project/ir-axioms/)
[![PyPI downloads](https://img.shields.io/pypi/dm/ir-axioms?style=flat-square)](https://pypi.org/project/ir-axioms/)
[![Python versions](https://img.shields.io/pypi/pyversions/ir-axioms?style=flat-square)](https://pypi.org/project/ir-axioms/)  
[![Issues](https://img.shields.io/github/issues/webis-de/ir_axioms?style=flat-square)](https://github.com/webis-de/ir_axioms/issues)
[![Pull requests](https://img.shields.io/github/issues-pr/webis-de/ir_axioms?style=flat-square)](https://github.com/webis-de/ir_axioms/pulls)
[![Commit activity](https://img.shields.io/github/commit-activity/m/webis-de/ir_axioms?style=flat-square)](https://github.com/webis-de/ir_axioms/commits)
[![License](https://img.shields.io/github/license/webis-de/ir_axioms?style=flat-square)](LICENSE)

# ↕️ ir_axioms

Axiomatic constraints for information retrieval and retrieval-augmented generation.

`ir_axioms` is a Python framework for experimenting with axioms in information retrieval in a declarative way.
It includes reference implementations of many commonly used traditional retrieval axioms as well as axioms for retrieval-augmented generation.
The library is well integrated with the [PyTerrier](https://github.com/terrier-org/pyterrier) framework and supports [Pyserini](https://github.com/castorini/pyserini) retrieval indices too.
Use-cases of `ir_axioms` include search-result re-ranking, analyses of (neural) retrieval systems, and analyses of generated RAG answers.

_Note: If you're looking out for `ir_axioms`<1.0, please [go here](https://github.com/webis-de/ir_axioms/tree/legacy)._

## Publications

Read more about the [`ir_axioms` framework](https://webis.de/publications.html?q=axiom#bondarenko_2022d) and the new [RAG axioms](https://webis.de/publications.html?q=axiom#merker_2025b) in these publications:

- Alexander Bondarenko, Maik Fröbe, Jan Heinrich Reimer, Benno Stein, Michael Völske, and Matthias Hagen. [Axiomatic Retrieval Experimentation with `ir_axioms`](https://webis.de/publications.html?q=axiom#bondarenko_2022d).
- Jan Heinrich Merker, Maik Fröbe, Benno Stein, Martin Potthast, and Matthias Hagen. [Axioms for Retrieval-Augmented Generation](https://webis.de/publications.html?q=axiom#merker_2025b).

## Installation

1. Install the package from PyPI:

   ```shell
   pip install ir_axioms>=1.0
   ```

2. Install spaCy model:

   ```shell
   python -m spacy download en_core_web_sm
   ```

### Optional Dependencies

| Tag | Description |
|:--|:--|
| `pyserini` | Use index statistics, document contents, and tokenization from Pyserini/Anserini indices. |
| `pyterrier` | Use index statistics, document contents, and tokenization from PyTerrier/Terrier indices. Apply KwikSort re-ranking to PyTerrier pipelines. Run axiomatic analyses. |
| `keybert` | Use KeyBERT for aspect extraction (must be enabled manually). |
| `sbert` | Use Sentence Transformers for sentence similarity (enabled automatically). |

Note: To reproduce our results from ICTIR'25, please use these extras: `pyterrier,keybert,sbert`

## Usage

Run the CLI with:

```shell
ir_axioms --help
```

## Development

1. Install [Python 3.11](https://python.org/downloads/) or later.
2. Create and activate a virtual environment:

   ```shell
   python3 -m venv venv/
   source venv/bin/activate
   ```

3. Install project dependencies:

   ```shell
   pip install -e .[tests]
   ```

4. Install spaCy model:

   ```shell
   python -m spacy download en_core_web_sm
   ```

5. After having implemented a new feature, please check the code format, inspect common LINT errors, and run all unit tests with the following commands:

   ```shell
   ruff check .                   # Code format and LINT
   mypy .                         # Static typing
   bandit -c pyproject.toml -r .  # Security
   pytest .                       # Unit tests
   ```

## Contribute

If you have found an important feature missing from our tool, please suggest it by creating an [issue](https://github.com/webis-de/ir_axioms/issues). We also gratefully accept [pull requests](https://github.com/webis-de/ir_axioms/pulls)!

If you are unsure about anything, post an [issue](https://github.com/webis-de/ir_axioms/issues/new) or contact us:

- [heinrich.merker@uni-jena.de](mailto:heinrich.merker@uni-jena.de)

We are happy to help!

## License

This repository is released under the [MIT license](LICENSE).
Files in the `data/` directory are exempt from this license.
