Metadata-Version: 2.4
Name: ir_axioms
Version: 1.2.5
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: frozendict~=2.4
Requires-Dist: injector<0.25,>=0.22
Requires-Dist: ir-datasets<0.7.0,>=0.5.9
Requires-Dist: joblib~=1.4
Requires-Dist: language-tool-python~=3.4
Requires-Dist: more-itertools~=10.5
Requires-Dist: negspacy~=1.0
Requires-Dist: nltk~=3.9
Requires-Dist: numpy~=1.26
Requires-Dist: pandas<4.0,>=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<3.0,>=1.13; extra == "tests"
Requires-Dist: pytest<10.0,>=8.3; extra == "tests"
Requires-Dist: pytest-cov<8,>=6; extra == "tests"
Requires-Dist: ruff<0.15.0,>=0.12.7; extra == "tests"
Requires-Dist: types-tqdm~=4.66; extra == "tests"
Provides-Extra: docs
Requires-Dist: mkdocs~=1.6; extra == "docs"
Requires-Dist: mkdocs-material~=9.6; extra == "docs"
Requires-Dist: mkdocs-redirects~=1.2; extra == "docs"
Requires-Dist: mkdocs-webis~=0.1.2; extra == "docs"
Requires-Dist: mkdocstrings[python]~=1.0; extra == "docs"
Requires-Dist: ruff<0.15.0,>=0.12.7; extra == "docs"
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<6.0,>=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: pyterrier~=1.0; extra == "pyterrier"
Provides-Extra: keybert
Requires-Dist: keybert<0.10.0,>=0.8.5; extra == "keybert"
Provides-Extra: sbert
Requires-Dist: sentence-transformers~=5.7; extra == "sbert"
Provides-Extra: model2vec
Requires-Dist: model2vec~=0.9.0; extra == "model2vec"
Provides-Extra: blingfire
Requires-Dist: blingfire~=0.1.8; extra == "blingfire"
Provides-Extra: fasttext
Requires-Dist: fasttext~=0.9.3; extra == "fasttext"
Requires-Dist: huggingface-hub[hf_xet]<1.5.0,>=0.30.1; extra == "fasttext"
Provides-Extra: autojudge
Requires-Dist: autojudge-base~=1.0; extra == "autojudge"
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/)
[![Documentation](https://img.shields.io/github/actions/workflow/status/webis-de/ir_axioms/docs.yml?branch=main&style=flat-square&label=docs)](https://ir-axioms.webis.de/)
[![Maintenance](https://img.shields.io/maintenance/yes/2026?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](https://ir-axioms.webis.de/axioms/) as well as [axioms for retrieval-augmented generation](https://ir-axioms.webis.de/axioms/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](https://ir-axioms.webis.de/walkthroughs/kwiksort/), [analyses of (neural) retrieval systems](https://ir-axioms.webis.de/walkthroughs/post-hoc-analysis/), and [analyses of generated RAG answers](https://ir-axioms.webis.de/walkthroughs/rag-evaluation/).

Refer to the `ir_axioms` [documentation](https://ir-axioms.webis.de/) for:

- [Installation](https://ir-axioms.webis.de/getting-started/installation/) and a [quickstart](https://ir-axioms.webis.de/getting-started/quickstart/)
- [Axiom intuitions, formalizations, and implementations](https://ir-axioms.webis.de/axioms/)
- [Related information retrieval literature](https://ir-axioms.webis.de/axioms/related/)
- [Walkthroughs](https://ir-axioms.webis.de/walkthroughs/) on re-ranking, post-hoc analyses, and RAG evaluation
- [Instructions for developing new axioms](https://ir-axioms.webis.de/development/axiom-development/)

## TL;DR

To get started without reading the [documentation](https://ir-axioms.webis.de/), follow these steps:

1. Install the package from [PyPI](https://pypi.org/project/ir-axioms/):

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

2. Install a spaCy model:

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

3. Load and combine axioms:

   ```python
   from ir_axioms.axiom import TFC1, PROX1, ORIG

   axiom = (TFC1() & PROX1()) | ORIG()
   ```

4. Define some test data:

   ```python
   from ir_axioms.model import Query, Document

   query = Query(id="q1", text="axiomatic information retrieval")
   documents = [
      Document(id="d1", text="Retrieval axioms formalize constraints for retrieval models.", rank=1),
      Document(id="d2", text="Axiomatic information retrieval: axiomatic constraints guide retrieval.", rank=2),
   ]
   ```

5. Compute axiom preferences or re-rank documents:

   ```python
   axiom.preferences(input=query, outputs=documents)
   axiom.rerank_kwiksort(input=query, ranking=documents)
   ```

## 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)!
Get started by following our [development guides](https://ir-axioms.webis.de/development/).

## License

This repository is released under the [MIT license](LICENSE).
Files in the `data/` directory are exempt from this license.
If you use `ir_axioms` in your research, consider [citing us](https://ir-axioms.webis.de/#references).
